OpenAI Agents SDK: Diagrams and Architecture Guide
OpenAI Agents SDK: Diagrams and Architecture Guide
Section titled “OpenAI Agents SDK: Diagrams and Architecture Guide”Visual representations and architecture diagrams for the OpenAI Agents SDK, including agent lifecycle, multi-agent patterns, deployment topologies, and system flows.
Table of Contents
Section titled “Table of Contents”- Agent Lifecycle
- Multi-Agent Interaction Patterns
- Message Flow Diagrams
- Session Management
- Tool Integration Patterns
- Guardrail Integration
- MCP Integration Architecture
- Production Deployment Topologies
- Error Handling Flows
- Scalability Patterns
Agent Lifecycle
Section titled “Agent Lifecycle”Agent Execution Loop
Section titled “Agent Execution Loop”┌─────────────────────────────────────────────────────────┐│ Agent Execution Flow │└─────────────────────────────────────────────────────────┘
┌──────────────────────┐ │ User Input │ │ + Instructions │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ Format as Input │ │ (with history) │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ Input Guardrails │ │ (validation) │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ Call LLM Model │ │ (with tools schema) │ └──────────┬───────────┘ │ ▼ ┌──────────────────────────────────────────┐ │ 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 ResultSession State Management
Section titled “Session State Management”┌──────────────────────────────────────────────────────────┐│ 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]Multi-Agent Interaction Patterns
Section titled “Multi-Agent Interaction Patterns”Simple Handoff Pattern
Section titled “Simple Handoff Pattern”┌────────────────────────────────────────────────────────────┐│ 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 ResponseChain of Responsibility Pattern
Section titled “Chain of Responsibility Pattern”┌────────────────────────────────────────────────────────────┐│ 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 ReportHub-and-Spoke Pattern
Section titled “Hub-and-Spoke Pattern”┌────────────────────────────────────────────────────────────┐│ 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 resultsMessage Flow Diagrams
Section titled “Message Flow Diagrams”Standard Agent Query Flow
Section titled “Standard Agent Query Flow”┌────────────────────────────────────────────────────────────┐│ 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 ──────│ │ │ │ │ │ │Handoff Message Flow
Section titled “Handoff Message Flow”┌────────────────────────────────────────────────────────────┐│ Message Flow: Agent Handoff Process │└────────────────────────────────────────────────────────────┘
User Agent 1 (Triage) Agent 2 (Specialist) │ │ │ │─ Query ───────>│ │ │ │ │ │ │─ Evaluate ──>│ │ │ │ (LLM) │ │ │ │ │ │ │<── Decision ──│ │ │ │ "Handoff" │ │ │ │ │ │─ Transfer History ───>│ │ │ │ │ │ Process Query │ │ │ │ │<─── Final Response ───│ │ │ │ │<─ Response ────│ │ │ │ │Guardrail Validation Flow
Section titled “Guardrail Validation Flow”┌────────────────────────────────────────────────────────────┐│ Message Flow: Input and Output Guardrails │└────────────────────────────────────────────────────────────┘
User Input │ ▼┌─────────────────────┐│ Input Guardrails │ Safe?├─────────────────────┤ Yes│ - Check injection │─────────┐│ - Validate format │ ││ - Check permissions │ │└─────────┬───────────┘ │ │ No │ ▼ │ Block & │ Return Error │ ▼ ┌─────────────────────┐ │ Execute Agent │ └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ Output Guardrails │ Valid? ├─────────────────────┤ Yes │ - Check toxicity │─────────┐ │ - Validate response │ │ │ - Verify compliance │ │ └─────────┬───────────┘ │ │ No │ ▼ │ Regenerate & │ Retry │ │ │ └────────┬───────────┘ │ ▼ Return to UserSession Management
Section titled “Session Management”SQLite Session Persistence
Section titled “SQLite Session Persistence”┌────────────────────────────────────────────────────────────┐│ Session Storage: SQLite Architecture │└────────────────────────────────────────────────────────────┘
In-Memory Conversation Context │ ▼ ┌──────────────────┐ │ SQLiteSession │ │ (Agent SDK) │ └────────┬─────────┘ │ ┌──────────┴──────────┐ │ │ ▼ ▼ Write On Auto-Load On Message Agent Run │ │ ▼ ▼ ┌───────────────────────────┐ │ SQLite Database │ │ conversations.db │ ├───────────────────────────┤ │ session_id | message_id │ │ role | content | timestamp│ └───────────────────────────┘ ▲ │ │ └──────────> Persistent Storage │ (File System) └─── Query & Retrieve ────────── For ContextMulti-Backend Session Support
Section titled “Multi-Backend Session Support”┌────────────────────────────────────────────────────────────┐│ Session Storage: Multiple Backend Options │└────────────────────────────────────────────────────────────┘
┌─────────────────────┐│ Agent/Runner ││ ││ session=... │└──────────┬──────────┘ │ ┌──────┼──────┬──────────┬────────────┐ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ SQLite Redis SQLAlchemy OpenAI In-Memory │ │ │ │ │ │ │ │ │ │ ├──FS ├─CPU │ │ └─ RAM │ │ │ │ (testing) │ │ │ │ │ │ ├─ PostgreSQL │ │ ├─ MySQL │ │ └─ Others │ │ │ └─ Distributed │ Cache Layer │ └─ Local File StorageTool Integration Patterns
Section titled “Tool Integration Patterns”Function Tool Execution Flow
Section titled “Function Tool Execution Flow”┌────────────────────────────────────────────────────────────┐│ 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 Architecture
Section titled “Hosted Tools Architecture”┌────────────────────────────────────────────────────────────┐│ Hosted Tools: OpenAI and External Services │└────────────────────────────────────────────────────────────┘
Agent withHosted Tools │ ├─ WebSearchTool() │ └──> Real-time web search │ Results returned │ ├─ FileSearchTool() │ └──> Vector database search │ Semantic matching │ ├─ CodeInterpreterTool() │ └──> Python sandbox execution │ Results captured │ ├─ ComputerControlTool() │ └──> Desktop automation │ Mouse/keyboard control │ └─ ImageGenerationTool() └──> DALL-E image generation URLs returnedGuardrail Integration
Section titled “Guardrail Integration”Input/Output Guardrail Pipeline
Section titled “Input/Output Guardrail Pipeline”┌────────────────────────────────────────────────────────────┐│ Guardrail Architecture: Safety Pipeline │└────────────────────────────────────────────────────────────┘
User Input │ ▼┌──────────────────────────┐│ Input Guardrail 1 ││ (Injection Detection) │└──────┬───────────────────┘ │ Pass ▼┌──────────────────────────┐│ Input Guardrail 2 ││ (Content Filtering) │└──────┬───────────────────┘ │ Pass ▼┌──────────────────────────┐│ Execute Agent │└──────┬───────────────────┘ │ ▼┌──────────────────────────┐│ Output Guardrail 1 ││ (Toxicity Check) │└──────┬───────────────────┘ │ Pass ▼┌──────────────────────────┐│ Output Guardrail 2 ││ (Compliance Check) │└──────┬───────────────────┘ │ Pass ▼ Return ResultMCP Integration Architecture
Section titled “MCP Integration Architecture”MCP Server Integration Pattern
Section titled “MCP Server Integration Pattern”┌────────────────────────────────────────────────────────────┐│ 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 blame └─ Parse HTMLStdio vs HTTP MCP
Section titled “Stdio vs HTTP MCP”┌────────────────────────────────────────────────────────────┐│ 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 endpointProduction Deployment Topologies
Section titled “Production Deployment Topologies”Monolithic Deployment
Section titled “Monolithic Deployment”┌────────────────────────────────────────────────────────────┐│ Single Service: Monolithic Deployment │└────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────┐│ Load Balancer ││ (nginx/haproxy) │└────────────┬─────────────────────────┘ │ ┌────────┼────────┬────────┐ │ │ │ │ ▼ ▼ ▼ ▼┌────┐ ┌────┐ ┌────┐ ┌────┐│App │ │App │ │App │ │App ││Pod │ │Pod │ │Pod │ │Pod ││ │ │ │ │ │ │ ││Agent │Agent │Agent │Agent││Svc │ │Svc │ │Svc │ │Svc │└────┘ └────┘ └────┘ └────┘│ │ │ │└─────────┼─────────┼─────────┘ │ ▼ ┌──────────────┐ │ PostgreSQL │ │ (Sessions) │ └──────────────┘ │ ▼ ┌──────────────┐ │ Redis │ │ (Cache) │ └──────────────┘Microservices Deployment
Section titled “Microservices Deployment”┌────────────────────────────────────────────────────────────┐│ Multiple Services: Microservices Deployment │└────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────┐│ API Gateway │└────────────┬─────────────────────────┘ │ ┌────────┼────────┬────────┐ │ │ │ │ ▼ ▼ ▼ ▼┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐│Triage│ │Billing│ │Tech │ │Account│Svc │ │Svc │ │Support│ │Svc│ │ │ │ │Svc │ ││Agents│ │Agents│ │Agents│ │Agents└──────┘ └──────┘ └──────┘ └──────┘ │ │ │ │ └────────┼────────┼────────┘ │ ┌────────┴────────┐ │ │ ▼ ▼┌──────────────┐ ┌──────────────┐│ PostgreSQL │ │ Redis ││ (Databases) │ │ (Cache) │└──────────────┘ └──────────────┘Serverless Deployment
Section titled “Serverless Deployment”┌────────────────────────────────────────────────────────────┐│ Event-Driven: Serverless Deployment │└────────────────────────────────────────────────────────────┘
Events │ ├─ API Gateway Request │ └─> Lambda Function (Query Handler) │ ├─ SQS Message │ └─> Lambda Function (Background Processor) │ └─ CloudWatch Trigger └─> Lambda Function (Scheduled Job)
Each Lambda: ├─ Agent Initialization ├─ Execute Agent └─ Return Result
Storage: ├─ DynamoDB (Sessions) ├─ S3 (File Storage) └─ RDS (Database)Error Handling Flows
Section titled “Error Handling Flows”Retry and Fallback Mechanism
Section titled “Retry and Fallback Mechanism”┌────────────────────────────────────────────────────────────┐│ Error Handling: Retry and Fallback Strategy │└────────────────────────────────────────────────────────────┘
Execute Task │ ▼ Fail? │ Yes ▼┌─────────────────┐│ Retry 1 / 3 ││ (wait 1s) │└────────┬────────┘ │ Fail? │ Yes ▼ ┌─────────────────┐ │ Retry 2 / 3 │ │ (wait 2s) │ └────────┬────────┘ │ Fail? │ Yes ▼ ┌─────────────────┐ │ Retry 3 / 3 │ │ (wait 4s) │ └────────┬────────┘ │ Fail? │ Yes ▼ Use Fallback Agent │ ▼ Return ResultCircuit Breaker Pattern
Section titled “Circuit Breaker Pattern”┌────────────────────────────────────────────────────────────┐│ Resilience: Circuit Breaker States │└────────────────────────────────────────────────────────────┘
┌──────────┐ │ CLOSED │ (Normal operation) │ │ └────┬─────┘ │ Failures exceed │ threshold (5) ▼ ┌──────────┐ │ OPEN │ (Reject requests) │ │ └────┬─────┘ │ Wait timeout (60s) ▼ ┌──────────────┐ │ HALF_OPEN │ (Testing recovery) │ │ └────┬────┬────┘ │ │ Success Failure │ │ ▼ ▼ CLOSED OPENScalability Patterns
Section titled “Scalability Patterns”Horizontal Scaling Architecture
Section titled “Horizontal Scaling Architecture”┌────────────────────────────────────────────────────────────┐│ Scaling: Horizontal Expansion │└────────────────────────────────────────────────────────────┘
┌──────────────────┐ │ Load Balancer │ │ (Round Robin) │ └────────┬─────────┘ │ ┌────────────────────┼────────────────────┐ │ │ │ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │Instance│ │Instance│ │Instance│ │ 1 │ │ 2 │ │ 3 │ │ │ │ │ │ │ │Agents │ │Agents │ │Agents │ │Pool │ │Pool │ │Pool │ └────────┘ └────────┘ └────────┘ │ │ │ └────────────────────┼────────────────────┘ │ ┌────────▼────────┐ │ Shared Session │ │ Storage │ │ (PostgreSQL) │ └─────────────────┘Caching Strategy
Section titled “Caching Strategy”┌────────────────────────────────────────────────────────────┐│ Performance: Multi-Level Caching │└────────────────────────────────────────────────────────────┘
Request │ ▼┌─────────────────────┐│ L1: In-Memory Cache ││ (Same Process) │ Hit?└────────┬────────────┘ Return │ Miss ▼┌─────────────────────┐│ L2: Redis Cache ││ (Shared across │ Hit?│ processes) │ Return & Update L1└────────┬────────────┘ │ Miss ▼┌─────────────────────┐│ L3: Database Cache ││ (Long-lived) │ Hit?└────────┬────────────┘ Return & Update L1/L2 │ Miss ▼ Execute Agent │ ▼ Update all cache layersReal-World Patterns
Section titled “Real-World Patterns”Financial Research Workflow
Section titled “Financial Research Workflow”┌────────────────────────────────────────────────────────────┐│ 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 ReportCustomer Support Triage
Section titled “Customer Support Triage”┌────────────────────────────────────────────────────────────┐│ 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 AgentThis comprehensive diagrams guide provides visual clarity for understanding OpenAI Agents SDK architectures and patterns.