How openai/openai-agents-python works
OpenAI Agents SDK is a provider-agnostic framework for agent workflows. The principal path is application input into Runner, through the run loop, model interaction, tool or handoff execution, and a final RunResult. Guardrails, sessions, tracing, MCP, sandbox workspaces, realtime agents, and voice pipelines are distinct capabilities. The tree and README establish these subsystem boundaries; sampled excerpts most directly confirm run orchestration support, voice processing, MCP lifecycle, sandbox persistence, and tracing-related error handling.
Main entry points: run_loop.py Agent Run Loop · run.py Runner API · pipeline.py Voice Pipeline · agent.py Agent Definition
Components 25
Core Orchestration
- Runner API
src/agents/run.py - Agent Definition
src/agents/agent.py - Agent Run Loop
src/agents/run_internal/run_loop.py - Run Result
src/agents/result.py - Guardrails
src/agents/run_internal/guardrails.py
Models And Tools
- Model Interface
src/agents/models/interface.py - Provider Routing
src/agents/models/multi_provider.py - OpenAI Models
src/agents/models/openai_responses.py - Tool Execution
src/agents/run_internal/tool_execution.py - MCP Manager
src/agents/mcp/manager.py - Agent Handoffs
src/agents/handoffs/__init__.py
State And Observability
- Conversation Sessions
src/agents/memory/session.py - Session Persistence
src/agents/run_internal/session_persistence.py - Tracing System
src/agents/tracing/__init__.py
Interactive Modalities
- Realtime Runner
src/agents/realtime/runner.py - Realtime Session
src/agents/realtime/session.py - Voice Pipeline
src/agents/voice/pipeline.py - Voice Models
src/agents/voice/model.py
Sandbox Capabilities
- Sandbox Agent
src/agents/sandbox/sandbox_agent.py - Sandbox Runtime
src/agents/sandbox/runtime.py - Sandbox Sessions
src/agents/sandbox/session/manager.py - Sandbox Memory
src/agents/sandbox/memory/manager.py
Other components
- Application User
- LLM Provider
- MCP Services
Connections 26
- Application User → Runner API: submits input
- Runner API → Agent Run Loop: starts run
- Agent Definition → Runner API: configures run
- Agent Run Loop → Model Interface: requests completion
- Model Interface → Provider Routing: selects provider
- Provider Routing → OpenAI Models: dispatches model
- OpenAI Models → LLM Provider: calls API
- Agent Run Loop → Tool Execution: executes tools
- Tool Execution → MCP Manager: uses MCP tools
- MCP Manager → MCP Services: connects servers
- Agent Run Loop → Agent Handoffs: dispatches handoff
- Agent Run Loop → Guardrails: checks safety
- Agent Run Loop → Session Persistence: persists history
- Session Persistence → Conversation Sessions: reads writes
- Agent Run Loop → Tracing System: records spans
- Agent Run Loop → Run Result: builds result
- Run Result → Runner API: returns output
- Runner API → Application User: returns result
- Sandbox Agent → Sandbox Runtime: prepares workspace
- Sandbox Runtime → Sandbox Sessions: manages sessions
- Sandbox Sessions → Sandbox Memory: stores memories
- Realtime Runner → Realtime Session: starts session
- Realtime Session → LLM Provider: streams events
- Voice Pipeline → Voice Models: transcribes speaks
- Voice Pipeline → Agent Definition: runs workflow
- Voice Pipeline → Tracing System: traces pipeline