OpenAI Agents SDK

Warnings

• breaking openai v1.x is no longer supported. Must use openai>=2.0.0.
  Fix: pip install 'openai>=2.0.0' before installing openai-agents
• breaking Python 3.9 support dropped. Minimum runtime is Python 3.10.
  Fix: Upgrade to Python 3.10+
• deprecated Swarm is the deprecated predecessor. Do not use openai/swarm — openai-agents is the production replacement.
  Fix: Migrate to openai-agents. Primitives are similar but not identical.
• gotcha MCP server methods (list_tools(), etc.) now take AgentBase, not Agent as type hint. Runtime behavior unchanged — objects are still Agent instances.
  Fix: Update type annotations: replace Agent with AgentBase where type errors appear
• gotcha Agent.as_tool() return type narrowed from Tool to FunctionTool. May cause type errors if you relied on the broader union.
  Fix: Update type annotations to FunctionTool where needed
• gotcha RealtimeAgent is beta. Breaking changes expected. Azure realtime: use GA URL path (wss://.../openai/v1/realtime), not legacy beta path (/openai/realtime?api-version=...).
  Fix: Pin version if using RealtimeAgent in production. Use GA URL format for Azure.
• gotcha WebSocket transport for Responses API is opt-in. Default remains HTTP. Must call set_default_openai_responses_transport('websocket') to enable globally.
  Fix: No action needed unless you want WebSocket mode explicitly

Install

• pip install openai-agents pip
• uv add openai-agents uv
• pip install 'openai-agents[voice]' pip (voice)
• pip install 'openai-agents[redis]' pip (redis sessions)

Imports

• Agent

  from agents import Agent

  Core agent primitive
• Runner

  from agents import Runner

  Synchronous and async run entrypoint
• handoffs

  Agent(handoffs=[other_agent])

  Pass agent instances directly, not strings
• RealtimeAgent

  from agents.realtime import RealtimeAgent

  Voice agent — beta, expect breaking changes
• AgentBase

  from agents import AgentBase

  MCPServer.list_tools() and similar now take AgentBase not Agent — typing change, objects are still Agent instances

Quickstart

Minimal single-agent run

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)