How to properly handle session state across agent transfers?

[mohammadmseet-hue]

I am building a multi-agent system where agents share session state. When I transfer from agent A to agent B using agent_transfer(), the state dict seems to be copied by reference in some cases and by value in others.

Is there a recommended pattern for ensuring consistent state handling across transfers? Should I use the artifact service instead?

Using google-adk 1.5.0 on Python 3.11.

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The session.state dictionary is shared by reference among all agents in a single invocation. The behavior you're seeing is standard for mutable dictionaries in Python. For robust state management, we recommend using tools to explicitly modify the state. The artifact service is intended for file-based data, not for managing the session's working state.

---

Hello! That's an excellent question about a core concept in ADK.

How State is Handled

In a multi-agent system using ADK, agents share information primarily through the session.state object. When you use agent_transfer() or have a SequentialAgent invoke its sub-agents, they are all given the same InvocationContext, which contains a reference to the same session.state dictionary [1].

This means you are always operating on the same state object, not a copy. The behavior you've observed that seems like "copy by value" vs. "copy by reference" is a result of how Python handles mutable objects like dictionaries. Any modification to the dictionary (e.g., adding a key or changing a value) will be visible to all subsequent agents in that conversational turn because they all hold a reference to the same dictionary object.

Recommended Patterns for State Management

While you can modify the state directly within an agent, a more robust and maintainable pattern is to delegate state manipulation to tools.

1. Use Tools for State Modification: Create a tool that takes the necessary data as input and performs the logic to update the session.state. This encapsulates the state logic and makes the agent's role clearer—it focuses on reasoning and deciding when to call the tool. Tools get access to the state via the ToolContext [2, 3].

   from adk.tools import tool
   
   @tool
   def update_shared_state(tool_context, new_value: str) -> str:
       """Updates the shared state with a new value."""
       current_state = tool_context.state.get("my_key", "default")
       print(f"Current state was: {current_state}")
       tool_context.state["my_key"] = new_value
       return f"State updated to: {new_value}"

2. Use output_key for Simple Cases: If an agent's primary purpose is to produce a value that needs to be stored, you can use the output_key property on the agent. This will automatically save the agent's return value to the specified key in session.state [1, 4].

When to Use the Artifact Service

The artifact service is designed for a different purpose. It should be used for storing and sharing file-based data, such as images, PDFs, or other binary data, not for the working "scratchpad" memory of the session [5, 6]. For the dictionary of session values you're describing, session.state is the correct tool.

I hope this clarifies the intended design and helps you build your multi-agent system!

---

[1] https://google.github.io/adk-docs/agents/multi-agents/
[2] https://google.github.io/adk-docs/context/
[3] https://google.github.io/adk-docs/tools-custom/
[4] https://google.github.io/adk-docs/tutorials/agent-team/
[5] https://google.github.io/adk-docs/artifacts/
[6] https://google.github.io/adk-docs/workflows/data-handling/

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

Related answer: Based on internal documentation, here are the recommended credential configurations for ADK agents.

For authenticating ADK agents, especially for use with Google Cloud services, the recommended approach for production environments is using a service account. You can point to the service account key file using the GOOGLE_APPLICATION_CREDENTIALS environment variable. For other environments, API keys can be managed using the GOOGLE_API_KEY environment variable.

ADK also supports other authentication methods like OAuth 2.0 for interactive scenarios, which can be configured within the agent's code. For development, you can use Application Default Credentials by running gcloud auth application-default login.