The OpenAI Agents SDK (Python) is a compact, batteries-included toolkit for building agents that can call tools, hand off control, and trace their own reasoning across steps. It aims to make multi-agent workflows as approachable as a simple function call while staying flexible enough to power production systems (OpenAI, 2025).
openai
Organization
openai-agents-python
A lightweight, powerful framework for multi-agent workflowsA practical problem the SDK targets
Real-world AI apps juggle many concerns: planning, tool use, external APIs, safety checks, and sometimes multiple specialists that need to coordinate. Hard-coding this logic quickly turns into a tangle of prompts and callbacks.
The Agents SDK abstracts that complexity into a clean event loop: the agent decides what to do next (speak, call a function, or hand off), the runner executes, and you get structured, traceable results (OpenAI Docs, 2025).
How the SDK answers that need
The core is an agent loop orchestrated by Runner. Each turn, the model returns either a final answer or instructions to invoke tools or hand off to another agent. This pattern gives you predictable control flow without sacrificing the flexibility of LLM-driven decisions.
Sessions provide memory across turns so you can carry context safely, and guardrails let you validate input/output before the next step runs.
Key features you can build on
The repository, browsable via examples/ and documented at project docs centers on a few sturdy ideas:
- Agents: Configurable LLMs with instructions, tools, optional output types, and handoffs that coordinate control between agents (Agents guide, OpenAI Docs, 2025).
- Tools: Python functions exposed with a simple decorator so models can call code deterministically. Great for retrieval, DB access, or API calls.
- Handoffs: A first-class way to switch to a more specialized agent without losing context, ideal for routing and triage.
- Sessions: Built-in conversation memory via
SQLiteSessionand a cleanSessionprotocol for custom stores.- Tracing: Automatic spans for debugging and optimization with integrations for Logfire, AgentOps, Braintrust, Scorecard, and more (Tracing docs).
Under the hood: design and tech choices
The SDK is provider-agnostic. It works with the OpenAI Responses or Chat Completions APIs and can reach 100+ LLMs through LiteLLM (BerriAI, 2024). Structured outputs let you declare an output_type so the loop can stop when a response matches your schema. The codebase is pure Python, typed, and organized for clarity: see src/agents/ for the core and AGENTS.md for deeper conceptual notes.
Validation and configuration lean on modern Python tooling. You can spot familiar names in acknowledgements f from Pydantic (Pydantic, 2024) and PydanticAI to docs built with MkDocs Material and API docs via Griffe. For long-running or human-in-the-loop tasks, there is a maintained integration with Temporal and the Temporal Python SDK (Temporal, 2024).
LiteLLM in practice
LiteLLM provides two complementary paths: a Python SDK and a Proxy Server (LLM Gateway). Both expose a unified, OpenAI-style interface across 100+ providers and models with consistent response shapes, streaming, and a router for retries and fallbacks. The Proxy adds centralized auth, logging, cost tracking, and rate limits; the SDK is ideal when you just need a lightweight client in your code (BerriAI Docs, 2025).
With the Agents SDK, you typically integrate LiteLLM in two ways: point the official OpenAI Python client at a LiteLLM Proxy by setting base_url, or call litellm.completion() inside a tool function when an agent needs a non-OpenAI provider. This keeps your agent loop, guardrails, sessions, and tracing the same while swapping models and providers behind the scenes (BerriAI, 2025).
# Option A: Route the OpenAI client through a LiteLLM Proxy
from openai import OpenAI
client = OpenAI(api_key="anything", base_url="http://localhost:4000")
resp = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello"}],
)
# Option B: Call LiteLLM directly inside a tool function
from litellm import completion
resp2 = completion(
model="anthropic/claude-3-sonnet-20240229",
messages=[{"role": "user", "content": "Hello"}],
) For centralized governance, see the Proxy quick start and features (auth hooks, logging, spend tracking, and rate limits) in the LiteLLM docs (BerriAI Docs, 2025).
Quick tour in code
Here are two tiny examples to demonstrate the feel of the API. They assume your OPENAI_API_KEY is set and that you installed the package with pip install openai-agents. See examples/ for more.
from agents import Agent, Runner, function_tool
# 1) Hello world
agent = Agent(name="Assistant", instructions="You are a concise assistant.")
print(Runner.run_sync(agent, "Say hello to the Agents SDK.").final_output)
# 2) Handoffs + a simple tool
@function_tool
def get_weather(city: str) -> str:
return f"Weather in {city}: sunny"
spanish = Agent(name="Spanish", instructions="Solo hablas Español.")
english = Agent(name="English", instructions="You only speak English.")
triage = Agent(
name="Triage",
instructions="Route to the agent that matches the user's language.",
tools=[get_weather],
handoffs=[spanish, english],
)
print(Runner.run_sync(triage, "What's the weather in Tokyo?").final_output)
Underneath, the runner executes an agent loop: call the LLM, check for final output, process any tool calls, and follow handoffs when present. If you specify an output_type, the loop ends when the model returns a valid structured object; otherwise, it stops at the first plain response without tool calls. The behavior is documented in Agents, Handoffs, and Guardrails (OpenAI Docs, 2025).
Good fits and real-world use
The SDK shines when your app has distinct steps or specialties. Examples: a triage agent routes by language or intent; a research agent calls search and RAG tools; a planner delegates to a calculator or calendar tool; or a customer support agent hands off to a policy checker before replying. For voice experiences, optional extras enable voice via pip install "openai-agents[voice]", and you can mix the Agents SDK with the official OpenAI Python library for broader API coverage (OpenAI, 2025).
More use cases to spark ideas
Customer support copilot with compliance checks: A frontline agent drafts answers while a policy agent runs guardrails to catch PII, tone, and contractual constraints before responses go out. Handoffs route escalations to specialized agents (billing, refunds) with traceable decisions. Tracing integrations (Logfire, Braintrust) help teams audit tricky conversations and improve prompts over time.
RAG-powered research and summarization: A planner agent breaks down a research task, calls retrieval tools to query your knowledge base, and synthesizes structured outputs (via
output_type) for dashboards or downstream APIs. Using the OpenAI Python SDK, you can pair the agent loop with the Responses API and streaming to deliver progressive results to users.Analytics Q&A with tool calling: An analyst agent answers questions by calling function tools that hit your warehouse (SQL) or metrics service. The agent explains steps and returns concise, structured findings, while sessions keep multi-turn context (e.g., follow-up filters, time ranges) consistent across queries.
Operations automation with human-in-the-loop: Long-running workflows (procurement, onboarding, incident response) can be orchestrated via the Temporal integration. Agents gather data, draft actions, and wait for approvals; humans unblock decisions, and the flow resumes reliably, even across failures. See Temporal + Agents for examples.
Multilingual triage and localization: A triage agent detects language and hands off to locale-specific agents for accurate tone and terminology. Tool calls fetch glossary terms or product names, and guardrails validate output style before publishing.
Developer assistants for code and docs: A router agent distinguishes between "explain", "refactor", and "test" intents, handing off to focused agents that call linters, test runners, or doc generators. With sessions, the assistant carries context from previous edits and comments.
Community, contributions, and roadmap signals
The repository is active with frequent releases, a sizable contributor list, and a healthy set of issues and dependents. You can explore patterns under examples/agent_patterns, read conceptual docs in AGENTS.md, and learn by browsing tests/. Open a PR or issue to propose new tools, sessions, or tracing processors; the maintainers explicitly acknowledge the broader ecosystem and invite extension (OpenAI, 2025).
Usage and license
Getting started is straightforward: create a virtual environment (venv or uv), install openai-agents, set OPENAI_API_KEY, and run an example. Development uses familiar commands via make to run tests, type checks, and linters. The project is released under the MIT License, which permits reuse, modification, and distribution with attribution and without warranty.
Impact and what comes next
Agents are fast becoming the substrate for real apps: they combine language understanding with structured decision-making and code execution. By baking in handoffs, guardrails, sessions, and tracing, the Agents SDK offers a pragmatic foundation for teams that want velocity without giving up control. Expect to see deeper ecosystem integrations (vector DBs, evaluation suites, observability backends), richer guardrails, and ergonomic patterns for voice and realtime interactions as the platform evolves. The open-source model makes it straightforward to adapt or extend to your stack.
About OpenAI
OpenAI builds general-purpose AI systems and developer tooling, including the OpenAI API and ChatGPT, with a focus on safety and practical utility. Learn more at openai.com/about.
Wrapping up
If you need agents that can route, call tools, remember context, and explain themselves after the fact, this SDK is thoughtfully engineered for that job. Explore the repository, study the docs, run the examples, and consider contributing patterns or integrations back to the community.
Inside OpenAI's Agents SDK for Python