# openai/openai-agents-python architecture

> Architecture diagram of the GitHub repository openai/openai-agents-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/openai-agents-python
- Repository: https://github.com/openai/openai-agents-python

## Overview

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: [`src/agents/run_internal/run_loop.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/run_loop.py) (Agent Run Loop), [`src/agents/run.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/run.py) (Runner API), [`src/agents/voice/pipeline.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/voice/pipeline.py) (Voice Pipeline), [`src/agents/agent.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py) (Agent Definition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Orchestration"]
  node_runner["Runner API<br/>[run.py]"]
  node_agent["Agent Definition<br/>[agent.py]"]
  node_run_loop["Agent Run Loop<br/>[run_loop.py]"]
  node_run_result["Run Result<br/>[result.py]"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
end

subgraph group_models_tools["Models And Tools"]
  node_model_interface["Model Interface<br/>[interface.py]"]
  node_provider_routing["Provider Routing<br/>[multi_provider.py]"]
  node_openai_models["OpenAI Models"]
  node_tool_execution["Tool Execution<br/>[tool_execution.py]"]
  node_mcp_manager["MCP Manager<br/>[manager.py]"]
  node_handoffs["Agent Handoffs<br/>[__init__.py]"]
end

subgraph group_state_obs["State And Observability"]
  node_sessions["Conversation Sessions<br/>[session.py]"]
  node_session_persistence["Session Persistence"]
  node_tracing["Tracing System<br/>[__init__.py]"]
end

subgraph group_modalities["Interactive Modalities"]
  node_realtime_runner["Realtime Runner<br/>[runner.py]"]
  node_realtime_session["Realtime Session<br/>[session.py]"]
  node_voice_pipeline["Voice Pipeline<br/>[pipeline.py]"]
  node_voice_models["Voice Models<br/>[model.py]"]
end

subgraph group_sandbox["Sandbox Capabilities"]
  node_sandbox_agent["Sandbox Agent<br/>[sandbox_agent.py]"]
  node_sandbox_runtime["Sandbox Runtime<br/>[runtime.py]"]
  node_sandbox_sessions["Sandbox Sessions<br/>[manager.py]"]
  node_sandbox_memory[("Sandbox Memory<br/>[manager.py]")]
end

node_app_user(("Application User"))
node_llm_service{{"LLM Provider"}}
node_mcp_service{{"MCP Services"}}

node_app_user -->|"submits input"| node_runner
node_runner -->|"starts run"| node_run_loop
node_agent -->|"configures run"| node_runner
node_run_loop -->|"requests completion"| node_model_interface
node_model_interface -->|"selects provider"| node_provider_routing
node_provider_routing -->|"dispatches model"| node_openai_models
node_openai_models -->|"calls API"| node_llm_service
node_run_loop -->|"executes tools"| node_tool_execution
node_tool_execution -.->|"uses MCP tools"| node_mcp_manager
node_mcp_manager -.->|"connects servers"| node_mcp_service
node_run_loop -->|"dispatches handoff"| node_handoffs
node_run_loop -->|"checks safety"| node_guardrails
node_run_loop -->|"persists history"| node_session_persistence
node_session_persistence -->|"reads writes"| node_sessions
node_run_loop -->|"records spans"| node_tracing
node_run_loop -->|"builds result"| node_run_result
node_run_result -->|"returns output"| node_runner
node_runner -->|"returns result"| node_app_user
node_sandbox_agent -.->|"prepares workspace"| node_sandbox_runtime
node_sandbox_runtime -->|"manages sessions"| node_sandbox_sessions
node_sandbox_sessions -->|"stores memories"| node_sandbox_memory
node_realtime_runner -.->|"starts session"| node_realtime_session
node_realtime_session -.->|"streams events"| node_llm_service
node_voice_pipeline -.->|"transcribes speaks"| node_voice_models
node_voice_pipeline -.->|"runs workflow"| node_agent
node_voice_pipeline -.->|"traces pipeline"| node_tracing

click node_runner "https://github.com/openai/openai-agents-python/blob/main/src/agents/run.py"
click node_agent "https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py"
click node_run_loop "https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/run_loop.py"
click node_run_result "https://github.com/openai/openai-agents-python/blob/main/src/agents/result.py"
click node_model_interface "https://github.com/openai/openai-agents-python/blob/main/src/agents/models/interface.py"
click node_provider_routing "https://github.com/openai/openai-agents-python/blob/main/src/agents/models/multi_provider.py"
click node_openai_models "https://github.com/openai/openai-agents-python/blob/main/src/agents/models/openai_responses.py"
click node_tool_execution "https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/tool_execution.py"
click node_mcp_manager "https://github.com/openai/openai-agents-python/blob/main/src/agents/mcp/manager.py"
click node_handoffs "https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/__init__.py"
click node_guardrails "https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/guardrails.py"
click node_sessions "https://github.com/openai/openai-agents-python/blob/main/src/agents/memory/session.py"
click node_session_persistence "https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/session_persistence.py"
click node_tracing "https://github.com/openai/openai-agents-python/blob/main/src/agents/tracing/__init__.py"
click node_sandbox_agent "https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/sandbox_agent.py"
click node_sandbox_runtime "https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/runtime.py"
click node_sandbox_sessions "https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/session/manager.py"
click node_sandbox_memory "https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/memory/manager.py"
click node_realtime_runner "https://github.com/openai/openai-agents-python/blob/main/src/agents/realtime/runner.py"
click node_realtime_session "https://github.com/openai/openai-agents-python/blob/main/src/agents/realtime/session.py"
click node_voice_pipeline "https://github.com/openai/openai-agents-python/blob/main/src/agents/voice/pipeline.py"
click node_voice_models "https://github.com/openai/openai-agents-python/blob/main/src/agents/voice/model.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_agent,node_run_loop,node_run_result,node_guardrails,node_app_user toneBlue
class node_model_interface,node_provider_routing,node_openai_models,node_tool_execution,node_mcp_manager,node_handoffs toneAmber
class node_sessions,node_session_persistence,node_tracing toneMint
class node_realtime_runner,node_realtime_session,node_voice_pipeline,node_voice_models toneRose
class node_sandbox_agent,node_sandbox_runtime,node_sandbox_sessions,node_sandbox_memory,node_llm_service,node_mcp_service toneIndigo
```

## Components

### Core Orchestration

- [Runner API](https://github.com/openai/openai-agents-python/blob/main/src/agents/run.py): `src/agents/run.py`
- [Agent Definition](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py): `src/agents/agent.py`
- [Agent Run Loop](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/run_loop.py): `src/agents/run_internal/run_loop.py`
- [Run Result](https://github.com/openai/openai-agents-python/blob/main/src/agents/result.py): `src/agents/result.py`
- [Guardrails](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/guardrails.py): `src/agents/run_internal/guardrails.py`

### Models And Tools

- [Model Interface](https://github.com/openai/openai-agents-python/blob/main/src/agents/models/interface.py): `src/agents/models/interface.py`
- [Provider Routing](https://github.com/openai/openai-agents-python/blob/main/src/agents/models/multi_provider.py): `src/agents/models/multi_provider.py`
- [OpenAI Models](https://github.com/openai/openai-agents-python/blob/main/src/agents/models/openai_responses.py): `src/agents/models/openai_responses.py`
- [Tool Execution](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/tool_execution.py): `src/agents/run_internal/tool_execution.py`
- [MCP Manager](https://github.com/openai/openai-agents-python/blob/main/src/agents/mcp/manager.py): `src/agents/mcp/manager.py`
- [Agent Handoffs](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/__init__.py): `src/agents/handoffs/__init__.py`

### State And Observability

- [Conversation Sessions](https://github.com/openai/openai-agents-python/blob/main/src/agents/memory/session.py): `src/agents/memory/session.py`
- [Session Persistence](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/session_persistence.py): `src/agents/run_internal/session_persistence.py`
- [Tracing System](https://github.com/openai/openai-agents-python/blob/main/src/agents/tracing/__init__.py): `src/agents/tracing/__init__.py`

### Interactive Modalities

- [Realtime Runner](https://github.com/openai/openai-agents-python/blob/main/src/agents/realtime/runner.py): `src/agents/realtime/runner.py`
- [Realtime Session](https://github.com/openai/openai-agents-python/blob/main/src/agents/realtime/session.py): `src/agents/realtime/session.py`
- [Voice Pipeline](https://github.com/openai/openai-agents-python/blob/main/src/agents/voice/pipeline.py): `src/agents/voice/pipeline.py`
- [Voice Models](https://github.com/openai/openai-agents-python/blob/main/src/agents/voice/model.py): `src/agents/voice/model.py`

### Sandbox Capabilities

- [Sandbox Agent](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/sandbox_agent.py): `src/agents/sandbox/sandbox_agent.py`
- [Sandbox Runtime](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/runtime.py): `src/agents/sandbox/runtime.py`
- [Sandbox Sessions](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/session/manager.py): `src/agents/sandbox/session/manager.py`
- [Sandbox Memory](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/memory/manager.py): `src/agents/sandbox/memory/manager.py`

### Other components

- **Application User**
- **LLM Provider**
- **MCP Services**

## Connections

- 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
