One Open Source Project a Day (Part 45): OpenAI Agents SDK Python - Lightweight Multi-Agent Workflow Framework Supporting 100+ LLMs and Realtime Voice

Introduction

"A lightweight, powerful framework for multi-agent workflows."

This is Part 45 of the "One Open Source Project a Day" series. Today's project is OpenAI Agents SDK Python (GitHub).

Building multi-agent workflows requires handling complex issues like agent orchestration, tool calling, session management, tracing, and debugging? OpenAI Agents SDK Python is OpenAI's open-source lightweight multi-agent workflow framework: supports OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs (via LiteLLM), built-in tracing visualization, session management, guardrails, human-in-the-loop, realtime voice agents. Based on Pydantic and PydanticAI, provides clean APIs, suitable for production environments.

Why it matters:

🚀 Lightweight Framework: Clean APIs, quick start, production-ready
🤖 Multi-Agent Orchestration: Supports Agents as tools, Handoffs, parallel execution patterns
🔧 100+ LLM Support: Unified interface via LiteLLM, supports OpenAI, Anthropic, Google, open-source models
📊 Built-in Tracing: Visualization, debugging, monitoring, supports evaluation and fine-tuning
🎤 Realtime Voice: Supports realtime voice agents, automatic interruption detection and context management
🔒 Guardrails: Input/output validation and safety checks
💬 Session Management: Persistent memory layer, maintains context
👤 Human-in-the-Loop: Built-in human intervention mechanisms

What You'll Learn

Core concepts of OpenAI Agents SDK (Agents, Tools, Handoffs, Guardrails, Sessions, Tracing)
Multi-agent orchestration patterns: LLM autonomous orchestration vs code deterministic orchestration
Agent configuration: instructions, tools, handoffs, guardrails, structured outputs
Tool system: function tools, MCP tools, hosted tools
Session management and tracing visualization
Realtime voice agent usage
Comparison with LangChain, CrewAI, PydanticAI

Prerequisites

Basic Python 3.10+ usage
Basic understanding of AI agents
Understanding of LLM API calls (optional)
Basic knowledge of multi-agent systems (optional)

Project Background

Project Overview

OpenAI Agents SDK Python is OpenAI's open-source lightweight multi-agent workflow framework for building production-grade agent applications. It is not a heavyweight framework, but provides clean APIs and core features for developers to quickly build multi-agent systems.

Core Features:

Lightweight: Clean APIs, minimal configuration, quick start
Multi-LLM Support: Supports OpenAI API and 100+ other LLMs (via LiteLLM)
Multi-Agent Orchestration: Supports Agents as tools, Handoffs, parallel execution patterns
Production-Ready: Built-in tracing, session management, guardrails, human-in-the-loop
Realtime Voice: Supports realtime voice agents, automatic interruption detection
Extensible: Based on Pydantic, easy to extend and customize

Core Problems Solved:

Complex orchestration of multi-agent workflows
Unified interface for different LLM providers
Tracing and debugging of agent execution processes
Management and persistence of session context
Security validation of inputs/outputs
Human intervention mechanisms

Target Users:

Developers building multi-agent applications
Teams needing support for multiple LLMs
Enterprises requiring production-grade agent systems
Applications needing realtime voice agents
Beginners wanting to quickly start agent development

Author/Team

Team: OpenAI (GitHub)
Background: Officially maintained by OpenAI, deeply integrated with OpenAI API
Philosophy: Provide lightweight, production-ready multi-agent framework
Website: openai.github.io/openai-agents-python

Project Statistics

⭐ GitHub Stars: ~19.4k
🍴 Forks: ~3.2k
📦 Version: v0.10.5 (actively maintained, 1,201+ commits)
📄 License: MIT
🌐 Website: openai.github.io/openai-agents-python
📚 Documentation: Documentation
💬 Community: GitHub Issues
📝 Related Version: JavaScript/TypeScript Version

Tech Stack:

Language: Python (99.8%)
Core Dependencies: Pydantic, PydanticAI, LiteLLM
Tools: uv, ruff, MkDocs, Griffe
Python Version: 3.10+

Core Features

Core Purpose

The core purpose of OpenAI Agents SDK is to provide a lightweight, production-ready multi-agent workflow framework that enables developers to:

Quickly Build Agents: Clean APIs, minimal configuration
Orchestrate Multi-Agents: Supports Agents as tools, Handoffs, parallel execution patterns
Unified LLM Interface: Supports 100+ LLM providers via LiteLLM
Trace and Debug: Built-in visualization, debugging, monitoring tools
Manage Sessions: Persistent memory layer, maintains context
Validate Security: Guardrails for input/output validation
Human Intervention: Human-in-the-loop mechanisms
Realtime Voice: Supports realtime voice agents

Use Cases

Multi-Agent Collaboration Systems
- Use Agents as tools pattern, Manager Agent calls Specialist Agents
- Use Handoffs pattern, Specialist Agent takes over conversation
- Parallel execution of multiple agent tasks
LLM Application Development
- Applications needing support for multiple LLM providers
- Need unified interface to switch between models
- Need tracing and debugging of LLM calls
Production-Grade Agent Systems
- Need session management and context maintenance
- Need input/output security validation
- Need human intervention mechanisms
Realtime Voice Applications
- Build realtime voice agents
- Automatic interruption detection and context management
- Voice interaction applications
Research and Experimentation
- Rapid prototyping
- Agent behavior evaluation and optimization
- Multi-agent pattern experimentation

Quick Start

Installation:

# Using venv
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install openai-agents
 
# Voice support (optional)
pip install 'openai-agents[voice]'
 
# Redis session support (optional)
pip install 'openai-agents[redis]'
 
# Using uv (recommended)
uv init
uv add openai-agents
uv add 'openai-agents[voice]'  # Voice support
uv add 'openai-agents[redis]'  # Redis session

First Agent:

from agents import Agent, Runner
 
# Create agent
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant"
)
 
# Run agent
result = Runner.run_sync(
    agent,
    "Write a haiku about recursion in programming."
)
print(result.final_output)
 
# Output:
# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.

Using Tools:

from agents import Agent, Runner, Tool
 
# Define tool function
def calculate(expression: str) -> str:
    """Evaluate a mathematical expression."""
    return str(eval(expression))
 
# Create agent with tools
agent = Agent(
    name="Calculator",
    instructions="You are a helpful calculator assistant.",
    tools=[Tool(calculate)]
)
 
# Run
result = Runner.run_sync(agent, "What is 15 * 23?")
print(result.final_output)

Key Features

Agents (Agent Configuration)
- Required: name, instructions
- Optional: model, tools, handoffs, guardrails, structured outputs, temperature, top_p
- Supports custom model configuration
Agents as Tools / Handoffs (Agent Orchestration)
- Agents as tools: Manager Agent calls Specialist Agents, retains control
- Handoffs: Specialist Agent takes over conversation
- Can be combined: Triage Agent can Handoff to Specialist, Specialist can still call other Agents as tools
Tools (Tool System)
- Function tools: Python functions automatically converted to tools, auto-generates schema
- MCP tools: Model Context Protocol tool calling support
- Hosted tools: Supports hosted external tools
- Automatic function calling and parameter validation
Guardrails (Security Validation)
- Input validation: Validates user input
- Output validation: Validates agent output
- Configurable safety checks
- Prevents inappropriate content
Human-in-the-Loop (Human Intervention)
- Built-in human intervention mechanisms
- Supports approval workflows
- Human feedback integration
Sessions (Session Management)
- Automatic conversation history management
- Persistent memory layer
- Supports manual history management, Sessions, OpenAI-managed server-side state
- Redis support (optional)
Tracing (Tracing)
- Built-in visualization interface
- Debugging and monitoring
- Supports evaluation and fine-tuning
- Agent run tracing
Realtime Agents (Realtime Voice)
- Realtime voice agents
- Automatic interruption detection
- Context management
- Voice interaction support

Project Advantages

Comparison	OpenAI Agents SDK	LangChain	CrewAI	PydanticAI
Learning Curve	✅ Lightweight, quick start	⚠️ Steep, many concepts	⚠️ Medium, need to understand team concepts	⚠️ Medium
LLM Support	✅ 100+ LLMs (LiteLLM)	⚠️ Manual integration needed	⚠️ Limited	⚠️ Manual integration needed
Multi-Agent Orchestration	✅ Agents as tools, Handoffs	⚠️ LangGraph requires additional learning	✅ Team orchestration	⚠️ Manual implementation needed
Tracing & Debugging	✅ Built-in visualization	⚠️ LangSmith (paid)	⚠️ Limited	⚠️ Limited
Session Management	✅ Built-in Sessions	⚠️ Manual implementation needed	⚠️ Manual implementation needed	⚠️ Manual implementation needed
Guardrails	✅ Built-in support	⚠️ Manual implementation needed	⚠️ Manual implementation needed	⚠️ Manual implementation needed
Realtime Voice	✅ Built-in support	❌ None	❌ None	❌ None
Production-Ready	✅ Officially maintained, production-ready	⚠️ Community maintained	⚠️ Community maintained	⚠️ Community maintained

Why Choose OpenAI Agents SDK?

Lightweight framework: Clean APIs, quick start
Multi-LLM support: Unified interface via LiteLLM, supports 100+ LLMs
Built-in features: Tracing, sessions, guardrails, human-in-the-loop out of the box
Production-ready: Officially maintained by OpenAI, suitable for production
Realtime voice: Built-in realtime voice agent support

Deep Dive

Architecture Design

OpenAI Agents SDK uses a lightweight, modular design, based on Pydantic and PydanticAI, unified LLM interface via LiteLLM.

Core Components:

OpenAI Agents SDK
├── Agent (Agent Configuration)
│   ├── name, instructions (required)
│   ├── model, tools, handoffs (optional)
│   ├── guardrails, structured outputs (optional)
│   └── temperature, top_p (optional)
├── Runner (Execution Engine)
│   ├── run_sync (synchronous execution)
│   ├── run_async (asynchronous execution)
│   └── Streaming response support
├── Tools (Tool System)
│   ├── Function tools (auto-conversion)
│   ├── MCP tools (Model Context Protocol)
│   └── Hosted tools
├── Sessions (Session Management)
│   ├── Manual history management
│   ├── Sessions (persistent)
│   └── OpenAI server-side state
├── Tracing (Tracing)
│   ├── Visualization interface
│   ├── Debugging and monitoring
│   └── Evaluation and fine-tuning
└── Realtime (Realtime Voice)
    ├── Voice agents
    ├── Interruption detection
    └── Context management

Design Principles:

Lightweight: Minimal dependencies, clean APIs
Modular: Independent components, can be used separately
Extensible: Based on Pydantic, easy to extend
Production-Ready: Built-in tracing, sessions, guardrails

Multi-Agent Orchestration Patterns

OpenAI Agents SDK supports two orchestration patterns:

1. LLM Autonomous Orchestration (Orchestrating via LLM)

LLM autonomously plans and decides agent flow using tools and handoffs:

from agents import Agent, Runner
 
# Manager Agent
manager = Agent(
    name="Manager",
    instructions="You coordinate tasks and delegate to specialists.",
    tools=[
        # Specialist Agents as tools
        Agent(
            name="Researcher",
            instructions="You research topics thoroughly."
        ),
        Agent(
            name="Writer",
            instructions="You write clear, engaging content."
        )
    ]
)
 
# LLM autonomously decides which Specialist to call
result = Runner.run_sync(
    manager,
    "Research and write about quantum computing."
)

2. Code Deterministic Orchestration (Orchestrating via Code)

Use Python primitives (e.g., asyncio.gather) for deterministic flows:

import asyncio
from agents import Agent, Runner
 
# Define multiple agents
researcher = Agent(name="Researcher", instructions="...")
writer = Agent(name="Writer", instructions="...")
reviewer = Agent(name="Reviewer", instructions="...")
 
# Parallel execution
async def workflow(topic: str):
    # Parallel research
    research_result = await Runner.run_async(
        researcher, f"Research: {topic}"
    )
    
    # Parallel writing
    write_result = await Runner.run_async(
        writer, f"Write about: {research_result.final_output}"
    )
    
    # Parallel review
    review_result = await Runner.run_async(
        reviewer, f"Review: {write_result.final_output}"
    )
    
    return review_result
 
# Execute
result = asyncio.run(workflow("quantum computing"))

Core Patterns:

Agents as tools: Manager Agent calls Specialist Agents, retains control
Handoffs: Specialist Agent takes over conversation
Combined patterns: Triage Agent can Handoff to Specialist, Specialist can still call other Agents as tools

Tool System

Function Tools (Auto-Conversion):

from agents import Agent, Runner, Tool
 
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    # Implementation logic
    return f"Weather in {city}: Sunny, 25°C"
 
agent = Agent(
    name="WeatherBot",
    instructions="You help users get weather information.",
    tools=[Tool(get_weather)]  # Auto-conversion, auto-generates schema
)
 
result = Runner.run_sync(agent, "What's the weather in Beijing?")

MCP Tools (Model Context Protocol):

from agents import Agent, Runner
from agents.tools import MCPTool
 
# MCP tool integration
mcp_tool = MCPTool(
    server_name="my-mcp-server",
    tool_name="search"
)
 
agent = Agent(
    name="MCPBot",
    instructions="You use MCP tools to help users.",
    tools=[mcp_tool]
)

Session Management

Manual History Management:

from agents import Agent, Runner
 
agent = Agent(name="ChatBot", instructions="...")
 
# Manual history management
history = []
result1 = Runner.run_sync(agent, "Hello", history=history)
history.append({"role": "user", "content": "Hello"})
history.append({"role": "assistant", "content": result1.final_output})
 
result2 = Runner.run_sync(agent, "What did I say?", history=history)

Sessions (Persistent):

from agents import Agent, Runner, Session
 
agent = Agent(name="ChatBot", instructions="...")
 
# Create session
session = Session.create()
 
# Use session
result = Runner.run_sync(
    agent,
    "Hello",
    session_id=session.id
)
 
# Session automatically maintains history
result2 = Runner.run_sync(
    agent,
    "What did I say?",
    session_id=session.id  # Automatically includes previous conversation
)

Tracing and Debugging

OpenAI Agents SDK has built-in tracing functionality, provides visualization interface:

from agents import Agent, Runner
 
agent = Agent(name="DebugBot", instructions="...")
 
# Run agent (auto-traced)
result = Runner.run_sync(agent, "Debug this code...")
 
# View tracing
# Access tracing UI: http://localhost:8000/trace
# Or use API to get tracing data

Tracing features include:

Agent run visualization
Tool call tracing
LLM call tracing
Performance monitoring
Evaluation and fine-tuning support

Realtime Voice Agents

from agents import Agent, RealtimeAgent
 
# Create realtime voice agent
agent = Agent(
    name="VoiceAssistant",
    instructions="You are a helpful voice assistant."
)
 
# Start realtime voice
realtime_agent = RealtimeAgent(agent)
 
# Connect and interact
realtime_agent.connect()
# Automatically handles voice input, interruption detection, context management

Realtime voice features:

Automatic interruption detection
Context management
Voice input/output
Realtime interaction

Project Links and Resources

Official Resources

🌟 GitHub: https://github.com/openai/openai-agents-python
🌐 Website: openai.github.io/openai-agents-python
📚 Documentation: Documentation
💬 Community: GitHub Issues
📦 PyPI: openai-agents
📝 JS/TS Version: openai-agents-js

Pydantic: pydantic.dev
PydanticAI: pydantic.ai
LiteLLM: litellm.ai
LangChain: langchain.com
CrewAI: crewai.com

Target Audience

Multi-Agent Application Developers: Need to build multi-agent collaboration systems
LLM Application Developers: Need support for multiple LLM providers
Production Environment Users: Need production-grade agent systems with built-in tracing, sessions, guardrails
Realtime Voice Applications: Need to build realtime voice agents
Rapid Prototyping: Want to quickly start agent development

Learning Value:

✅ Multi-agent orchestration patterns and practices
✅ LiteLLM unified LLM interface usage
✅ Agent tracing and debugging methods
✅ Session management and context maintenance
✅ Guardrails and security validation
✅ Realtime voice agent development

Visit my homepage for more useful knowledge and interesting products