# 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](https://developers.openai.com/api/docs/guides/agents) · [Agents SDK](https://developers.openai.com/api/docs/guides/agents/sdk) · [Quickstart](https://developers.openai.com/api/docs/guides/agents/quickstart) · [Define agents](https://developers.openai.com/api/docs/guides/agents/define-agents) · [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents) · [Sandbox agents](https://developers.openai.com/api/docs/guides/agents/sandboxes) · [Orchestration and handoffs](https://developers.openai.com/api/docs/guides/agents/orchestration) · [Guardrails and approvals](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals) · [Agent Builder](https://developers.openai.com/api/docs/guides/agent-builder) · [Migrate from Agent Builder](https://developers.openai.com/api/docs/guides/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.