OpenAI Agents SDK (Python / TypeScript) and Agent Builder — relation to the APIs
Status: DOCUMENTED (SDK is open source; not an HTTP API surface — no live probe applicable). Agent Builder: DEPRECATED, shutdown 2026-11-30.
Sources: Agents overview / compare runtimes · Agents SDK · Quickstart · Define agents · Running agents · Sandbox agents · Orchestration and handoffs · Guardrails and approvals · Agent Builder · Migrate from Agent Builder · GitHub openai/openai-agents-python, openai/openai-agents-js.
Last verified: 2026-09-18.
Packages
| Language | Package / repo | Install |
|---|---|---|
| Python | openai-agents — https://github.com/openai/openai-agents-python |
pip install openai-agents |
| TypeScript | @openai/agents — https://github.com/openai/openai-agents-js |
npm install @openai/agents |
| (ChatKit server) | openai-chatkit (Python), @openai/chatkit (JS) |
see chatkit.md |
The SDK is a client-side agent loop: it calls the Responses API (default model transport; Chat Completions and third-party providers are pluggable), runs your tools locally, manages handoffs between agents, guardrails, human approvals, sessions (your storage or Responses conversation state) and tracing (traces dashboard). It does not call /v1/agents.
Concepts (API-level view)
| SDK concept | Underlying API surface |
|---|---|
Agent(name, instructions, model, tools, handoffs, output_type) |
POST /v1/responses per model call (instructions → instructions, tools → tools[], output_type → text.format json_schema) |
| Function tools | Responses function tool → SDK executes your callable, feeds function_call_output |
| Hosted tools (web search, file search, code interpreter, computer use, image gen, MCP) | Responses hosted tools / remote MCP |
| Handoffs | modelled as function tools that switch the active agent |
| Sessions / memory | your store, or Responses conversation / previous_response_id |
| Sandbox agents | provider integrations (containers, mounts, snapshots) run by your code |
| Guardrails, approvals | run in your process; approvals pause before tool execution |
| Tracing | spans exported to the OpenAI traces dashboard (api.traces.*) or OTLP |
| Realtime/voice agents | Realtime API |
Choosing a runtime (docs table)
| Agents API (managed Codex harness) | Agents SDK | Responses API | |
|---|---|---|---|
| Use for | long-running tasks, OpenAI saves progress | custom tools/workflows in your app | direct model calls |
| Integration effort | low | medium | high |
| State | sessions, turns, items on OpenAI | your storage / SDK sessions | manual or Conversations |
| Execution environment | OpenAI-hosted, self-hosted or none | your runtime + sandbox providers | yours |
Agent Builder (visual canvas) — DEPRECATED
Drag-and-drop workflow designer (nodes, typed edges, preview, trace graders). Publish → versioned workflow id used by ChatKit sessions (workflow.id) or exported as Agents SDK code (Code → Agents SDK → TypeScript/Python). Shutdown 2026-11-30 (deprecations 2026-06-03-agent-builder). Migration paths: (1) run the exported SDK code yourself; (2) paste the export into ChatGPT Agents studio to create a workspace agent (see workspace-agents.md). ChatKit remains available through the custom-server integration.