Google Firestore: implement agent demonstrating session persistence using Firestore database for java adk

Author: mohan-ganesh

docs/integrations/assets/firestore-session.png

@@ -0,0 +1,166 @@
+---
+catalog_title: Session Management with Firestore
+catalog_description: Session state management for ADK agents using Google Cloud Firestore
+catalog_icon: /integrations/assets/firestore-session.png
+catalog_tags: ["sessions", "database"]
+---
+
+# Session Management with Google Cloud Firestore
+
+<div class="language-support-tag">
+  <span class="lst-supported">Supported in ADK</span><span class="lst-java">Java</span>
+</div>
+
+[Google Cloud Firestore](https://cloud.google.com/firestore) is a flexible, scalable NoSQL cloud database to store and sync data for client- and server-side development. 
+ADK provides a native integration for managing persistent agent session states using Firestore, allowing continuous multi-turn conversations without losing conversation history.
+
+## Prerequisites
+
+- A [Google Cloud Project](https://cloud.google.com/) with Firestore enabled
+- A [Firestore database](https://cloud.google.com/firestore/docs/setup) in your Google Cloud Project
+- Appropriate [Google Cloud credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) configured in your environment
+
+## Install dependencies
+
+Add the following dependencies to your `pom.xml` (Maven) or `build.gradle` (Gradle):
+
+### Maven
+
+```xml
+<dependencies>
+    <!-- ADK Core -->
+    <dependency>
+        <groupId>com.google.adk</groupId>
+        <artifactId>google-adk</artifactId>
+        <version>1.0.0</version>
+    </dependency>
+    <!-- Firestore Session Service -->
+    <dependency>
+        <groupId>com.google.adk</groupId>
+        <artifactId>google-adk-firestore-session-service</artifactId>
+        <version>1.0.0</version>
+    </dependency>
+</dependencies>
+```
+
+### Gradle
+
+```gradle
+dependencies {
+    // ADK Core
+    implementation 'com.google.adk:google-adk:1.0.0-SNAPSHOT'
+    // Firestore Session Service
+    implementation 'com.google.adk:google-adk-firestore-session-service:1.0.0-SNAPSHOT'
+}
+```
+
+## Example: Agent with Firestore Session Management
+
+Use `FirestoreDatabaseRunner` to encapsulate your agent and Firestore-backed session management. Here is a complete example of setting up a simple assistant agent that remembers conversation context across turns using a custom session ID.
+
+```java
+import com.google.adk.agents.BaseAgent;
+import com.google.adk.agents.LlmAgent;
+import com.google.adk.agents.RunConfig;
+import com.google.adk.runner.FirestoreDatabaseRunner;
+import com.google.cloud.firestore.Firestore;
+import com.google.cloud.firestore.FirestoreOptions;
+import io.reactivex.rxjava3.core.Flowable;
+import java.util.Map;
+import com.google.adk.sessions.FirestoreSessionService;
+import com.google.adk.sessions.Session;
+import com.google.adk.tools.Annotations.Schema;
+import com.google.adk.tools.FunctionTool;
+import com.google.genai.types.Content;
+import com.google.genai.types.Part;
+import com.google.adk.events.Event;
+import java.util.Scanner;
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+public class YourAgentApplication {
+
+    public static void main(String[] args) {
+        System.out.println("Starting YourAgentApplication...");
+
+        RunConfig runConfig = RunConfig.builder().build();
+        String appName = "hello-time-agent";
+
+        BaseAgent timeAgent = initAgent();
+        
+        // Initialize Firestore
+        FirestoreOptions firestoreOptions = FirestoreOptions.getDefaultInstance();
+        Firestore firestore = firestoreOptions.getService();
+
+        // Use FirestoreDatabaseRunner to persist session state
+        FirestoreDatabaseRunner runner = new FirestoreDatabaseRunner(
+                timeAgent,
+                appName,
+                firestore
+        );
+
+        // Create a new session or load an existing one
+        Session session = new FirestoreSessionService(firestore)
+                .createSession(appName, "user1234", null, "12345")
+                .blockingGet();
+
+        // Start interactive CLI
+        try (Scanner scanner = new Scanner(System.in, UTF_8)) {
+            while (true) {
+                System.out.print("\\nYou > ");
+                String userInput = scanner.nextLine();
+                if ("quit".equalsIgnoreCase(userInput)) {
+                    break;
+                }
+
+                Content userMsg = Content.fromParts(Part.fromText(userInput));
+                Flowable<Event> events = runner.runAsync(session.userId(), session.id(), userMsg, runConfig);
+
+                System.out.print("\\nAgent > ");
+                events.blockingForEach(event -> {
+                    if (event.finalResponse()) {
+                        System.out.println(event.stringifyContent());
+                    }
+                });
+            }
+        }
+    }
+
+    /** Mock tool implementation */
+    @Schema(description = "Get the current time for a given city")
+    public static Map<String, String> getCurrentTime(
+        @Schema(name = "city", description = "Name of the city to get the time for") String city) {
+        return Map.of(
+            "city", city,
+            "forecast", "The time is 10:30am."
+        );
+    }
+    
+    private static BaseAgent initAgent() {
+        return LlmAgent.builder()
+            .name("hello-time-agent")
+            .description("Tells the current time in a specified city")
+            .instruction(\"""
+                You are a helpful assistant that tells the current time in a city.
+                Use the 'getCurrentTime' tool for this purpose.
+                \""")
+            .model("gemini-3.1-pro-preview")
+            .tools(FunctionTool.create(YourAgentApplication.class, "getCurrentTime"))
+            .build();
+    }
+}
+```
+
+## Configuration
+
+> [!NOTE]
+> The Firestore Session Service supports properties file configuration. This allows you to easily target a dedicated Firestore database and define custom collection names for storing your agent session data.
+
+
+## Resources
+
+- [Firestore Session Service](https://github.com/google/adk-java/tree/main/contrib/firestore-session-service): 
+  Source code for the Firestore Session Service.
+- [Spring Boot Google ADK + Firestore Example](https://github.com/mohan-ganesh/spring-boot-google-adk-firestore): 
+  An example project demonstrating how to build a Java-based Google ADK agent application using Cloud Firestore for session management.
+- [Firestore Session Service - DeepWiki](https://deepwiki.com/google/adk-java/4.3-firestore-session-service): 
+  Detailed description of Firestore integration in the Google ADK for Java.