State: The Session's Scratchpad¶

Within each Session (our conversation thread), the state attribute acts like the agent's dedicated scratchpad for that specific interaction. While session.events holds the full history, session.state is where the agent stores and updates dynamic details needed during the conversation.

What is `session.state`?¶

Conceptually, session.state is a dictionary holding key-value pairs. It's designed for information the agent needs to recall or track to make the current conversation effective:

Personalize Interaction: Remember user preferences mentioned earlier (e.g., 'user_preference_theme': 'dark').
Track Task Progress: Keep tabs on steps in a multi-turn process (e.g., 'booking_step': 'confirm_payment').
Accumulate Information: Build lists or summaries (e.g., 'shopping_cart_items': ['book', 'pen']).
Make Informed Decisions: Store flags or values influencing the next response (e.g., 'user_is_authenticated': True).

Key Characteristics of `State`¶

Structure: Serializable Key-Value Pairs
- Data is stored as key: value.
- Keys: Always strings (str). Use clear names (e.g., 'departure_city', 'user:language_preference').
- Values: Must be serializable. This means they can be easily saved and loaded by the SessionService. Stick to basic Python types like strings, numbers, booleans, and simple lists or dictionaries containing only these basic types. (See API documentation for precise details).
- ⚠️ Avoid Complex Objects: Do not store non-serializable Python objects (custom class instances, functions, connections, etc.) directly in the state. Store simple identifiers if needed, and retrieve the complex object elsewhere.
Mutability: It Changes
- The contents of the state are expected to change as the conversation evolves.
Persistence: Depends on SessionService
- Whether state survives application restarts depends on your chosen service:
- InMemorySessionService: Not Persistent. State is lost on restart.
- DatabaseSessionService / VertexAiSessionService: Persistent. State is saved reliably.

Organizing State with Prefixes: Scope Matters¶

Prefixes on state keys define their scope and persistence behavior, especially with persistent services:

No Prefix (Session State):
- Scope: Specific to the current session (id).
- Persistence: Only persists if the SessionService is persistent (Database, VertexAI).
- Use Cases: Tracking progress within the current task (e.g., 'current_booking_step'), temporary flags for this interaction (e.g., 'needs_clarification').
- Example: session.state['current_intent'] = 'book_flight'
user: Prefix (User State):
- Scope: Tied to the user_id, shared across all sessions for that user (within the same app_name).
- Persistence: Persistent with Database or VertexAI. (Stored by InMemory but lost on restart).
- Use Cases: User preferences (e.g., 'user:theme'), profile details (e.g., 'user:name').
- Example: session.state['user:preferred_language'] = 'fr'
app: Prefix (App State):
- Scope: Tied to the app_name, shared across all users and sessions for that application.
- Persistence: Persistent with Database or VertexAI. (Stored by InMemory but lost on restart).
- Use Cases: Global settings (e.g., 'app:api_endpoint'), shared templates.
- Example: session.state['app:global_discount_code'] = 'SAVE10'
temp: Prefix (Temporary Session State):
- Scope: Specific to the current session processing turn.
- Persistence: Never Persistent. Guaranteed to be discarded, even with persistent services.
- Use Cases: Intermediate results needed only immediately, data you explicitly don't want stored.
- Example: session.state['temp:raw_api_response'] = {...}

How the Agent Sees It: Your agent code interacts with the combined state through the single session.state dictionary. The SessionService handles fetching/merging state from the correct underlying storage based on prefixes.

How State is Updated: Recommended Methods¶

State should always be updated as part of adding an Event to the session history using session_service.append_event(). This ensures changes are tracked, persistence works correctly, and updates are thread-safe.

1. The Easy Way: output_key (for Agent Text Responses)

This is the simplest method for saving an agent's final text response directly into the state. When defining your LlmAgent, specify the output_key:

from google.adk.agents import LlmAgent
from google.adk.sessions import InMemorySessionService, Session
from google.adk.runners import Runner
from google.genai.types import Content, Part

# Define agent with output_key
greeting_agent = LlmAgent(
    name="Greeter",
    model="gemini-2.0-flash", # Use a valid model
    instruction="Generate a short, friendly greeting.",
    output_key="last_greeting" # Save response to state['last_greeting']
)

# --- Setup Runner and Session ---
app_name, user_id, session_id = "state_app", "user1", "session1"
session_service = InMemorySessionService()
runner = Runner(
    agent=greeting_agent,
    app_name=app_name,
    session_service=session_service
)
session = session_service.create_session(app_name=app_name, 
                                        user_id=user_id, 
                                        session_id=session_id)
print(f"Initial state: {session.state}")

# --- Run the Agent ---
# Runner handles calling append_event, which uses the output_key
# to automatically create the state_delta.
user_message = Content(parts=[Part(text="Hello")])
for event in runner.run(user_id=user_id, 
                        session_id=session_id, 
                        new_message=user_message):
    if event.is_final_response():
      print(f"Agent responded.") # Response text is also in event.content

# --- Check Updated State ---
updated_session = session_service.get_session(app_name, user_id, session_id)
print(f"State after agent run: {updated_session.state}")
# Expected output might include: {'last_greeting': 'Hello there! How can I help you today?'}

Behind the scenes, the Runner uses the output_key to create the necessary EventActions with a state_delta and calls append_event.

2. The Standard Way: EventActions.state_delta (for Complex Updates)

For more complex scenarios (updating multiple keys, non-string values, specific scopes like user: or app:, or updates not tied directly to the agent's final text), you manually construct the state_delta within EventActions.

from google.adk.sessions import InMemorySessionService, Session
from google.adk.events import Event, EventActions
from google.genai.types import Part, Content
import time

# --- Setup ---
session_service = InMemorySessionService()
app_name, user_id, session_id = "state_app_manual", "user2", "session2"
session = session_service.create_session(
    app_name=app_name,
    user_id=user_id,
    session_id=session_id,
    state={"user:login_count": 0, "task_status": "idle"}
)
print(f"Initial state: {session.state}")

# --- Define State Changes ---
current_time = time.time()
state_changes = {
    "task_status": "active",              # Update session state
    "user:login_count": session.state.get("user:login_count", 0) + 1, # Update user state
    "user:last_login_ts": current_time,   # Add user state
    "temp:validation_needed": True        # Add temporary state (will be discarded)
}

# --- Create Event with Actions ---
actions_with_update = EventActions(state_delta=state_changes)
# This event might represent an internal system action, not just an agent response
system_event = Event(
    invocation_id="inv_login_update",
    author="system", # Or 'agent', 'tool' etc.
    actions=actions_with_update,
    timestamp=current_time
    # content might be None or represent the action taken
)

# --- Append the Event (This updates the state) ---
session_service.append_event(session, system_event)
print("`append_event` called with explicit state delta.")

# --- Check Updated State ---
updated_session = session_service.get_session(app_name=app_name,
                                            user_id=user_id, 
                                            session_id=session_id)
print(f"State after event: {updated_session.state}")
# Expected: {'user:login_count': 1, 'task_status': 'active', 'user:last_login_ts': <timestamp>}
# Note: 'temp:validation_needed' is NOT present.

What append_event Does:

Adds the Event to session.events.
Reads the state_delta from the event's actions.
Applies these changes to the state managed by the SessionService, correctly handling prefixes and persistence based on the service type.
Updates the session's last_update_time.
Ensures thread-safety for concurrent updates.

⚠️ A Warning About Direct State Modification¶

Avoid directly modifying the session.state dictionary after retrieving a session (e.g., retrieved_session.state['key'] = value).

Why this is strongly discouraged:

Bypasses Event History: The change isn't recorded as an Event, losing auditability.
Breaks Persistence: Changes made this way will likely NOT be saved by DatabaseSessionService or VertexAiSessionService. They rely on append_event to trigger saving.
Not Thread-Safe: Can lead to race conditions and lost updates.
Ignores Timestamps/Logic: Doesn't update last_update_time or trigger related event logic.

Recommendation: Stick to updating state via output_key or EventActions.state_delta within the append_event flow for reliable, trackable, and persistent state management. Use direct access only for reading state.

Best Practices for State Design Recap¶

Minimalism: Store only essential, dynamic data.
Serialization: Use basic, serializable types.
Descriptive Keys & Prefixes: Use clear names and appropriate prefixes (user:, app:, temp:, or none).
Shallow Structures: Avoid deep nesting where possible.
Standard Update Flow: Rely on append_event.