OpenAI Agents SDK

The OpenAI Agents SDK is a production-ready Python framework for building agentic AI apps with very few abstractions. It's the successor to OpenAI's earlier Swarm project and uses native Python constructs — functions, decorators, dataclasses — rather than bespoke DSLs.

Install

pip install openai-agents
export OPENAI_API_KEY=sk-...

Python 3.10+ required. TypeScript/JS port has historically been community-maintained; this page covers the Python-first official SDK.

Core primitives

Three concepts. That's most of the API.

1. Agent — an LLM with instructions, tools, and optional guardrails
2. Handoff — one agent delegating to another
3. Guardrail — input or output validation that can block a turn

Everything else (agent loop, tool execution, tracing, sessions) is handled by the SDK.

First win

A triage agent that hands off to specialized agents:

from agents import Agent, Runner

billing_agent = Agent(
    name="Billing",
    instructions="Handle billing questions. Be concise.",
)

tech_agent = Agent(
    name="Tech Support",
    instructions="Handle technical support. Ask for reproduction steps.",
)

triage = Agent(
    name="Triage",
    instructions="Route the user to Billing or Tech Support based on their question.",
    handoffs=[billing_agent, tech_agent],
)

result = Runner.run_sync(triage, "My invoice is wrong")
print(result.final_output)

The triage agent picks the right specialist via a handoff, which is a tool call under the hood. You get tracing, sessions, and the agent loop for free.

Features

• Built-in agent loop — no manual tool-execution loop to write
• Handoffs — first-class delegation; agents hand off by "calling" another agent as a tool
• Guardrails — input + output validators that can halt a turn
• Sessions — conversation state persisted across turns, with optional memory
• Tracing — built-in visibility into every step; pairs with OpenAI's dashboard
• Sandbox agents — isolated workspace execution for code-running tasks
• Realtime voice — streaming voice agents via gpt-realtime-1.5

Tool definition

Tools are plain Python functions with a decorator:

from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    # implementation...
    return f"Sunny, 72°F in {city}"

agent = Agent(
    name="Weather",
    instructions="Answer weather questions.",
    tools=[get_weather],
)

result = Runner.run_sync(agent, "Weather in Tokyo?")

The decorator introspects the signature and builds the tool schema automatically.

Guardrails

Block a turn if input/output violates policy:

from agents import Agent, Runner, GuardrailFunctionOutput, input_guardrail

@input_guardrail
def no_pii(input_text: str) -> GuardrailFunctionOutput:
    if any(marker in input_text for marker in ["SSN:", "credit card:"]):
        return GuardrailFunctionOutput(should_block=True, message="Blocked: possible PII")
    return GuardrailFunctionOutput(should_block=False)

agent = Agent(
    name="Safe",
    instructions="Answer questions.",
    input_guardrails=[no_pii],
)

When to use

• Lightweight and Python-first — if you want minimal abstractions on top of OpenAI's Chat Completions + tool calls
• Multi-agent workflows with handoffs — the triage pattern above maps directly
• OpenAI-native stack — if your models are already OpenAI, this has the tightest integration

When not to use

• Non-OpenAI models — works best with OpenAI; other providers are possible but less polished than Pydantic AI or LangChain
• Python not available — no official TypeScript equivalent in 2026
• You need graph-based orchestration — LangGraph is a better fit for complex branching / checkpointing

Gotchas

• Handoffs are tool calls. Debugging a failed handoff means looking at tool-call traces, not a separate handoff system.
• Guardrails can be bypassed by a determined prompt. Layer them with OS-level sandboxing for sensitive tasks.
• Sessions default to in-memory. For multi-user / multi-process, wire your own persistence.
• Breaking changes during 2024 → 2025 transition from Swarm. Verify imports against current docs.

Further reading

• Official docs: openai.github.io/openai-agents-python
• Framework Comparison — when to pick this vs Claude Agent SDK / Pydantic AI