Designing for Context Preservation and Resume Capabilities

In the realm of AI agents, a critical challenge arises when agents need to perform long-running tasks or maintain complex interactions over extended periods: how do they remember what happened, and how can they pick up exactly where they left off after an interruption? This chapter addresses that challenge head-on. We’ll design and implement a robust mechanism for our Google ADK agent to preserve its state and conversational context, enabling it to pause, resume, and recover from failures without losing valuable information.

By the end of this milestone, your ADK agent will be able to store its internal memory and conversational history in a durable external database. This means you can stop the agent, restart it later (even on a different machine), and it will seamlessly recall its previous interactions and internal state, crucial for building production-grade, reliable AI applications.

Project Overview

This chapter focuses on a core component of production-ready AI agents: persistent state and context management. We aim to build an ADK agent that can maintain its operational memory and conversational history across restarts. The target user is any developer building interactive, multi-turn AI applications that require continuity, such as customer support agents, personal assistants, or workflow automation tools.

Success for this milestone means:

• The agent can start, process messages, and save its state to a database.
• Upon a simulated restart (new agent instance, same session ID), the agent loads its previous state and continues the conversation as if uninterrupted.
• The system demonstrates reliable state saving and loading, visible both in application logs and the external database.

Tech Stack for Persistence

To achieve durable state management for our ADK agent, we will leverage the following technologies:

• Python (3.12+): The primary language for our agent and state management logic. We recommend using the latest stable Python 3.x version.
• Google ADK (Agent Development Kit): The framework for building our AI agent. (Note: Specific version information for Google ADK is not publicly available as of 2026-05-23. We will proceed with general ADK integration principles.)
• Google Cloud Firestore: Our chosen NoSQL document database for persisting agent state and conversational context. Its flexible schema and scalability make it suitable for dynamic agent data.
• Google Cloud IAM: For secure authentication and authorization of our agent to access Firestore.

Milestones for Context Preservation

We’ll break down the implementation into these actionable steps:

1. Understand Agent State: Clearly define what constitutes “state” and “context” for a long-running agent.
2. Choose a Durable Store: Select an appropriate external database for persistence (Firestore).
3. Design Data Model: Structure how agent state will be stored in Firestore.
4. Implement StateManager: Create a Python module to abstract Firestore interactions (save, load, delete).
5. Integrate with ADK Agent: Modify the ADK agent to use the StateManager for loading state on startup and saving state after significant actions.
6. Verify Persistence: Test the agent’s ability to pause, restart, and resume conversations correctly.

Understanding Agent State and Context

Before diving into implementation, it’s vital to differentiate between an agent’s transient session memory and its persistent, long-term state.

• Session Memory: This typically refers to the short-term conversational history that an agent framework (like ADK) manages during a single interaction session. It’s often in-memory and lost when the agent process restarts. This is sufficient for simple, one-off queries, but not for complex workflows.

• Persistent State and Context: This is the information we want to save and load across sessions or system restarts. It includes:

  • Conversational Context: The entire chat history, including user inputs and agent responses, often structured to feed back into the LLM.
  • Agent Internal State: Any variables, flags, or data points specific to the agent’s current task or workflow. This could be the outcome of a tool call, a pending user confirmation, or the current step in a multi-step process.
  • Tool State: Information related to external tools the agent uses, such as an API call’s response that needs to be processed later.

📌 Key Idea: For a long-running agent to be truly resilient, it must externalize and persist this critical state and context beyond its immediate runtime memory.

Architectural Choices for Persistence

To achieve persistence, we need an external data store. The choice of store depends on your project’s specific requirements for data structure, scalability, performance, and cost.

Data Store Options

Here’s a comparison of common Google Cloud options:

For this project, we’ll choose Firestore. Its document-oriented, NoSQL nature is well-suited for storing flexible agent states and conversational histories, which often don’t fit a rigid relational schema. It also offers excellent scalability and is fully managed, reducing operational overhead.

State Management Architecture

Our agent will interact with a dedicated StateManager component. This component will abstract away the details of the chosen database, providing a clean interface for the agent to save and load its state.

Explanation of the Flow:

1. User Interaction: The user sends a message to the ADK agent.
2. Agent Application: The ADK agent processes the message, potentially using tools or internal logic.
3. State Manager: Before processing or after a significant step, the agent calls the StateManager to load its previous state or save its current state.
4. Firestore Database: The StateManager interacts directly with Firestore, reading or writing documents that represent the agent’s state and context.

Data Model for Firestore

We’ll store each agent’s state as a single document in a Firestore collection (e.g., agent_states). The document ID will be unique to each agent instance (e.g., a session ID or a user ID).

A state document might look like this:

{
  "session_id": "user-123",
  "last_updated": "2026-05-23T10:30:00Z",
  "conversation_history": [
    {
      "role": "user",
      "content": "What's the weather like?"
    },
    {
      "role": "agent",
      "content": "Which city are you interested in?"
    }
  ],
  "agent_variables": {
    "current_city_query": "London",
    "last_tool_call_result": {
      "tool": "weather_api",
      "status": "success",
      "data": {}
    },
    "step_in_workflow": "awaiting_city_confirmation"
  }
}

This structure allows for a flexible conversation_history array and an agent_variables dictionary to hold any custom data the agent needs. This approach minimizes Firestore operations by keeping all related state for a single agent instance within one document.

Step-by-Step Implementation

We’ll integrate Firestore into our ADK agent.

Prerequisites

1. Python 3.12+: Ensure you have the latest stable Python 3.x installed.
2. Google Cloud Project: Ensure you have an active Google Cloud project.
3. Firestore API Enabled: In your Google Cloud project, navigate to “APIs & Services” -> “Enabled APIs & Services” and ensure “Cloud Firestore API” is enabled.
4. Service Account: For local development, create a service account key and download it. For deployment, use Google Cloud’s default service account or dedicated IAM roles.
   • Go to “IAM & Admin” -> “Service Accounts” -> “Create Service Account”.
   • Grant it the “Cloud Datastore User” or “Cloud Datastore Editor” role (Firestore uses the same underlying service).
   • Create a new JSON key and save it as service_account_key.json in your project root or a secure location.
   • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of this key file.

1. Install Firestore Client Library

First, install the Python client library for Google Cloud Firestore.

pip install google-cloud-firestore==2.17.0  # Checked 2024-05-23

⚡ Quick Note: The specified version 2.17.0 is current as of 2024-05-23. Always check the official google-cloud-firestore PyPI page for the absolute latest stable release as of your development date (2026-05-23).

2. Create a StateManager Module

Let’s create state_manager.py to handle all interactions with Firestore. This module will encapsulate all database logic, keeping our agent code clean and focused on AI logic.

Create a file named state_manager.py in your project root:

# project_root/state_manager.py
import os
from datetime import datetime
from typing import Dict, Any
from google.cloud import firestore

class StateManager:
    """Manages persistence of agent state and conversational context using Firestore."""

    def __init__(self, project_id: str, collection_name: str = "agent_states"):
        """
        Initializes the StateManager.

        Args:
            project_id: Your Google Cloud Project ID.
            collection_name: The Firestore collection to store agent states.
        """
        self.db = firestore.Client(project=project_id)
        self.collection_ref = self.db.collection(collection_name)
        print(f"StateManager initialized for project '{project_id}', collection '{collection_name}'")

    def load_state(self, agent_id: str) -> Dict[str, Any]:
        """
        Loads the agent's state from Firestore.

        Args:
            agent_id: A unique identifier for the agent instance (e.g., session ID).

        Returns:
            A dictionary representing the agent's state, or an empty dict if not found.
        """
        try:
            doc_ref = self.collection_ref.document(agent_id)
            doc = doc_ref.get()
            if doc.exists:
                state = doc.to_dict()
                print(f"State loaded for agent '{agent_id}'. Last updated: {state.get('last_updated')}")
                return state
            print(f"No existing state found for agent '{agent_id}'. Returning empty state.")
            return {}
        except Exception as e:
            print(f"Error loading state for agent '{agent_id}': {e}")
            return {} # Return empty state on error

    def save_state(self, agent_id: str, state: Dict[str, Any]):
        """
        Saves the agent's current state to Firestore.

        Args:
            agent_id: A unique identifier for the agent instance.
            state: The dictionary representing the agent's current state.
        """
        try:
            state["last_updated"] = datetime.now().isoformat()
            doc_ref = self.collection_ref.document(agent_id)
            doc_ref.set(state) # Firestore automatically creates/overwrites
            print(f"State saved for agent '{agent_id}' at {state['last_updated']}")
        except Exception as e:
            print(f"Error saving state for agent '{agent_id}': {e}")

    def delete_state(self, agent_id: str):
        """
        Deletes an agent's state from Firestore.

        Args:
            agent_id: A unique identifier for the agent instance.
        """
        try:
            doc_ref = self.collection_ref.document(agent_id)
            doc_ref.delete()
            print(f"State deleted for agent '{agent_id}'")
        except Exception as e:
            print(f"Error deleting state for agent '{agent_id}': {e}")

# Example usage (for testing, not part of agent.py)
if __name__ == "__main__":
    # Ensure GOOGLE_APPLICATION_CREDENTIALS is set in your environment
    # export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service_account_key.json"
    # export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

    project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
    if not project_id:
        raise ValueError("Environment variable GOOGLE_CLOUD_PROJECT not set. Please configure your GCP project ID.")

    sm = StateManager(project_id)
    test_agent_id = "test_user_session_123"

    print("\n--- Initial Load ---")
    initial_state = sm.load_state(test_agent_id)
    print(f"Initial state: {initial_state}")

    print("\n--- Saving New State ---")
    new_state = {
        "conversation_history": [
            {"role": "user", "content": "Hello there!"},
            {"role": "agent", "content": "Hi! How can I help you?"}
        ],
        "agent_variables": {
            "user_name": "Alice",
            "task_status": "greeting_complete"
        }
    }
    sm.save_state(test_agent_id, new_state)

    print("\n--- Loading State After First Save ---")
    loaded_state = sm.load_state(test_agent_id)
    print(f"Loaded state: {loaded_state}")

    print("\n--- Updating State ---")
    loaded_state["conversation_history"].append({"role": "user", "content": "What time is it?"})
    loaded_state["agent_variables"]["task_status"] = "awaiting_time_query"
    sm.save_state(test_agent_id, loaded_state)

    print("\n--- Loading State After Update ---")
    updated_loaded_state = sm.load_state(test_agent_id)
    print(f"Updated loaded state: {updated_loaded_state}")

    print("\n--- Deleting State ---")
    sm.delete_state(test_agent_id)

    print("\n--- Verifying Deletion ---")
    final_state = sm.load_state(test_agent_id)
    print(f"State after deletion: {final_state}")

Explanation:

• StateManager Class: This class encapsulates the logic for interacting with Firestore. It’s initialized with your Google Cloud project_id and a collection_name (defaulting to agent_states).
• __init__: Sets up the firestore.Client, which handles authentication using the GOOGLE_APPLICATION_CREDENTIALS environment variable (or instance metadata in Google Cloud environments).
• load_state(agent_id): This method attempts to retrieve a document from the specified collection using agent_id as the document identifier. If the document exists, its contents are returned as a Python dictionary. If not, an empty dictionary is returned, signaling a new session. Basic error handling is included.
• save_state(agent_id, state): This method writes the provided state dictionary to Firestore. It automatically adds a last_updated timestamp. Firestore intelligently handles creation if the document doesn’t exist or overwrites it if it does, ensuring the state is always current. Error handling is included.
• delete_state(agent_id): Provides a way to clean up an agent’s state, useful for ending sessions or testing.
• if __name__ == "__main__": block: This block serves as a self-contained unit test for the StateManager. Running this script directly will demonstrate loading, saving, updating, and deleting states in your Firestore project. Remember to set your GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT environment variables before running it.

3. Integrate StateManager into Your ADK Agent

Now, let’s modify our ADK agent (assuming you have a basic agent setup from previous chapters) to use the StateManager. We’ll focus on how to load state when the agent starts and save state after each significant interaction.

For simplicity, we’ll assume a single AGENT_SESSION_ID for demonstration. In a real application, this agent_id would typically map to a unique user session, a specific long-running task identifier, or even a channel ID.

Create a file named my_adk_agent.py in your project root:

# project_root/my_adk_agent.py
import os
from typing import Dict, Any, List
from adk.agent import Agent, AgentConfig, Message
from adk.tool import Tool
from adk.event import Event
from adk.llm import LLMConfig
# Assuming state_manager.py is in the same directory
from state_manager import StateManager

# --- Agent Configuration ---
GCP_PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not GCP_PROJECT_ID:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set. Please configure your GCP project ID.")

# This could be a session ID, user ID, or task ID - crucial for state persistence
AGENT_SESSION_ID = "my-unique-agent-session-001"

# --- Define a simple tool (optional, for context) ---
class GreetingTool(Tool):
    def __init__(self):
        super().__init__(
            name="greeting_tool",
            description="A tool to greet the user and remember their name.",
            input_schema={
                "type": "object",
                "properties": {
                    "name": {"type": "string", "description": "The user's name"},
                },
                "required": ["name"],
            },
        )

    def run(self, input: Dict[str, Any]) -> str:
        name = input.get("name", "there")
        return f"Hello, {name}! It's nice to meet you."

# --- Define the ADK Agent ---
class PersistentAgent(Agent):
    def __init__(self, config: AgentConfig, state_manager: StateManager):
        super().__init__(config)
        self.state_manager = state_manager
        self.agent_id = AGENT_SESSION_ID # In a real app, this would be passed dynamically

        # Load initial state when the agent is initialized
        self.state = self.state_manager.load_state(self.agent_id)
        if not self.state:
            # Initialize with default values if no state was loaded (first run)
            self.state = {
                "conversation_history": [],
                "agent_variables": {
                    "user_name": None,
                    "greeting_done": False
                }
            }
        print(f"Agent '{self.agent_id}' initialized with state: {self.state}")

    def on_init(self) -> None:
        """Called once when the agent is initialized.
        State is already loaded in __init__ for immediate availability."""
        print(f"Agent '{self.agent_id}' on_init hook called.")
        pass

    def on_message(self, message: Message) -> Event:
        """Processes an incoming message, updates state, and saves it."""
        print(f"Agent '{self.agent_id}' received message: {message.text}")

        # Add user message to conversation history
        self.state["conversation_history"].append({"role": "user", "content": message.text})

        response_text = ""

        # Example: Use a tool and update agent variables based on current state
        if "hello" in message.text.lower() and not self.state["agent_variables"]["greeting_done"]:
            # In a real agent, LLM would extract the name
            name_match = "User" # For simplicity in this example
            
            tool_output = self.call_tool("greeting_tool", {"name": name_match})
            response_text = tool_output
            self.state["agent_variables"]["user_name"] = name_match
            self.state["agent_variables"]["greeting_done"] = True
        elif self.state["agent_variables"]["user_name"]:
            response_text = f"Hello again, {self.state['agent_variables']['user_name']}! You said: '{message.text}'"
        else:
            # Simulate an LLM response based on history (ADK's default behavior)
            # In a real scenario, you'd use self.llm.generate_response(messages=self.state["conversation_history"])
            response_text = f"You said: '{message.text}'. Current state (vars): {self.state['agent_variables']}"

        # Add agent response to conversation history
        self.state["conversation_history"].append({"role": "agent", "content": response_text})

        # Save the updated state after processing the message
        self.state_manager.save_state(self.agent_id, self.state)
        
        # Return the agent's response
        return Event(text=response_text)

    def on_tool_call_result(self, tool_name: str, tool_input: Dict[str, Any], tool_output: str) -> None:
        """Called after a tool call completes.
        You might save state here if tool calls are critical checkpoints."""
        print(f"Tool '{tool_name}' called with input '{tool_input}', result: '{tool_output}'")
        # self.state_manager.save_state(self.agent_id, self.state) # Optional save point
        pass

# --- Main execution block ---
if __name__ == "__main__":
    # Initialize the StateManager
    state_manager = StateManager(project_id=GCP_PROJECT_ID)

    # Configure the ADK agent. Use a placeholder LLM config.
    agent_config = AgentConfig(
        llm=LLMConfig(
            model_name="gemini-pro", # Use an appropriate model for your region/project
            temperature=0.7,
        ),
        tools=[GreetingTool()], # Register our custom tool
        # Add other configurations as needed
    )

    print("\n--- Simulating first session (Agent Instance 1) ---")
    # Instantiate the persistent agent
    persistent_agent = PersistentAgent(config=agent_config, state_manager=state_manager)

    # Simulate an incoming message
    first_message = Message(text="Hello, my name is User!")
    persistent_agent.on_message(first_message)

    second_message = Message(text="How are you today?")
    persistent_agent.on_message(second_message)

    print("\n--- Simulating agent restart (Agent Instance 2, same session ID) ---")
    # In a real scenario, the old process would die, and a new one would start.
    # We simulate this by creating a new agent instance with the same AGENT_SESSION_ID.
    restarted_agent = PersistentAgent(config=agent_config, state_manager=state_manager)
    third_message = Message(text="Can you remind me what my name is?")
    restarted_agent.on_message(third_message)

    print("\n--- Simulating another message in the restarted session ---")
    fourth_message = Message(text="What else can you do?")
    restarted_agent.on_message(fourth_message)

    print("\n--- Final state after all interactions (retrieved directly from DB) ---")
    final_state_from_db = state_manager.load_state(AGENT_SESSION_ID)
    print(f"Final state from DB: {final_state_from_db}")

    # Optional: Clean up state for next run or if the session is truly over
    # print("\n--- Deleting agent state for cleanup ---")
    # state_manager.delete_state(AGENT_SESSION_ID)

Explanation of Agent Integration:

1. StateManager Import: We import our StateManager class into the main agent file.
2. PersistentAgent Class:
   • __init__: Takes a state_manager instance. Crucially, it calls self.state_manager.load_state(self.agent_id) right at the start. If no state is found (e.g., first interaction for this agent_id), it initializes a default empty state. This ensures the agent always starts with its last known context if available, or a clean slate otherwise.
   • on_message:
     • Appends the incoming user message to self.state["conversation_history"].
     • Performs some example logic (e.g., calling a greeting_tool and updating agent_variables). Notice how self.state["agent_variables"]["greeting_done"] is used to prevent repeated greetings, demonstrating stateful logic.
     • Appends the agent’s response to self.state["conversation_history"].
     • self.state_manager.save_state(self.agent_id, self.state): This is the critical line. After every significant interaction (here, after processing a message and formulating a response), the agent’s entire self.state dictionary is saved to Firestore. This makes the agent’s progress durable.
3. Main Execution Block:
   • Initializes the StateManager with your GCP project ID.
   • Configures the ADK agent with an LLM and our GreetingTool.
   • Simulates First Session: persistent_agent handles initial messages, saving its state after each.
   • Simulates Restart: A new PersistentAgent instance (restarted_agent) is created using the same AGENT_SESSION_ID. When restarted_agent initializes, it automatically loads the state that persistent_agent had saved to Firestore, demonstrating the core resume capability.
   • Further messages are processed by restarted_agent, and its updated state is saved, proving continuity.
   • Finally, the state is loaded directly from the database to show its final persistent form.

Testing & Verification

To confirm your persistent agent is working as expected, follow these verification steps:

1. Set Environment Variables: Open your terminal and set the required environment variables:

   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service_account_key.json"
   export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

   Replace /path/to/your/service_account_key.json with the actual path to your downloaded service account key, and your-gcp-project-id with your Google Cloud project ID.

2. Run the Agent Script: Execute the agent application:

   python my_adk_agent.py

3. Observe Console Output: Carefully review the output in your terminal:

   • Look for StateManager initialized... messages at the start.
   • When the first agent instance starts, you should see No existing state found... initially, followed by State saved... messages after each message processing.
   • When the “restarted” agent instance starts, you should see State loaded for agent 'my-unique-agent-session-001'. Last updated:... messages, indicating it successfully retrieved the previous state.
   • Verify that the responses from the restarted_agent acknowledge previous interactions, for example, by recalling the user’s name.
   • The “Final state from DB” output should show the complete conversation_history and agent_variables from all simulated interactions.

4. Inspect Firestore Console:

   • Go to the Google Cloud Console and navigate to “Firestore Database”.
   • You should see a collection named agent_states (or whatever collection_name you used in StateManager).
   • Inside this collection, you’ll find a document with the ID my-unique-agent-session-001.
   • Inspect the document’s content. You should see the conversation_history, agent_variables, and last_updated fields reflecting the latest state of your agent after all interactions.
   • Verification Challenge: Try deleting the my-unique-agent-session-001 document in the Firestore console, then run my_adk_agent.py again. Observe that the agent now starts from a fresh state (No existing state found...) and the conversation history begins anew. This confirms the persistence mechanism is working as intended.

Production Considerations

Building a robust persistence layer requires more than just saving and loading data. Consider these factors for a production environment:

• Concurrency and Race Conditions: If multiple instances of the same agent_id could write state concurrently (e.g., if you have multiple user interactions happening simultaneously for the same agent), you need to handle race conditions. Firestore offers transactions for atomic read-modify-write operations, which are crucial for ensuring data consistency.
• Error Handling and Retries: What happens if the Firestore service is temporarily unavailable? Implement robust try-except blocks around db operations and consider retry mechanisms (e.g., with exponential backoff) to make your agent resilient to transient network issues or service outages.
• Security (IAM): Never embed service account keys directly into your deployed application code.
  • Google Cloud Run/GKE: Use the default service account associated with the compute instance or container. Grant this service account the minimum necessary IAM roles (e.g., roles/datastore.user for read/write access to Firestore).
  • Local Development: Use the GOOGLE_APPLICATION_CREDENTIALS environment variable, which points to your service account key file.
  • Ensure any sensitive information stored in the agent’s state (e.g., API keys, user PII) is encrypted, either before storage or by using a service like Google Secret Manager.
• Performance and Scalability:
  • Indexing: For complex queries on your state documents (e.g., searching for agents by specific agent_variables), ensure appropriate Firestore indexes are configured to maintain performance.
  • Document Size: Keep individual state documents reasonably sized (Firestore has a 1MB limit per document). If your conversation history grows excessively large, consider archiving older parts or storing them in a separate, cheaper storage solution like Cloud Storage.
  • Read/Write Operations: Be mindful of Firestore’s pricing model, which charges per document read, write, and delete. Optimize your save_state calls to only persist when absolutely necessary (e.g., after a tool call, or a critical user confirmation, not after every single token generated by the LLM).
• Schema Evolution: As your agent’s capabilities grow, its internal state structure might change. Plan for schema migrations or design your agent_variables to be flexible enough to handle new fields without breaking existing state documents.

Common Issues & Solutions

1. google.auth.exceptions.DefaultCredentialsError:
   • Issue: The Firestore client cannot find your Google Cloud credentials.
   • Solution: Ensure the GOOGLE_APPLICATION_CREDENTIALS environment variable points to your service account key JSON file, or that your execution environment (e.g., Cloud Run) has a service account with appropriate permissions. Double-check the project_id passed to firestore.Client.
2. State Not Persisting/Loading Correctly:
   • Issue: After restarting the agent, the state doesn’t reflect previous interactions.
   • Solution:
     • Verify the agent_id is consistent across saves and loads. A common mistake is generating a new ID on restart, leading to a new state document being created.
     • Check the Firestore console to confirm the document is being written and updated as expected.
     • Ensure save_state is called at all necessary checkpoints within your agent’s logic.
     • Check for any errors during save_state that might prevent the write (review the try-except blocks’ output).
3. Performance Bottlenecks with Large State:
   • Issue: Agent becomes slow when loading or saving very large conversation_history or agent_variables.
   • Solution:
     • Optimize data structure: Only store essential information. For conversation_history, consider storing only a summary or the last N turns in the main state document, and archiving older turns in a separate collection or Cloud Storage.
     • Consider caching: For frequently accessed but slowly changing parts of the state, implement an in-memory cache within the agent instance to reduce database calls.
     • Review Firestore usage: Check for inefficient queries or excessive reads/writes.
4. Firestore Permissions Denied:
   • Issue: Your agent’s service account lacks the necessary IAM permissions to read/write to Firestore.
   • Solution: In the Google Cloud Console, navigate to “IAM & Admin” -> “Service Accounts” and ensure the service account used by your agent has at least the Cloud Datastore User role, or a custom role with datastore.entities.get, datastore.entities.update, datastore.entities.create, and datastore.entities.delete permissions.

Summary & Next Step

You’ve successfully designed and implemented a robust context preservation mechanism for your ADK agent. By integrating with Google Firestore, your agent can now:

• Load its entire operational state and conversational history upon startup.
• Save its current state and context after critical interactions or workflow steps.
• Effectively pause and resume its activities, maintaining continuity across sessions or system restarts.

This is a fundamental step towards building truly resilient and production-ready AI agents. With persistent state, your agent can handle interruptions, long-running tasks, and deliver a more consistent user experience. This durable memory is what elevates an agent from a stateless chatbot to a capable, long-term assistant.

In the next chapter, we will take our agent a step closer to production readiness by containerizing it using Docker, preparing it for scalable and portable deployment to Google Cloud services like Cloud Run or GKE.

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.

References

1. Google Cloud Firestore Documentation: The official documentation for Google’s NoSQL document database. https://cloud.google.com/firestore/docs
2. Google Cloud Python Client for Firestore: Official repository and documentation for the Python library. https://googleapis.dev/python/firestore/latest/index.html
3. Google Cloud IAM Documentation: Information on managing identities and access control in Google Cloud. https://cloud.google.com/iam/docs
4. Google ADK (Agent Development Kit) Examples: While a specific official ADK documentation URL wasn’t found as of 2026-05-23, community and training examples provide insight. https://github.com/Sri-Krishna-V/awesome-adk-agents
5. PyPI: google-cloud-firestore: The Python Package Index page for the Firestore client library, useful for checking the latest stable version. https://pypi.org/project/google-cloud-firestore/