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.
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. Source: User capture, 2026-06-12
- 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