state

Chapter 4: State

In the previous chapter, we saw how the Session object holds conversational history (events) and a state dictionary to maintain context across turns. This chapter dives deep into that state dictionary's wrapper: the State object. It's designed to provide a consistent view of the session's state while meticulously tracking changes made during a specific agent turn or callback execution.

Motivation and Use Case

When an agent processes a request, it often needs to:

1. Read existing information: What did the user previously specify as their destination?
2. Store new information: The agent just identified the user's budget.
3. Track intermediate changes: A tool call successfully fetched flight options, which need to be stored temporarily before being presented to the user or used in the next LLM call.
4. Manage different scopes: Some information might be relevant only to the current chat (session state), while other details (like user preferences) should persist across different chats (user state).

Managing this directly within a simple dictionary passed around can be error-prone. How do we ensure that changes made during a complex turn (involving callbacks, LLM calls, tool executions) are correctly captured and associated with the final outcome (Event) for persistence?

The State object addresses this by acting as a smart dictionary wrapper. It provides access to the underlying session state but records any modifications made during the current context (e.g., a callback or tool execution) into a separate "delta". This delta is then attached to the resulting Event, ensuring the Session (Session / BaseSessionService) can accurately update the persistent state.

Central Use Case: Consider our travel agent bot.

• The Session starts with state = {'origin': 'London'}.
• The agent's run_async is called. An InvocationContext is created.
• Inside a before_model_callback, we access ctx.state. ctx.state['origin'] returns 'London'.
• The callback sets a temporary flag: ctx.state[State.TEMP_PREFIX + 'needs_clarification'] = True. This is added to the delta but won't be persisted.
• The LLM runs and invokes a find_flights tool.
• Inside the tool's execution, it accesses ctx.state via ToolContext. It finds flights and updates the state: ctx.state['available_flights'] = [...]. This change is recorded in the delta. ctx.state['origin'] still returns 'London'.
• The tool yields an Event. This event's actions.state_delta now contains {'available_flights': [...]}. The temp: key is not included for persistence.
• The Runner calls session_service.append_event with this event. The service updates the persistent session state by merging the state_delta.
• In the next turn, when the Session is loaded, its base state will include {'origin': 'London', 'available_flights': [...]}.