State management for data agents

When you build with the Conversational Analytics API, state management is a key architectural consideration. You manage the API's conversation state and, for applications that use the Agent Development Kit (ADK), the framework's session state.

API state modes

The chat method in the Conversational Analytics API supports mutually exclusive context parameters that determine how conversation state is handled.

Use the following table to compare these modes:

Mode State Conversation history Agent Parameter Description
Chat with a conversation reference Stateful Managed by the API Yes ConversationReference Continues a stateful conversation by referencing an existing conversation and its associated agent. Google Cloud stores and manages the conversation history. You send only the new message for each turn.
Chat with a data agent reference Stateless Managed by your application Yes DataAgentContext Sends a stateless message that references a saved data agent for context. Your application must manage and provide the full conversation history with each request.
Chat with inline context Stateless Managed by your application No InlineContext Sends a stateless message that provides all context directly in the request. This mode doesn't use a saved data agent. Your application must manage and provide the full conversation history.

ADK session state

If you use the ADK framework for orchestration, the ADK provides a state management layer that operates independently of Conversational Analytics API state. Understanding both layers is essential for building multi-agent systems that function correctly.

The ADK uses key prefix conventions to control the scope and lifetime of state variables. Use the following table to evaluate these scopes:

Key prefix Scope Lifetime Visible to Examples
(no prefix) Session Current session only All agents in the session Current conversation topic or the results of the last query
user: User Across all sessions for the same user All agents and sessions for the specified user User preferences, saved data agent IDs, or language settings
app: Application Across all sessions for all users All agents and all users Global application configuration, shared data agent IDs, or feature flags
temp: Invocation Current invocation only The current agent within the active invocation Intermediate response data, such as streaming chunks or in-progress calculations

For more information on sharing state in multi-agent systems, see the ADK documentation.

How API state and ADK state interact

When you use the Conversational Analytics API with the ADK framework, the state layers function independently:

  • API state: If your application uses conversation references (stateful mode), then the API manages the conversation history. If your application uses data agent context or inline context (stateless modes), then the API remains stateless for each call.
  • ADK session state: The ADK framework maintains its own session, events, and state variables regardless of the mode that the Conversational Analytics API uses.

For example, when you use the ask_data_insights or ask_data_agent tools within the ADK, each call is independently stateless at the API level, even though the ADK maintains the broader session context. The ADK streaming demo illustrates the recommended pattern for this interaction: a data sub-agent writes parsed response data to the temp: state, which downstream agents then read within the same invocation.

What's next