1# Agents SDK1# Agents
2 2
3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4 4
5Agents are applications that plan, call tools, collaborate across specialists, and keep enough state to complete multi-step work.5Agents can plan and complete tasks using tools, work with other agents, and maintain context across steps. Choose a runtime based on where you want orchestration to run and who should manage the state between tasks.
6
7## Get your first agent running
8
9Start with the [Agents SDK quickstart](https://developers.openai.com/api/docs/guides/agents/quickstart) to install the SDK, define one agent, and run it. Once that works, return here to choose the next capability your application needs.
10
11## Get the Agents SDK
12
13Use the GitHub repositories for more examples, issues, and language-specific reference details.
14
15
16
17 [TypeScript SDK
18
19
20
21 Open the TypeScript SDK repository on GitHub.](https://github.com/openai/openai-agents-js)
22 [Python SDK
23
24
25
26 Open the Python SDK repository on GitHub.](https://github.com/openai/openai-agents-python)
27
28
29 6
30## Choose your starting point7## Choose your starting point
31 8
32| If you want to | Start here | Why |9| You want to | Start here |
33| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |10| ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
34| Build a code-first agent app | [Quickstart](https://developers.openai.com/api/docs/guides/agents/quickstart) | This is the shortest path to a working SDK integration. |11| Run an agent with the Codex harness managed by OpenAI | [Agents API](https://developers.openai.com/api/docs/guides/agents-api/quickstart) |
35| Define one specialist cleanly | [Agent definitions](https://developers.openai.com/api/docs/guides/agents/define-agents) | Start here when you are still shaping the contract for a single agent. |12| Control the agent loop in your application with reusable agents, tools, and handoffs | [Agents SDK](https://developers.openai.com/api/docs/guides/agents/quickstart) |
36| Choose models, defaults, and transport | [Models and providers](https://developers.openai.com/api/docs/guides/agents/models) | Use this when model choice, provider setup, or transport strategy affects the workflow. |13| Work directly with model responses and control your integration | [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses) |
37| Understand the runtime loop and state | [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents) | This is where the agent loop, streaming, and continuation strategies live. |14| Add an embedded chat experience | [ChatKit](https://developers.openai.com/api/docs/guides/chatkit) |
38| Run work in a container-based environment | [Sandbox agents](https://developers.openai.com/api/docs/guides/agents/sandboxes) | Use this when the agent needs files, commands, packages, snapshots, mounts, or provider links. |
39| Design specialist ownership | [Orchestration and handoffs](https://developers.openai.com/api/docs/guides/agents/orchestration) | Use this when you need more than one agent and must decide who owns the reply. |
40| Add validation or human review | [Guardrails and human review](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals) | Use this when the workflow should block or pause before risky work continues. |
41| Understand what a run returns | [Results and state](https://developers.openai.com/api/docs/guides/agents/results) | This page explains final output, resumable state, and next-turn surfaces. |
42| Add hosted tools, function tools, or MCP | [Using tools](https://developers.openai.com/api/docs/guides/tools#usage-in-the-agents-sdk) and [Integrations and observability](https://developers.openai.com/api/docs/guides/agents/integrations-observability) | Tool semantics live in the platform tools docs; SDK-specific MCP and tracing live here. |
43| Inspect and improve runs | [Integrations and observability](https://developers.openai.com/api/docs/guides/agents/integrations-observability) and [evaluate agent workflows](https://developers.openai.com/api/docs/guides/agent-evals) | Use traces for debugging first, then move into evaluation loops. |
44| Build a voice-first workflow | [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents) | Use the SDK's voice pipeline and realtime agent patterns. |
45
46## Build with the SDK
47
48Use the SDK track when your server owns deployment, tool implementations, state storage, and approval decisions, while the SDK runs the agent loop and invokes those tools. That path is the best fit when you want:
49
50- typed application code in TypeScript or Python
51- direct control over tools, MCP servers, and runtime behavior
52- custom storage or server-managed conversation strategies
53- tight integration with existing product logic or infrastructure
54
55A typical SDK reading order is:
56 15
57- Start with [Quickstart](https://developers.openai.com/api/docs/guides/agents/quickstart) to get one working run on screen.16<a id="agents-sdk-vs-responses-api"></a>
58- Use [Agent definitions](https://developers.openai.com/api/docs/guides/agents/define-agents) and [Models and providers](https://developers.openai.com/api/docs/guides/agents/models) to shape one specialist cleanly.
59- Continue to [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents), [Orchestration and handoffs](https://developers.openai.com/api/docs/guides/agents/orchestration), and [Guardrails and human review](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals) as the workflow grows more complex.
60- Use [Results and state](https://developers.openai.com/api/docs/guides/agents/results) and [Integrations and observability](https://developers.openai.com/api/docs/guides/agents/integrations-observability) when application logic depends on the run object or deeper visibility into behavior.
61 17
62## Agents SDK vs. Responses API18<a id="compare-agent-runtimes"></a>
63 19
64Use the Responses API when you want to own the loop. Use the Agents SDK when you want the SDK to run it.20## Compare agent runtime options
65 21
66### Choose the Responses API when22| | Agents API | Agents SDK | Responses API |
23| ------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------- |
24| **Use for** | Long-running tasks where OpenAI manages the agent and saves its progress | Building agents with custom tools and workflows in your application | Calling models directly or building an agent from scratch |
25| Where the agent runs | OpenAI runs a managed Codex harness | The SDK runs inside your application | Your application, with optional hosted orchestration |
26| Agent integration effort | Low | Medium | High |
27| State between tasks | Saved session configuration, turns, and items | Your storage and SDK sessions, or Responses conversation state | Manual history, response chaining, or Conversations |
28| Tool execution | Service-connected tools, application function handlers, and an optional sandbox | Tools and integrations configured in your application | Hosted tools and tools your application runs |
29| Execution environment | OpenAI hosted sandbox, self-hosted sandbox, or no sandbox | Your runtime and sandbox provider integrations | Your own execution environment |
30| Start here | [Agents API overview](https://developers.openai.com/api/docs/guides/agents-api/overview) | [Agents SDK overview](https://developers.openai.com/api/docs/guides/agents/sdk) | [Responses guide](https://developers.openai.com/api/docs/guides/migrate-to-responses) |
67 31
68- You want direct control over model interactions, output items, tools, state, and orchestration, whether the workflow takes one call or many.32The Agents API runs the Codex harness and manages the underlying agent infrastructure so you can focus on what your agents do. It includes automatic context compaction, multi-agent orchestration, programmatic tool calling, and support for MCP servers. See [Architecture](https://developers.openai.com/api/docs/guides/agents-api/architecture).
69- You want to implement custom tool routing, loops, or branching directly in your application.
70 33
71In the [Responses function-calling flow](https://developers.openai.com/api/docs/guides/function-calling#the-tool-calling-flow), your application receives function calls, executes them, returns their output, and calls the model again.34The Agents SDK gives your application control over deployment, storage, approvals, and runtime integration. Its runner handles the agent loop and handoffs. See [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents).
72 35
73For example, a Responses API workflow might search a knowledge base and generate a cited answer.
74 36
75### Choose the Agents SDK when
76 37
77- You want the SDK to manage the agent loop and recurring orchestration such as repeated tool calls or branching.
78- Different specialists need different instructions, tools, or policies.
79- You want built-in sessions, tracing, guardrails, or resumable approval flows.
80 38
81The [Agents SDK runner](https://developers.openai.com/api/docs/guides/agents/running-agents#the-agent-loop) performs the tool loop, switches agents after handoffs, and stops when the run finishes or pauses for approval.39## Add tools, skills, and prompt caching
82 40
83For example, an Agents SDK workflow might investigate a support request, hand it to the correct specialist, call internal systems, request approval for a refund, and record the result.41Tool design, reusable skills, and prompt caching apply across agent workflows. Their configuration and lifecycle can differ by API.
84 42
85### Compare the Responses API and Agents SDK43- Start with [Using tools](https://developers.openai.com/api/docs/guides/tools) for function calling, MCP, and hosted capabilities.
44- Read [Programmatic Tool Calling](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling) for orchestration with JavaScript and the configuration for each API.
45- Use [Skills](https://developers.openai.com/api/docs/guides/tools-skills) for reusable instructions and the supported loading mechanisms.
46- Read [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching) for shared caching behavior, then [Agents API observability and usage](https://developers.openai.com/api/docs/guides/agents-api/observability) for session accounting.
86 47
87| | Responses API | Agents SDK |48An Agents API session, an SDK session, a Responses conversation, and a sandbox are different resources. Follow the state and cleanup instructions for the runtime you choose.
88| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
89| **Best for** | Custom model-powered features and workflows | Bounded conversational or transactional workflows with defined tools and recurring orchestration patterns |
90| **Core abstraction** | A model response | An agent run |
91| **Tools** | Platform tools, function calling, and remote [Model Context Protocol (MCP)](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) | Platform tools attached to reusable agents, plus tool wrappers, local MCP connections, and [agents as tools](https://developers.openai.com/api/docs/guides/agents/orchestration#use-agents-as-tools-for-manager-style-workflows) |
92| **Workflow orchestration** | You manage custom loops and branching | The SDK provides the agent loop and lifecycle |
93| **Multi-agent workflows** | Build routing and delegation yourself | Built-in agents-as-tools and [handoffs](https://developers.openai.com/api/docs/guides/agents/orchestration#use-handoffs-for-delegated-ownership) |
94| **State** | Manual history, response chaining, or [Conversations](https://developers.openai.com/api/docs/guides/conversation-state#using-the-conversations-api) | The same options, plus [SDK sessions and resumable run state](https://developers.openai.com/api/docs/guides/agents/running-agents#choose-one-conversation-strategy) |
95| **Safety and approvals** | Tool-specific approvals; you build broader controls | Input, output, and tool [guardrails plus resumable approval flows](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals) |
96| **Debugging and tracing** | Response objects and API logs | [Built-in traces](https://developers.openai.com/api/docs/guides/agents/integrations-observability#tracing) across model calls, tools, agents, guardrails, and handoffs |
