The OpenAI Agents SDK is OpenAI's code library, in TypeScript or Python, that runs an AI agent loop inside your own application: you define agents and their tools, and the SDK handles the model calls, tool calls and handoffs between agents. It's one of three ways OpenAI offers to build agents, and it sits in the middle, with more control than the managed Agents API and far less plumbing than building on the Responses API from scratch.
That middle position is the whole decision. Three products with near-identical names do different jobs, and picking the wrong one means rebuilding later or paying a developer to write plumbing you didn't need. If you want the basics of OpenAI's developer platform first, start with the OpenAI API in plain English.
Agents API, Agents SDK or Responses API?
OpenAI's Agents overview puts the three runtimes side by side. Here's that comparison in plain words, as of October 2026:
| What you're comparing | Agents API | Agents SDK | Responses API |
|---|---|---|---|
| Best for | Long-running tasks where OpenAI manages the agent and saves its progress | Agents with your own tools and workflows, inside your application | Calling models directly or building an agent from scratch |
| Where the agent runs | On OpenAI's side, in a managed Codex harness | Inside your application | Your application, with optional hosted orchestration |
| Integration effort | Low | Medium | High |
| Memory between tasks | Saved for you: session configuration, turns and items | Your storage and SDK sessions, or OpenAI's conversation state | You keep the history yourself or chain responses |
| Where tools run | Service-connected tools, your function handlers and an optional sandbox | Tools and integrations configured in your app | Hosted tools plus tools your app runs |
So if you searched for the OpenAI Agents API, that's the first column: OpenAI runs the agent for you. The SDK is the second column: your server runs it. The overview also spells out that an Agents API session, an SDK session, a Responses conversation and a sandbox are different resources, so don't assume settings carry across. OpenAI's visual Agent Builder is a separate product again, and it's being retired, so I wouldn't start anything new there.
What the SDK does for you
OpenAI's SDK page says this route fits when your server owns deployment, tool implementations, state storage and approval decisions, while the SDK runs the agent loop and calls your tools. There are two versions, TypeScript and Python, each with its own GitHub repository.
The loop is the bit worth understanding, because everything else builds on it. One run is one turn, and the runner keeps going until it reaches a real stopping point:
- It calls the current agent's model with the prepared input.
- It checks what the model sent back.
- If the model asked for tools, it runs them and goes round again.
- If the model handed off to another specialist, it switches agent and carries on.
- If there's a final answer and no more tool work, it returns the result.
That's the work a developer would otherwise write and debug by hand. It's also why the SDK suits teams with an existing product: the docs list typed code, direct control over tools and MCP servers, custom storage, and tight integration with existing product logic as the reasons to pick it.
What a first agent looks like
Installing takes one line per language. You also need an OpenAI API key, set as an environment variable called OPENAI_API_KEY.
Install commands (JavaScript first, then Python)
npm install @openai/agents zod
pip install openai-agents
OpenAI's quickstart then builds a single agent called History tutor. It has three things: a name, one line of instructions telling it to answer history questions clearly and concisely, and a model, gpt-6-astra in the example. One call runs it with a question about when the Roman Empire fell, and the answer comes back as the final output. That's the whole first program.
The definitions guide says an agent packages a model and instructions, plus optional tools, guardrails, MCP servers, handoffs and structured outputs. The quickstart's advice is the line I'd pin to the wall: once that first loop works, keep the same shape and add capabilities one at a time, rather than starting with a large multi-agent design. The first capability most teams add is a tool, either a function your own code runs or a hosted OpenAI tool such as web search or file search.
Memory comes next. The SDK gives you four ways to carry a conversation into the next turn: keep the history in your own app, use a session so the SDK saves and loads history from your storage, let OpenAI hold it through the Conversations API, or chain from the previous response ID. The running-agents guide says to pick one per conversation, because mixing your own replay with server-managed state can duplicate context.
Handoffs versus agents as tools
Once one agent works, the next question is usually whether to add specialists. The SDK gives you two patterns, and the difference is who owns the reply:
- Handoffs: control moves to a specialist, who owns the next answer. Think of a triage agent passing a billing question to a billing agent.
- Agents as tools: a manager agent stays in charge and calls specialists as bounded helpers, such as a summariser, then writes the final answer itself.
OpenAI's orchestration guide is blunt about timing. Start with one agent whenever you can, and add specialists only when they clearly improve capability isolation, policy isolation, prompt clarity or trace legibility. Splitting too early creates more prompts, more traces and more approval surfaces without necessarily making the workflow better. That's the insight most agent demos skip. If you're weighing the SDK against other options, I compare other agent frameworks separately.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
Guardrails and human sign-off
This is where a manager should ask the most questions, because it decides what the agent can do without a person looking. The guardrails guide splits the controls four ways:
- Input guardrails block disallowed requests before the main model runs.
- Output guardrails validate or redact the final answer before it leaves your system.
- Tool guardrails check the arguments or results around a function tool.
- Human-in-the-loop approvals pause the run before side effects such as cancellations, edits, shell commands or sensitive MCP actions.
Two details matter. First, a blocking guardrail stops expensive or risky work from starting, while a parallel one runs alongside to cut waiting time, at the cost of some speculative work. Second, agent-level guardrails don't run everywhere: input guardrails only run for the first agent in the chain, and output guardrails only for the agent producing the final answer. If a specialist can cancel an order, put the check next to that tool. An approval pauses the same run, which your app can store and resume later once someone says yes.
For debugging, the normal server-side setup includes tracing, and the quickstart points you to the Traces dashboard as soon as the first run works, to inspect model calls, tool calls, handoffs and guardrails. There's also a voice route in the SDK if your agent needs to talk.
Who should build on it, and who shouldn't
Here's the honest catch. The Agents SDK is a developer library. If you don't write code, you won't install it yourself. The realistic reader of this page is a founder or manager commissioning a build, or a tech lead choosing which runtime to bet on. That's still a decision worth getting right, because the runtime decides who stores your conversation history and who approves risky actions.
Pick the SDK if your team already runs its own servers, wants agents inside an existing product, and needs control over storage and approvals. Pick the Agents API if you'd rather OpenAI hosted the agent and kept its progress for long-running jobs. Build on the Responses API only if you've got developers who want every decision in their own hands. And if you're not sure OpenAI is the right model provider at all, look at other model APIs before anyone writes a line.
My advice: I'd start with one agent and one tool, and skip multi-agent handoffs until the single agent is dull and reliable. Put a human approval on anything that changes data before it touches a real customer.
If you're working out whether to build an AI agent on OpenAI or buy one ready-made, that's the kind of AI enablement I help with. I run AI training and workshops for teams, and help businesses with AI enablement and workflow automation, so the busywork runs itself and people get time back. Most of that work is with SaaS marketing teams and small businesses. Here's how we can work together.
Frequently asked questions
What is the OpenAI Agents SDK?
It's OpenAI's code library for building agents in TypeScript or Python. The SDK runs the agent loop inside your application, calling the model, running your tools and handling handoffs between agents.
What's the difference between the Agents SDK and the Agents API?
With the Agents API, OpenAI runs a managed Codex harness and saves the agent's progress. With the Agents SDK, the agent runs inside your own application and you control storage, tools and approvals.
How do I install the OpenAI Agents SDK?
Run npm install @openai/agents zod for JavaScript or pip install openai-agents for Python, then set your API key in the OPENAI_API_KEY environment variable.
Should I use handoffs or agents as tools?
Use handoffs when a specialist should take over the reply. Use agents as tools when a manager agent should stay in charge and call specialists for bounded jobs like summarising.
Can an agent built with the SDK ask before it acts?
Yes. Mark a tool as needing approval and the run pauses before that action, so a person can approve or reject it, and the same run then resumes.
