OpenAI Agents Python SDK

System overview

Product runtime architecture

Solid lines show the primary path. Dashed lines show reads, writes, async work, or feedback. Select an element to drill down.

Primary pathSupporting relation

Drawing…

01Agent Definition & Prompt AssemblyDefines agents, their instructions, tools, handoffs, and guardrails; assembles system prompts and handoff prompts.02Run Loop & Turn ProcessingOrchestrates the agent run: processes model responses, executes tools, handles handoffs, and finalizes output.03Tool Execution & ApprovalExecutes function tools, manages background tasks, and enforces approval workflows.04Handoffs & History ManagementTransfers control between agents, manages handoff history and input filtering.05Guardrails & SafetyRuns input and output guardrails, detects tripwires, and handles blocked outputs.06Session Persistence & TracingPersists conversation history and emits trace spans for model generations and tool activity.

Modules

Agent Definition & Prompt Assembly

Defines agents, their instructions, tools, handoffs, and guardrails; assembles system prompts and handoff prompts.

Module evidencesrc/agents/agent.py:296-1083

Dashed nodes are interfaces outside this module.

Drawing…

entryAgent Definition & EntryEntry point for defining an agent with instructions, tools, handoffs, and guardrails.

Input

User-defined agent configuration

Output

Agent object with system prompt and tool list

Source evidence

src/agents/agent.py:296-1083

No prompt evidence is directly associated with this node.

stageSystem Prompt AssemblyBuilds the system prompt from agent instructions and dynamic prompt functions.

Input

Agent instructionsDynamic prompt function output

Output

System prompt string

Source evidence

src/agents/agent.py:296-1083

No prompt evidence is directly associated with this node.

Modules

Run Loop & Turn Processing

Orchestrates the agent run: processes model responses, executes tools, handles handoffs, and finalizes output.

Module evidencesrc/agents/run_internal/run_loop.py:491-649src/agents/run_internal/agent_runner_helpers.py:494-500

Dashed nodes are interfaces outside this module.

Drawing…

entryRun Loop StartEntry point for running an agent; accepts user input and starts the turn loop.

Input

User inputAgentRun configuration

Output

RunResult or RunResultStreaming

Source evidence

src/agents/run_internal/run_loop.py:491-649

No prompt evidence is directly associated with this node.

stageModel Response ProcessingProcesses the model response, appending it to the list of responses and extracting tool calls or final output.

Input

Model responseCurrent items

Output

Processed responseTool calls or final output

Source evidence

src/agents/run_internal/agent_runner_helpers.py:494-500

No prompt evidence is directly associated with this node.

outputFinal OutputReturns the final output to the caller, either as a result object or streamed events.

Input

Final output valueGuardrail results

Output

RunResult or RunResultStreaming

Source evidence

src/agents/run_internal/run_loop.py:491-649

No prompt evidence is directly associated with this node.

Modules

Tool Execution & Approval

Executes function tools, manages background tasks, and enforces approval workflows.

Module evidencesrc/agents/run_internal/tool_execution.py:232-324

Dashed nodes are interfaces outside this module.

Drawing…

workerTool ExecutionExecutes function tools, manages background tasks, and handles approval flows.

Input

Tool calls from modelApproval decisions

Output

Tool resultsApproval requests

Source evidence

src/agents/run_internal/tool_execution.py:232-324

No prompt evidence is directly associated with this node.

Modules

Handoffs & History Management

Transfers control between agents, manages handoff history and input filtering.

Module evidencesrc/agents/handoffs/__init__.py:203-204

Dashed nodes are interfaces outside this module.

Drawing…

Key prompts

Handoff Prompt Assembly

Recommended Handoff System Context

# System context You are part of a multi-agent system called the Agents SDK, designed to make agent coordination and execution easy. Agents uses two primary abstraction: **Agents** and **Handoffs**. An agent encompasses instructions and tools and can hand off a conversation to…

src/agents/extensions/handoff_prompt.py:3-12

llmHandoff Prompt AssemblyAdds handoff instructions to the system prompt to inform the model about available handoffs.

Input

System promptHandoff instructions

Output

Prompt with handoff instructions

Source evidence

src/agents/extensions/handoff_prompt.py:15-19

Recommended Handoff System Context

src/agents/extensions/handoff_prompt.py:3-12

# System context
You are part of a multi-agent system called the Agents SDK, designed to make agent coordination and execution easy. Agents uses two primary abstraction: **Agents** and **Handoffs**. An agent encompasses instructions and tools and can hand off a conversation to…

workerHandoff ExecutionTransfers control to another agent, generating a transfer message and updating history.

Input

Handoff tool callCurrent history

Output

Transfer messageUpdated history

Source evidence

src/agents/handoffs/__init__.py:203-204

No prompt evidence is directly associated with this node.

Modules

Guardrails & Safety

Runs input and output guardrails, detects tripwires, and handles blocked outputs.

Module evidencesrc/agents/run_internal/guardrails.py:227-241

Dashed nodes are interfaces outside this module.

Drawing…

stageInput GuardrailsRuns input guardrails on user input before model processing; detects tripwires.

Input

User inputGuardrail functions

Output

Guardrail resultsTripwire flag

Source evidence

src/agents/run_internal/guardrails.py:227-241

No prompt evidence is directly associated with this node.

stageOutput GuardrailsRuns output guardrails on the final output; handles tripwires and blocked messages.

Input

Final outputGuardrail functions

Output

Guardrail resultsBlocked message or final output

Source evidence

src/agents/run_internal/run_loop.py:491-649

No prompt evidence is directly associated with this node.

Modules

Session Persistence & Tracing

Persists conversation history and emits trace spans for model generations and tool activity.

Module evidencesrc/agents/models/_trace.py:42-71src/agents/sandbox/session/sandbox_session.py:703-708

Dashed nodes are interfaces outside this module.

Drawing…

storeSession PersistencePersists conversation items to the session store for continuity across runs.

Input

Final turn itemsResponse ID

Output

Persisted session state

Source evidence

src/agents/run_internal/run_loop.py:491-649

No prompt evidence is directly associated with this node.

externalTrace GenerationEmits trace spans for model generations and tool activity for observability.

Input

Model responseUsage data

Output

Trace spans

Source evidence

src/agents/models/_trace.py:42-71

No prompt evidence is directly associated with this node.