Study 70 files · 12 subfolders
Copy to Workspace 00_OVERVIEW Shared from "Study" on Inkdown
OpenAI Agents Python SDK - Comprehensive Codebase Study
Introduction
This is a comprehensive study of the OpenAI Agents Python SDK codebase. The SDK is a lightweight yet powerful framework for building multi-agent workflows that is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs.
Project Structure
Core Architecture
The SDK is built around several key concepts:
basic-ques
Agents - LLMs configured with instructions, tools, guardrails, and handoffs
Runner - The execution engine that runs agents
Tools - Functions that agents can call to perform actions
Items - The unit of work in an agent run (messages, tool calls, etc.)
Guardrails - Safety checks for input and output validation
Handoffs - Mechanism for delegating to other agents
Sessions - Automatic conversation history management
Tracing - Built-in tracking of agent runs
Sandbox - Isolated execution environments for agents
Key Design Principles
1. Provider Agnostic The SDK supports multiple model providers through a unified interface. You can use OpenAI's Responses API, Chat Completions API, or integrate with 100+ other LLMs through the MultiProvider system.
2. Type Safety The entire SDK is written with Python type hints and uses Pydantic for data validation. This ensures type safety and provides excellent IDE support.
3. Async-First The SDK is designed with async/await as the primary execution model. This allows for efficient concurrent operations, especially when dealing with multiple tools or handoffs.
4. Streaming Support All operations support streaming, allowing you to get real-time updates as the agent processes requests.
5. Human-in-the-Loop Built-in support for pausing agent runs for human approval, inspection, or intervention through the RunState system.
6. Extensibility The SDK is designed to be extended through:
Custom tools
Custom model providers
Custom guardrails
Lifecycle hooks
Extensions (MCP, memory backends, etc.)
Module Organization
Core Modules (src/agents/)
agent.py - Agent and AgentBase classesrun.py - Runner and execution orchestrationtool.py - Tool system and built-in toolsitems.py - Run items (messages, tool calls, etc.)guardrail.py - Input and output guardrailshandoffs/ - Agent delegation systemmemory/ - Session and conversation persistencemodels/ - Model provider implementationssandbox/ - Isolated execution environmentstracing/ - Observability and debuggingrun_internal/ - Internal runtime implementationextensions/ - Additional functionality (MCP, memory, etc.)
Data Flow
Basic Agent Execution Flow
Input - User provides input (string or list of items)Context Setup - RunContextWrapper is created with user contextGuardrails - Input guardrails run (if configured)Model Call - Agent calls LLM with instructions and toolsTool Execution - If model calls tools, they are executedOutput Guardrails - Output guardrails run (if configured)Result - Final output is returnedSession Update - Conversation history is saved (if session is configured)
Streaming Flow The streaming flow follows the same path but yields events as they happen:
Model response chunks
Tool call events
Tool output events
Final result
Key Abstractions
Agent An agent is the main building block. It represents an AI assistant with:
Instructions (system prompt)
Tools it can use
Guardrails for safety
Handoffs to other agents
Output schema for structured responses
Runner The Runner is responsible for executing agents. It handles:
Turn management (multi-turn conversations)
Tool execution
Handoff delegation
Session persistence
Error handling
Streaming
Tool Tools are functions that agents can call. They can be:
Function tools (Python functions)
Hosted tools (OpenAI tools like file search, web search)
MCP tools (from Model Context Protocol servers)
Agent tools (other agents exposed as tools)
Shell tools (command execution)
Computer tools (computer interaction)
Item Items represent units of work in an agent run:
MessageOutputItem - Messages from the LLM
ToolCallItem - Tool calls made by the LLM
ToolCallOutputItem - Results from tool execution
HandoffCallItem - Handoff to another agent
ReasoningItem - Model reasoning (for reasoning models)
RunState RunState captures the complete state of an agent run, enabling:
Pause and resume
Human-in-the-loop workflows
State inspection
Debugging
Configuration Hierarchy Configuration flows from most specific to most general:
Agent-level - Settings on the Agent instanceRunConfig-level - Settings for a specific runGlobal defaults - Default settings for the SDK This allows fine-grained control while maintaining sensible defaults.
Error Handling The SDK uses a structured error handling approach:
UserError - Errors due to user input or configurationModelBehaviorError - Errors from unexpected model behaviorAgentsException - Base exception for SDK errorsToolTimeoutError - Tool execution timeoutMaxTurnsExceeded - Agent exceeded maximum turnsGuardrail Tripwires - Guardrail violations
Testing Strategy
pytest for test executioninline-snapshot for snapshot testspytest-asyncio for async test supportcoverage.py for coverage tracking Tests are organized by functionality:
test_agent_*.py - Agent-specific teststest_run_*.py - Runner and execution teststest_tool_*.py - Tool system teststest_guardrails.py - Guardrail teststest_handoff_*.py - Handoff testsIntegration tests in examples/
Documentation Documentation is built with MkDocs and Material theme:
Source in docs/
Built output in site/
API reference auto-generated from docstrings
Multi-language support (ja, ko, zh)
Development Workflow
Setup - uv sync to install dependenciesDevelopment - Make changes with uv run pythonTesting - make tests to run test suiteLinting - make lint and make formatType checking - make typecheckDocumentation - make build-docsCoverage - make coverage
Performance Considerations
Async execution - Tools and guardrails run concurrently when possibleConnection pooling - Reuse HTTP connections for model callsPrompt caching - Support for prompt cache keysSession compaction - Intelligent conversation history managementTool use tracking - Prevent infinite loops
Security Considerations
Input validation - Guardrails for input sanitizationTool approval - Human approval for sensitive toolsSandbox isolation - Isolated execution for file system accessAPI key management - Secure handling of API keysTracing controls - Options to exclude sensitive data from traces
Next Steps This overview provides a high-level understanding of the SDK. The following documents dive deep into each component:
Agent System - Deep dive into agentsRunner System - Execution engineTool System - Tools and tool executionItems System - Run items and eventsGuardrails - Input/output validationHandoffs - Agent delegationMemory & Sessions - Conversation persistenceModel Providers - LLM integrationSandbox System - Isolated executionTracing - ObservabilityRun State - State managementContext - Execution contextLifecycle Hooks - Event callbacksConfiguration - Settings and configError Handling - Error managementStreaming - Real-time updatesExtensions - Extending the SDKMCP Integration - Model Context ProtocolBest Practices - Usage patternsArchitecture Patterns - Design patterns 