Skip to content
OaPy

OpenAI Agents SDK: Diagrams and Architecture Guide

Text diagrams of how the Python OpenAI Agents SDK works: the run loop, sessions, handoffs, guardrails, tools, MCP and approvals.

Checked against openai-agents 0.24.0 (checked 2026-11-19).

Text diagrams of what happens inside a run. Code for each step is in the comprehensive guide.

  1. Agent Lifecycle
  2. Multi-Agent Interaction Patterns
  3. Message Flow Diagrams
  4. Session Management
  5. Tool Integration Patterns
  6. Guardrail Integration
  7. MCP Integration Architecture
  8. Approvals
  9. Real-World Patterns

┌─────────────────────────────────────────────────────────┐
│ Agent Execution Flow │
└─────────────────────────────────────────────────────────┘
┌──────────────────────┐
│ User Input │
│ + Instructions │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Format as Input │
│ (with history) │
└──────────┬───────────┘
│
▼
┌──────────────────────┐ ┌───────────────────────────┐
│ Call LLM Model │ ◄──► │ Input guardrails (first │
│ (with tools schema) │ │ agent only; in parallel │
└──────────┬───────────┘ │ unless run_in_parallel= │
│ │ False, which runs first) │
│ └───────────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Parse LLM Response │
├──────────────────────────────────────────┤
│ ├─ Tool Calls → Process & Return Results│
│ ├─ Handoff → Switch Agent & Continue │
│ └─ Final Output → Return to User │
└──────────┬───────────────────────────────┘
│
┌──────┴──────┐
│ │
▼ ▼
Has More Reached Final
Work? Output?
│ │
├─Yes──────┤
│ │
▼ ▼
Loop Output Guardrails
(validation)
│
▼
Return Result
┌──────────────────────────────────────────────────────────┐
│ Session Lifecycle with Conversation │
└──────────────────────────────────────────────────────────┘
Turn 1:
User: "My favourite colour is blue"
│
▼
Session Storage: [user_msg_1]
│
▼
Agent Response: "Noted, blue is your favourite"
│
▼
Session Storage: [user_msg_1, assistant_msg_1]
Turn 2:
User: "What's my favourite colour?"
│
▼
Load from Session: [user_msg_1, assistant_msg_1]
│
▼
Add new User message
Session Storage: [user_msg_1, assistant_msg_1, user_msg_2]
│
▼
Agent (with context): "Your favourite colour is blue"
│
▼
Session Storage: [user_msg_1, assistant_msg_1, user_msg_2, assistant_msg_2]

┌────────────────────────────────────────────────────────────┐
│ Simple Agent Handoff Architecture │
└────────────────────────────────────────────────────────────┘
User Query
│
▼
┌─────────────────────┐
│ Triage Agent │
│ - Determines type │
│ - Routes request │
└──────┬──────────────┘
│
├─ Billing Issue ──────────┐
│ │
├─ Technical Issue ────────┤
│ │
└─ General Question ───────┤
│
┌────────────────────────┴──────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Billing Agent│ │ Technical │
│ │ │ Support │
│ - Process │ │ │
│ - Calculate │ │ - Diagnose │
│ - Resolve │ │ - Solutions │
└──────────────┘ └──────────────┘
│ │
└───────────────┬───────────────┘
│
▼
Final Response
┌────────────────────────────────────────────────────────────┐
│ Chain of Responsibility - Agent Delegation │
└────────────────────────────────────────────────────────────┘
User Query: "Complex Financial Analysis"
│
▼
┌──────────────────────┐
│ Data Collection │
│ Agent │ Fetch data sources
├──────────────────────┤
│ Tools: Web search, │
│ file retrieval │
└──────┬───────────────┘
│ "Here's the data"
▼
┌──────────────────────┐
│ Preprocessing Agent │
│ │ Clean & structure data
├──────────────────────┤
│ Tools: Data │
│ transformations │
└──────┬───────────────┘
│ "Data prepared"
▼
┌──────────────────────┐
│ Analysis Agent │
│ │ Run complex analysis
├──────────────────────┤
│ Tools: Calculations, │
│ statistical models │
└──────┬───────────────┘
│ "Analysis complete"
▼
┌──────────────────────┐
│ Reporting Agent │
│ │ Generate formatted report
├──────────────────────┤
│ Tools: Formatting, │
│ export options │
└──────┬───────────────┘
│
▼
Final Report
┌────────────────────────────────────────────────────────────┐
│ Hub-and-Spoke Multi-Agent Architecture │
└────────────────────────────────────────────────────────────┘
┌─────────────────────┐
│ Orchestrator │
│ Agent (Hub) │
│ │
│ - Route requests │
│ - Aggregate results │
│ - Manage workflow │
└─────────┬───────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Agent 1 │ │ Agent 2 │ │ Agent 3 │
│ Search │ │ Analysis│ │ Format │
└─────────┘ └─────────┘ └─────────┘
│ │ │
└─────────────────┼─────────────────┘
│
▼
Orchestrator collects
and integrates results

┌────────────────────────────────────────────────────────────┐
│ Message Flow: Query to Response │
└────────────────────────────────────────────────────────────┘
User Agent LLM Tool
│ │ │ │
│─ Query ─────────>│ │ │
│ │─ Format ───────>│ │
│ │ (with context)│ │
│ │ │ │
│ │<─ Response ─────│ │
│ │ (with tool call)│ │
│ │ │ │
│ │─────────────────────── Call ─────>│
│ │ │
│ │<───────────────── Result ─────────│
│ │ │
│ │─ Re-call ────────>│ (with result) │
│ │ │ │
│ │<─ Final Output ───│ │
│ │ │ │
│<─ Response ──────│ │ │
│ │ │ │
┌────────────────────────────────────────────────────────────┐
│ Message Flow: Agent Handoff Process │
└────────────────────────────────────────────────────────────┘
User Agent 1 (Triage) Agent 2 (Specialist)
│ │ │
│─ Query ───────>│ │
│ │ │
│ │─ Evaluate ──>│ │
│ │ (LLM) │ │
│ │ │
│ │<── Decision ──│ │
│ │ "Handoff" │
│ │ │
│ │─ Transfer History ───>│
│ │ │
│ │ Process Query
│ │ │
│ │<─── Final Response ───│
│ │ │
│<─ Response ────│ │
│ │ │
User Input
│
├──────────────────────────────┐
▼ ▼
Input guardrails First model call
(run_in_parallel=True) (starts at the same time)
│
├─ tripwire? ──► cancel run, raise InputGuardrailTripwireTriggered
│
▼
Agent loop continues (tools, handoffs, more model calls)
│
▼
Final output from the last agent
│
▼
Output guardrails
│
├─ tripwire? ──► raise OutputGuardrailTripwireTriggered (no automatic retry)
│
▼
Return result

With @input_guardrail(run_in_parallel=False) the guardrail finishes before the first model call starts, so a tripwire costs no model tokens.


┌────────────────────────────────────────────────────────────┐
│ Session Storage: SQLite Architecture │
└────────────────────────────────────────────────────────────┘
In-Memory
Conversation
Context
│
▼
┌──────────────────┐
│ SQLiteSession │
│ (Agent SDK) │
└────────┬─────────┘
│
┌──────────┴──────────┐
│ │
▼ ▼
Write On Auto-Load On
Message Agent Run
│ │
▼ ▼
┌───────────────────────────┐
│ SQLite Database │
│ conversations.db │
├───────────────────────────┤
│ agent_sessions │
│ agent_messages │
│ (session_id, message_data)│
└───────────────────────────┘
▲ │
│ └──────────> Persistent Storage
│ (File System)
└─── Query & Retrieve ──────────
For Context
┌────────────────────────────────────────────────────────────┐
│ Session Storage: Multiple Backend Options │
└────────────────────────────────────────────────────────────┘
┌─────────────────────┐
│ Agent/Runner │
│ │
│ session=... │
└──────────┬──────────┘
│
┌──────┼──────┬──────────┬────────────┐
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
SQLite Redis SQLAlchemy OpenAI SQLite ":memory:"
│ │ │ │ │
│ │ │ │ │
├──FS ├─CPU │ │ └─ RAM
│ │ │ │ (testing)
│ │ │ │
│ │ ├─ PostgreSQL
│ │ ├─ MySQL
│ │ └─ Others
│ │
│ └─ Distributed
│ Cache Layer
│
└─ Local File
Storage

┌────────────────────────────────────────────────────────────┐
│ Function Tool: Definition to Execution │
└────────────────────────────────────────────────────────────┘
Step 1: Tool Definition
┌──────────────────────────┐
│ @function_tool │
│ def get_weather(): │
│ ... │
└──────────┬───────────────┘
│
▼
Step 2: Schema Generation
┌──────────────────────────┐
│ Pydantic Inspection │
├──────────────────────────┤
│ - Extract parameters │
│ - Get type hints │
│ - Generate JSON schema │
└──────────┬───────────────┘
│
▼
Step 3: Register with Agent
┌──────────────────────────┐
│ Agent(tools=[...]) │
├──────────────────────────┤
│ - Add to tools list │
│ - Include in LLM prompt │
└──────────┬───────────────┘
│
▼
Step 4: LLM Decision
┌──────────────────────────┐
│ LLM determines need │
│ tool and calls it │
└──────────┬───────────────┘
│
▼
Step 5: Tool Execution
┌──────────────────────────┐
│ Runner calls tool │
│ with LLM arguments │
└──────────┬───────────────┘
│
▼
Step 6: Return Result
┌──────────────────────────┐
│ Tool output appended │
│ to message history │
└──────────┬───────────────┘
│
▼
Step 7: Continue Loop
┌──────────────────────────┐
│ LLM uses result to │
│ craft response │
└──────────────────────────┘
┌────────────────────────────────────────────────────────────┐
│ Hosted Tools: OpenAI and External Services │
└────────────────────────────────────────────────────────────┘
Agent with
Hosted Tools
│
├─ WebSearchTool()
│ └──> Real-time web search
│ Results returned
│
├─ FileSearchTool()
│ └──> Vector database search
│ Semantic matching
│
├─ CodeInterpreterTool(tool_config=...)
│ └──> Python in an OpenAI-hosted container
│ Results captured
│
├─ ImageGenerationTool(tool_config=...)
│ └──> Image generation; image returned as base64
│
└─ HostedMCPTool(tool_config=...)
└──> OpenAI calls a remote MCP server
Run in your process instead: ComputerTool(computer=...) drives a
screen you implement; ShellTool / ApplyPatchTool act on a machine you control.

Runner.run(starting_agent, input)
│
├─ input guardrails ............ starting agent only (+ RunConfig.input_guardrails)
│
├─ for each function tool call:
│ needs_approval ........... pause the run for a person (checked first by default)
│ tool input guardrails .... before the tool (allow / reject_content / raise)
│ tool executes
│ tool output guardrails ... before the model sees the result
│
├─ handoff input_filter ........ when control moves to another agent
│
└─ output guardrails ........... final agent only (+ RunConfig.output_guardrails)

Several guardrails at the same level run concurrently; the first tripwire stops the run.


┌────────────────────────────────────────────────────────────┐
│ Model Context Protocol: Agent-Server Integration │
└────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────┐
│ OpenAI Agent │
│ │
│ ├─ Agent │
│ ├─ Tools (function tools + MCP tools) │
│ └─ Runner │
└─────────────────┬───────────────────────────────────────┘
│ Uses resources from
│
┌─────────┴──────────┬──────────────┐
│ │ │
▼ ▼ ▼
MCP Server A MCP Server B MCP Server C
(Filesystem) (Git) (Web Tools)
│ │ │
├─ List files ├─ Git log ├─ Search
├─ Read file ├─ Git diff ├─ Fetch URL
└─ Write file └─ Git show └─ Parse HTML
┌────────────────────────────────────────────────────────────┐
│ MCP Server Types: Local vs Remote │
└────────────────────────────────────────────────────────────┘
Local MCP (Stdio):
Agent
│
├─ MCPServerStdio
│ │
│ └─ subprocess.spawn
│ (local process)
│
└─ Tools from local
process
Remote MCP (HTTP/SSE):
Agent
│
├─ MCPServerStreamableHttp
│ │
│ └─ HTTP/SSE connection
│ (remote server)
│
└─ Tools from remote
endpoint

Runner.run(agent, input)
│
▼
Model calls a tool marked needs_approval
│
▼
Run stops; result.interruptions = [ToolApprovalItem, ...]
│
▼
state = result.to_state() ──► state.to_string() ──► your database
│ │
│ (minutes or days later, any process) │
▼ ▼
state = await RunState.from_string(agent, saved)
state.approve(item) or state.reject(item, rejection_message=...)
│
▼
Runner.run(agent, state) ──► tool runs (or the model is told it was rejected)
│
▼
Loop continues to the final output

┌────────────────────────────────────────────────────────────┐
│ Use Case: Financial Analysis Multi-Agent Workflow │
└────────────────────────────────────────────────────────────┘
User: "Analyse stock XYZ"
│
▼
Collector Agent
├─ Web search for news
├─ Fetch financial data
└─ Retrieve analyst reports
│
▼ Data collected
│
Processor Agent
├─ Parse financial metrics
├─ Calculate ratios
└─ Identify trends
│
▼ Processed data
│
Analyser Agent
├─ SWOT analysis
├─ Risk assessment
└─ Valuation models
│
▼ Analysis complete
│
Reporter Agent
├─ Format findings
├─ Generate visuals
└─ Produce recommendation
│
▼
Final Report
┌────────────────────────────────────────────────────────────┐
│ Use Case: Customer Service Support Triage │
└────────────────────────────────────────────────────────────┘
Customer Query
│
▼
Initial Assessment Agent
├─ Classify issue
├─ Set priority
└─ Route to specialist
│
├─ Billing ────────> Billing Agent
│ - Invoices - Account access
│ - Refunds - Payment processing
│ - Escalation
│
├─ Technical ─────> Technical Agent
│ - Bugs - Troubleshooting
│ - Features - Documentation
│ - Integration - Solutions
│
└─ General ───────> Knowledge Agent
- FAQs - Documentation
- Getting started - Best practices
Agent Handles Request
│
└─> Resolution or Escalation
to Human Agent

This comprehensive diagrams guide provides visual clarity for understanding OpenAI Agents SDK architectures and patterns.