User session data
AI Models & Assistants / Knowledge library
Agent State
Stores the information required to continue, inspect, or resume an agent run
Why learn Agent State?
It lets applications preserve continuity without forcing every operational detail into the model prompt.
The problem it solves
It separates durable workflow facts from the limited context sent to each model call.
Where it came from
Agent state can include conversation items, current agent, tool results, plans, checkpoints, budgets, and application metadata. Model-visible context is only one projection of this larger runtime state.
Build your understanding
Work through these exercises in order. Try the task before opening a reference.
- Define Agent State and identify its place in an agent architecture.
- Choose a task where Agent State improves an agent system.
- Diagnose one failure caused by misusing Agent State.
- Interpret a trace or state transition involving Agent State.
- Explain one operational tradeoff of Agent State.
Documentation and sources
- OpenAI Agents SDK: Context management (openai.github.io)
Connect the ideas
Explore next
Real World Example
Dynamic User Session Context for Financial Support Agents
Financial services firms providing automated customer support agents.
The business problem
Agents often lose track of user-specific authorization levels or account identifiers during complex, multi-step tool interactions, leading to redundant authentication requests or incorrect data access.
How this topic solves it
By utilizing a shared RunContextWrapper, the agent maintains a persistent, type-safe state object throughout the entire lifecycle of a run, ensuring that user-specific metadata is available to every tool without requiring the LLM to re-query the user.
- Define a Pydantic model or dataclass to hold the required user session state, such as account_id and authorization_level.
- Initialize the agent with the specific context type to ensure type safety across all tool definitions.
- Pass the populated context object into the Runner.run method at the start of the agent interaction.
- Access the shared state within tool functions using the RunContextWrapper.context property to perform authorization checks or data retrieval.
Shows how the application state flows through the agent execution lifecycle.
Orchestrates the run
Provides access to state
Executes logic using state
- App State → injects → Runner
- Runner → wraps → RunContextWrapper
- RunContextWrapper → exposes context → Tool Function
Implementation example
Demonstrates how the tool function receives the RunContextWrapper and accesses the underlying UserSession object to perform operations.
from dataclasses import dataclass
from agents import RunContextWrapper
@dataclass
class UserSession:
account_id: str
# Tool accesses the shared account_id from the context wrapper
async def get_balance(wrapper: RunContextWrapper[UserSession]) -> str:
return f"Balance for {wrapper.context.account_id} is $500."Expected business outcome
A seamless user experience where the agent retains critical session information, reducing friction and improving the accuracy of tool-based operations.
Limitations and checks
The context object is not automatically sent to the LLM; it is strictly for local tool execution. If the LLM needs this data to make decisions, it must be explicitly injected into the instructions or conversation history.