OpenAI Agents SDK

OpenAI Agents SDK

The OpenAI Agents SDK is a production-ready, open-source framework designed to simplify the development of agentic AI applications. Released as an evolution of OpenAI's earlier Swarm experimentation, it provides a minimal set of primitives—Agents, Handoffs, Guardrails, Sessions, and Tracing—to enable complex multi-agent interactions without unnecessary abstractions. This SDK is particularly suited for Python developers (requiring Python 3.9 or newer) and supports both synchronous and asynchronous workflows, making it ideal for building scalable, real-time AI systems.

Key Features and Core Concepts

At its heart, the SDK revolves around Agents, which are large language models (LLMs) configured with custom instructions, tools, guardrails, and handoffs. Agents can process inputs, invoke tools (like custom functions for tasks such as weather queries), and delegate tasks dynamically. For instance, a triage agent can assess user input and hand off to specialized agents, such as one for Spanish or English responses.

Handoffs are a specialized mechanism for seamless agent-to-agent transfers, allowing workflows to branch based on context without rigid hierarchies. This is crucial for multi-agent patterns like supervisor-led teams or iterative refinement loops.

Guardrails ensure safety and reliability by validating inputs and outputs against configurable rules, preventing issues like hallucinations or unsafe responses in production environments.

Sessions handle conversation history automatically, supporting options like SQLite for local storage, Redis for distributed setups, or custom implementations. This eliminates boilerplate for maintaining state across runs, enabling natural, multi-turn interactions.

Tracing is built-in for observability, logging agent runs, tool calls, and handoffs. It integrates with tools like Logfire, AgentOps, and Braintrust, and traces can be viewed in the OpenAI Dashboard for debugging and optimization.

The SDK is provider-agnostic, working with OpenAI's APIs out-of-the-box but extensible to over 100 LLMs through LiteLLM. It also supports advanced features like Temporal integration for durable, long-running workflows with human-in-the-loop capabilities, ideal for tasks spanning hours or days.

Getting Started

Installation is straightforward via pip or uv:

pip install openai-agents

For voice-enabled agents, use pip install 'openai-agents[voice]'; for Redis sessions, pip install 'openai-agents[redis]'.

A basic 'Hello World' example demonstrates creating an agent and running a simple query:

from agents import Agent, Runner
 
agent = Agent(name="Assistant", instructions="You are a helpful assistant")
 
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.

More advanced patterns include function tools (e.g., a get_weather function) and handoff workflows, as shown in the README examples for language-based routing.

Agent Loop Mechanics

The SDK's Runner executes an adaptive loop: It invokes the LLM, processes tool calls or handoffs, and continues until a 'final output' is reached. Final outputs can be plain text (no tools/handoffs) or structured via Pydantic models using OpenAI's structured outputs. A max_turns limit prevents infinite loops.

Common patterns supported include deterministic flows, iterative evaluations, and multi-agent orchestration, with examples in the repository's examples/agent_patterns directory.

Use Cases and Extensibility

This framework shines in applications like financial research agents, real-time voice interactions (via Realtime API integration), or deep research workflows combining the SDK with OpenAI's Deep Research API. It's extensible for custom sessions, tracing processors, and even non-OpenAI models.

With over 16,000 GitHub stars and active community contributions, the SDK draws from tools like Pydantic, LiteLLM, and Ruff, fostering an ecosystem for agentic AI development. For full documentation, visit the homepage, and explore JavaScript/TypeScript variants for broader language support.