# OpenAI Agents SDK The OpenAI Agents SDK is [[OpenAI]]'s framework for building **multi-agent applications** ; agents, sub-agents, handoffs, guardrails, and tracing as first-class primitives. Originally Python-only as the successor to OpenAI's older Swarm prototype, it now also has a TypeScript implementation. It sits at the *agent-runtime* layer of [[AI SDKs]], peer to [[Claude Code SDK]] and [[GitHub Copilot SDK]]. The pitch: instead of writing your own agent loop on top of [[OpenAI SDK|the OpenAI SDK]], use the SDK that already encodes patterns OpenAI recommends ; `@openai/agents` for TS, `openai-agents` for Python. ## Maturity — persistently pre-1.0 Worth knowing before you build on it: the SDK has stayed on `0.x` for its entire life. As of 2026-08-20 the Python package is at **0.22.0** and the TypeScript package at **0.17.0**, roughly eighteen months after launch. There is no 1.0 and no committed date for one. The APIs are usable and widely deployed, but OpenAI has not made a stability commitment, so treat minor bumps as potentially breaking and pin accordingly. ## The provider-plurality catch The SDK is OpenAI-first in a stronger sense than the marketing suggests. Non-OpenAI models are not supported natively — they go through an extension that **wraps the [[Vercel AI SDK]]'s provider layer**. If you are running Anthropic or Google models through it, you are running the Vercel AI SDK underneath with the Agents SDK on top, and tracing is degraded on that path compared to the first-party OpenAI route. This inverts the usual reasoning. If your workload is mostly non-OpenAI, the Agents SDK is a lossy layer over a substrate you could use directly; the honest comparison is "Agents SDK handoffs and guardrails" versus "the Vercel AI SDK plus your own loop", not "provider-neutral framework A versus B". ## Core Primitives - **Agent** ; a configured model + system prompt + tools + (optional) sub-agents - **Tool** ; a typed function the agent can call (Pydantic / Zod schemas drive both validation and the model's tool spec) - **Handoff** ; one agent transfers control to another mid-task ; the routing primitive that makes multi-agent flows tractable - **Guardrail** ; pre/post checks on agent inputs and outputs (PII filters, content policy, schema validation) - **Tracing** ; built-in span instrumentation for the whole agent run, exportable to OpenAI's dashboard or any OTel sink - **Sessions / state** ; conversation memory and run-state lifecycle ## Python Example ```python from agents import Agent, Runner triage = Agent( name="triage", instructions="Route the user to the right specialist agent.", handoffs=[support_agent, sales_agent], ) result = Runner.run_sync(triage, "I want to upgrade my plan.") print(result.final_output) ``` ## TypeScript Example ```ts import { Agent, run } from "@openai/agents"; const support = new Agent({ name: "support", instructions: "Help the user with technical issues.", tools: [searchKb, openTicket], }); const result = await run(support, "Wifi isn't working on my new device"); ``` ## When To Use It - **Multi-agent applications**: triage → specialist agent flows, planner-executor patterns, research-then-write teams - **You want OpenAI's opinionated agent shape** rather than rolling your own agent loop on top of the [[OpenAI SDK|raw SDK]] - **You need handoffs as a primitive** ; doing this manually with raw chat completions is doable but verbose - **You want first-class tracing** without bolting on OpenTelemetry yourself ## Where It Doesn't Fit - **Single-agent apps with no multi-agent fan-out** ; the raw [[OpenAI SDK]] is simpler - **Coding-agent embedding** ; for "I want Claude Code / Copilot in my app," use [[Claude Code SDK]] / [[GitHub Copilot SDK]] - **Production-managed runtime** ; for fully hosted agents, [[Claude Managed Agents]] is closer to that shape; the OpenAI Agents SDK runs on *your* infra ## Comparison with Sibling Frameworks - **vs raw [[OpenAI SDK]]**: SDK is the model client; this is the agent loop on top - **vs [[Vercel AI SDK]]**: Vercel's SDK is provider-neutral and does *not* include multi-agent handoffs as a primitive; the OpenAI Agents SDK is OpenAI-first and does - **vs [[Pydantic AI]]**: same neighborhood in Python; Pydantic AI leans harder into typed I/O, OpenAI Agents SDK leans harder into multi-agent orchestration - **vs [[Mastra AI]]**: Mastra is the TypeScript-side equivalent ; both target multi-agent apps with tools, memory, and tracing ## License [[MIT License|MIT]] for both implementations. Source at https://github.com/openai/openai-agents-python and https://github.com/openai/openai-agents-js. (This note previously said Apache-2.0; that was wrong — both repos and both published packages are MIT.) ## References - Python: https://github.com/openai/openai-agents-python - TypeScript: https://github.com/openai/openai-agents-js - Documentation: https://openai.github.io/openai-agents-python/ ## Related - [[OpenAI]] - [[OpenAI SDK]] - [[AI SDKs]] - [[Claude Code SDK]] - [[GitHub Copilot SDK]] - [[Claude Managed Agents]] - [[Vercel AI SDK]] - [[Pydantic AI]] - [[Mastra AI]] - [[AI Agent Harness]]