Principle:Openai Openai agents python Shared Context

Knowledge Sources	OpenAI Agents Python Agents SDK Docs
Domains	AI_Agents, State_Management, Orchestration
Last Updated	2026-02-11 15:00 GMT

Overview

Shared Context is the theory of shared mutable state across agents, tools, and callbacks in the OpenAI Agents Python SDK. The RunContextWrapper provides a typed context object that is accessible throughout the entire run, enabling coordination between components without relying on global variables or external state stores.

Core Concepts

User-Defined Context Type

The context is a user-defined type that can be any Python object: a dataclass, a Pydantic model, a plain class, or even a simple dictionary. This type is passed to Runner.run() as the context parameter and becomes available to all tools, handoffs, guardrails, and lifecycle hooks throughout the run.

The flexibility of the context type means developers can model whatever state their application requires:

• A dataclass with user session information (user ID, permissions, preferences).
• A Pydantic model with database connections or API clients.
• A state object that tracks tool invocation counts, accumulated results, or workflow progress.

RunContextWrapper

The SDK wraps the user-provided context in a RunContextWrapper[TContext] generic class. This wrapper provides:

• context -- the user's original context object, accessible via wrapper.context.
• usage -- a Usage object that tracks token consumption across the run.
• turn_input -- the list of input items for the current turn.
• Approval state -- methods for tool approval/rejection in human-in-the-loop workflows (approve_tool, reject_tool, is_tool_approved).
• tool_input -- the raw input for the currently executing tool (when applicable).

Shared State Across Components

All components in a run receive the same RunContextWrapper instance. This means:

• A tool function can read state set by a previous tool or handoff callback.
• A handoff's on_handoff callback can initialize data that the target agent's tools will use.
• Guardrails can inspect or modify context to influence downstream processing.
• Lifecycle hooks can track metrics or log state transitions.

Because all components share the same mutable object, changes made by one component are immediately visible to all others. This is a deliberate design choice that enables coordination without message passing.

Context Is Not Sent to the LLM

A critical distinction is that the context object is not sent to the LLM. It exists purely for code-level coordination between Python components. The LLM never sees the context's contents, and the context cannot be modified by the model's outputs directly. Only tool functions and callbacks (Python code) can read and write to the context.

This separation ensures that:

• Sensitive data (API keys, database connections) can be stored in context without risk of LLM exposure.
• The context can hold objects that are not serializable to text (file handles, network connections).
• The LLM's token budget is not consumed by context data.

Type Safety

The RunContextWrapper uses Python generics (RunContextWrapper[TContext]) to provide type safety. When tools are defined with a typed context parameter, type checkers like mypy can verify that the context type matches the agent's declared context type. This catches mismatches at development time rather than at runtime.

Source Reference

Source: src/agents/run_context.py:L34-215

Import:

from agents import RunContextWrapper

Related Pages

• Implementation:Openai_Openai_agents_python_RunContextWrapper
• Implementation: Openai_Openai_agents_python_RunContextWrapper -- full class signature, fields, and usage examples.
• Principle: Openai_Openai_agents_python_Handoff_Configuration -- handoffs use shared context for cross-agent state.
• Workflow: Openai_Openai_agents_python_Multi_Agent_Handoff -- demonstrates shared context in a multi-agent conversation loop.

GitHub URL

Source: run_context.py