# 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. ## 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 Apache-2.0. Source at https://github.com/openai/openai-agents-python and https://github.com/openai/openai-agents-js. ## 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]]