OpenAI Agents SDK
OpenAI's code-first SDK for applications that own orchestration, tool execution, approvals, state, and multi-agent collaboration.
When To Use It
OpenAI's docs draw the boundary clearly: use the Responses API when one model call plus tools and application-owned logic is enough; use the Agents SDK when the application owns orchestration, tool execution, approvals, and state. Source: OpenAI Agents SDK docs, https://developers.openai.com/api/docs/guides/agents, 2026-06-18
Use the Agents SDK for:
- multi-agent workflows with handoffs
- agents-as-tools delegation
- built-in tracing and run inspection
- guardrails around input/output
- sessions / conversation state management
- human-in-the-loop approval
- MCP and hosted tool integration
- sandboxed or long-horizon agent work
- realtime / voice agents in the JS/TS ecosystem
Implementations
| Implementation | Best fit | Notes |
|---|---|---|
Python (openai-agents-python) |
backend services, orchestration, server agents | provider-agnostic; supports OpenAI Responses and Chat Completions plus other LLMs |
JS/TS (openai-agents-js) |
TypeScript apps, browser/voice surfaces | provider-agnostic; includes realtime/voice agent focus |
The Python GitHub README describes the SDK as provider-agnostic and lists core primitives: agents, sandbox agents, agents as tools, handoffs, tools, guardrails, HITL, sessions, and tracing. Source: openai/openai-agents-python, https://github.com/openai/openai-agents-python, 2026-06-18
Core Primitives
- Agent: LLM plus instructions, tools, guardrails, and handoffs.
- Tool: function, hosted tool, MCP server, or other action surface.
- Handoff / agent-as-tool: delegate to a specialist.
- Guardrail: validate inputs/outputs and short-circuit unsafe runs.
- Session: conversation/history management.
- Trace: inspect and debug agent runs.
- Human-in-the-loop: pause for approval or input.
- Sandbox agent: preconfigured long-horizon execution context.
- Realtime agent: voice-capable agent workflow.
How It Compares
| Tool | Choose when |
|---|---|
| OpenAI Agents SDK | OpenAI-centered code-first orchestration, handoffs, tracing, guardrails |
| Vercel AI SDK | TypeScript/React/Next.js AI app UI, streaming, provider abstraction, HarnessAgent |
| LangGraph | explicit graph/state-machine orchestration |
| Raw Responses API | a single model call plus tools is enough |
For Kevin projects, this SDK is most relevant when building agent services where OpenAI tracing/guardrails/sessions are first-class. For frontend-heavy TypeScript apps, Vercel AI SDK remains the default UI integration layer.
Design Implications
- Treat tracing as part of production readiness, not optional observability confetti.
- Pair HITL with durable execution when approvals may wait longer than a process lifetime.
- Keep guardrails narrow and testable; do not turn them into a second prompt blob.
- Use MCP tools through a governed registry/permission layer, not arbitrary discovery.
Hosted Agents API
OpenAI's Agents API (public beta, 2026-09-10) runs the Codex harness as a managed service: OpenAI runs the loop, model calls, tool use, long sessions and context management, while the developer sets capabilities and chooses where code runs. Sandboxes can be brought from a provider (Cloudflare, Daytona, E2B, Modal and others), deployed in the customer's VPC, or hosted by OpenAI with files, packages, skills and plugins. Use the SDK when you need to own the loop; use the API when you want OpenAI to run it. Source: X/@OpenAIDevs thread, 2026-09-10; Source: OpenAI
Timeline
- 2026-06-18 | Cross-linked the SDK to Agent Runtime Architecture and Agent Trajectory Evaluation because its runner/tracing primitives are runtime and trajectory infrastructure. Source: whole-wiki graph audit, 2026-06-18
- 2026-06-18 | Updated from official OpenAI docs and GitHub repos: clarified Responses API vs Agents SDK boundary, Python/JS implementations, core primitives, and Kevin routing. Source: OpenAI Agents SDK docs, https://developers.openai.com/api/docs/guides/agents, 2026-06-18; openai/openai-agents-python, 2026-06-18; openai/openai-agents-js, 2026-06-18
- 2026-06-12 | Cross-linked OpenAI Moderation API as optional harm classifier for user-facing guardrails alongside SDK guardrails. private page
- 2026-05-31 | Tool page created from OpenAI Agents SDK Python and JS/TS repos. Source: openai/openai-agents-python + openai-agents-js, 2026-05-31