OpenAI Agents SDK

January 30, 2026

The OpenAI Agents SDK is OpenAI's official framework for building production agent systems. It evolved from the experimental Swarm framework into a production-ready toolkit with multi-agent orchestration, built-in tools, and observability.

From Swarm to Production

Swarm was OpenAI's experimental multi-agent framework. The Agents SDK is its production evolution:

OpenAI just released the Agents SDK, a powerful evolution of the Swarm SDK, designed for seamless AI agent development.

Key upgrades:

Production stability
Built-in tracing
TypeScript support
Richer tool ecosystem

Core Primitives

Agent

The fundamental unit — an autonomous system with tools and instructions:

from openai_agents import Agent

agent = Agent(
    name="research-agent",
    instructions="You research topics thoroughly before responding.",
    tools=[web_search, file_reader],
)

Handoff

Transfer control between agents:

from openai_agents import Handoff

# Define when to hand off to a specialist
handoff = Handoff(
    target="specialist-agent",
    trigger="When the user asks about legal matters",
)

Guardrail

Constraints on agent behavior:

from openai_agents import Guardrail

guardrail = Guardrail(
    rule="Never share personal information",
    action="refuse",
)

Built-in Tools

The SDK includes powerful built-in tools:

Web Search: Real-time information retrieval
File Search: Query documents and knowledge bases
Code Interpreter: Execute Python code
Image Generation: Create images via DALL-E
Computer Use: Control computer interfaces

from openai_agents.tools import web_search, code_interpreter

agent = Agent(
    name="research-assistant",
    tools=[web_search, code_interpreter],
)

Multi-Agent Orchestration

Build systems where agents collaborate:

# Specialized agents
researcher = Agent(name="researcher", tools=[web_search])
analyst = Agent(name="analyst", tools=[code_interpreter])
writer = Agent(name="writer", instructions="Write clear, concise reports")

# Orchestrator that coordinates them
orchestrator = Agent(
    name="orchestrator",
    instructions="Coordinate research, analysis, and writing tasks",
    handoffs=[researcher, analyst, writer],
)

As one developer noted:

seamless flow for hierarchical communication between orchestrator/minion agents (handoffs). Everyone in the space has written boilerplate that handles similar problems. This library does it super well.

Observability

Built-in tracing for debugging and monitoring:

from openai_agents import trace

with trace() as t:
    result = agent.run("Research quantum computing")
    
# Inspect the trace
print(t.steps)  # All decisions and tool calls
print(t.tokens)  # Token usage
print(t.duration)  # Time taken

TypeScript Support

Full-featured TypeScript SDK:

import { Agent, Runner } from "@openai/agents";

const agent = new Agent({
  name: "assistant",
  instructions: "You are a helpful assistant",
  tools: [getWeather, searchWeb],
});

const runner = new Runner(agent);
const result = await runner.run("What's the weather in Tokyo?");

The Responses API

The Agents SDK builds on the new Responses API, which combines:

Chat Completions simplicity
Assistants API tool capabilities
Built-in tool integration

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{"type": "web_search"}],
    input="What happened in AI today?",
)

When to Use It

Good fit:

Building with OpenAI models
Need multi-agent coordination
Want built-in observability
Need web search or code execution

Consider alternatives when:

Need multi-provider support (use Vercel AI SDK)
Building on Anthropic models (use Claude SDK)
Need custom orchestration logic (use LangGraph)

Installation

# Python
pip install openai-agents

# TypeScript
npm install @openai/agents

Migration from Swarm

If you used Swarm:

# Swarm (deprecated)
from swarm import Swarm, Agent

# Agents SDK
from openai_agents import Agent, Runner

Key differences:

Runner replaces Swarm for execution
Better typing and validation
Production-grade tracing
More tool options

Sources

New tools for building agents — OpenAI announcement
Agents SDK Documentation — Official docs
GitHub: openai/swarm — Original Swarm (deprecated)