OpenAI Agents SDK

Overview

The OpenAI Agents SDK is an open-source, lightweight framework for building agentic applications. It is the production upgrade of OpenAI's earlier Swarm experiment, designed around a small set of primitives instead of heavy abstractions: Agents (LLMs configured with instructions, tools, and guardrails), Handoffs (specialized tool calls that transfer control between agents), and Guardrails (configurable input and output safety checks). A built-in agent loop runs tool calls and handoffs until a final output is produced, so you focus on agent logic rather than orchestration plumbing.

The SDK is published in two officially supported flavors that share the same primitives:

• TypeScript / JavaScript — npm install @openai/agents (this listing's primary documentation URL)
• Python — pip install openai-agents

Despite the OpenAI name, the SDK is provider-agnostic. It works out of the box with OpenAI's Responses and Chat Completions APIs, and supports non-OpenAI models through adapters such as the Vercel AI SDK integration in the JS/TS package.

Core primitives

• Agents — declarative Agent objects that bundle a model, instructions, tools, guardrails, and child agent handoffs.
• Handoffs — first-class transfers of control between agents, modeled as specialized tool calls. Useful for routing and specialist sub-agents.
• Guardrails — input and output validators that can trip a tripwire and halt the run with a typed error such as InputGuardrailTripwireTriggered.
• Function tools — define tools with Zod (TS) or Pydantic (Python) schemas; the SDK validates arguments and pipes results back into the agent loop.
• Sessions — built-in memory primitives like MemorySession and OpenAIConversationsSession for managing multi-turn state without rolling your own store.
• Tracing — every run, tool call, and handoff is captured as spans you can view in OpenAI's tracing UI or export via custom processors for debugging and optimization.

Notable features

• Native MCP server support via MCPServerStdio, MCPServerSSE, MCPServerStreamableHttp, and a hosted MCP tool helper, so you can expose any Model Context Protocol server as agent tools.
• Realtime Agents for voice — RealtimeAgent and RealtimeSession with WebRTC, WebSocket, and SIP transports. A separate browser-optimized @openai/agents-realtime package keeps client bundles small.
• Human-in-the-loop approval points where the run pauses on a tool call until your application approves or rejects it.
• Streaming responses for tokens, tool calls, and handoff events.
• Hosted tools including webSearchTool, fileSearchTool, codeInterpreterTool, imageGenerationTool, computerTool, and shellTool.
• Structured outputs with schema-validated final results.
• Parallel agent runs and aggregation patterns for fan-out workflows.
• Configurable retries with built-in retryPolicies and a MaxTurnsExceededError safety net via maxTurns.

When it fits

The Agents SDK is the natural choice when your stack is OpenAI-native and you want minimal ceremony: Responses API, Realtime API, OpenAI tracing, and OpenAI hosted tools all work without adapters. It is also a strong fit for teams who liked Swarm's simplicity but need production features like guardrails, sessions, MCP, and tracing.

It is a weaker fit when you need strong multi-provider routing across many vendor APIs as a first-class concern; frameworks built around a provider-router abstraction will give you more out of the box there.

Supported runtimes

• Node.js 22+, Deno, and Bun for the JS/TS package
• Cloudflare Workers (experimental, with nodejs_compat)
• Python 3.9+ for the Python package
• Browser bundle for Realtime voice agents

License

MIT, with both packages developed in the open on GitHub by OpenAI.