OpenAI Agents SDK Explained — Build LLM Agents

Photo: Sanket Mishra / Pexels
The OpenAI Agents SDK is OpenAI's official Python and TypeScript framework for building production agents on top of large language models. It shipped in March 2025 alongside the Responses API, and it's the direct, code-first successor to the Assistants API, which OpenAI has confirmed will shut down on August 26, 2026. This guide covers what the SDK actually gives you, how its five core primitives fit together, and when to reach for it instead of LangChain, Pydantic AI, or a hand-rolled agent loop.
If you're new to agents in general, start with our AI agents explainer and the subagents pattern. This article assumes you already know what an agent is and focuses specifically on the OpenAI implementation.
What the OpenAI Agents SDK actually is
The Agents SDK is an open-source, lightweight orchestration library — not a hosted product, not a drag-and-drop tool. You install it with pip install openai-agents (Python) or npm install @openai/agents (TypeScript), write code, and run it yourself. It is intentionally less opinionated than LangChain: there are only five core abstractions, and each one maps cleanly onto a first-party OpenAI capability like function calling, web search, file search, or computer use.
That minimalism is a design choice, not an accident. OpenAI's own SDK documentation frames the project as a production-ready upgrade to an earlier experimental project called Swarm, built with a small enough surface area that a team can read the entire source in an afternoon. Compare that to LangChain, whose abstraction layers (chains, agents, tools, callbacks, memory classes, output parsers) have shifted enough between major versions that "LangChain churn" is its own recurring complaint in developer forums.
The five core abstractions
The entire public API surface of the Agents SDK fits in five concepts. Once you understand these, you understand the framework — there is no sixth layer hiding underneath.
Agent
An Agent is an LLM plus its configuration: a system prompt (called instructions), the tools it's allowed to call, optional handoffs to other agents, and optional guardrails. It is a plain data object, not a running process.
from agents import Agent, function_tool
@function_tool
def get_weather(city: str) -> str:
return f"Sunny in {city}"
assistant = Agent(
name="Assistant",
instructions="You are a helpful assistant.",
tools=[get_weather],
)
Runner
The Runner executes the agent loop: it calls the model, checks whether the model asked to call a tool, runs that tool if so, feeds the result back into the model, and repeats until the agent produces a final answer or hands off to another agent. This loop — call, check, act, repeat — is the mechanical heart of every agent framework, whether it's OpenAI's SDK, LangGraph, or a bare while loop you write yourself. The Runner just handles the bookkeeping for you.
from agents import Runner
result = Runner.run_sync(assistant, "What's the weather in Berlin?")
print(result.final_output)
Think of the Runner as a relay race coach standing at the track: it doesn't run any leg itself, but it decides when the model's turn ends and whose turn is next, whether that's a tool, another agent, or the user.
Handoffs
A handoff is how one agent delegates a task to another. Under the hood, a handoff is modeled as a special kind of tool call — the "delegating" agent calls a function named after the target agent, and the Runner swaps in the new agent to continue the conversation. Because handoffs are just tools with a special shape, they show up in traces exactly like any other tool call, which makes them easy to debug.
triage = Agent(
name="Triage",
instructions="Route to the right specialist.",
handoffs=[billing_agent, support_agent],
)
According to OpenAI's own handoff documentation, handoffs stay within a single run: input guardrails apply only to the first agent in the chain, and output guardrails apply only to the agent that produces the final response. That's an important detail if you're chaining several specialists — a guardrail on your triage agent won't automatically re-check output three handoffs downstream.
Guardrails
Guardrails are input and output validators that run in parallel with the agent, not sequentially after it. OpenAI's guardrails documentation describes them as "fail fast" checks — if a guardrail trips, the run stops immediately rather than waiting for the full agent turn to finish and burning tokens on a response that was going to get rejected anyway. Guardrails are commonly used for PII filtering, topic restriction ("don't discuss competitors"), and jailbreak detection.
One subtlety worth knowing: because handoffs run through the SDK's own handoff pipeline rather than the standard function-tool pipeline, tool-level guardrails don't automatically apply to the handoff call itself. If you need a check to survive a handoff, it has to be attached at the agent level, not the tool level.
Tracing
Every agent run produces a trace: a timestamped record of every model call, tool call, handoff, and guardrail check, viewable in OpenAI's dashboard or exportable to a third-party observability tool. Tracing is enabled by default, and OpenAI's docs note you can turn it off with the OPENAI_AGENTS_DISABLE_TRACING=1 environment variable, set_tracing_disabled(True) in code, or a per-run RunConfig flag — useful if you're running against a non-OpenAI model through the LiteLLM bridge and don't want traces routed to OpenAI's servers.
Tracing is the single biggest practical advantage the SDK has over rolling your own agent loop. Debugging an agent that looped four times and burned $2 in tokens without you noticing is painful when all you have is server logs. A trace turns that into a step-through timeline you can actually read.
There's also Sessions, a sixth-ish feature for persisting conversation history across multiple Runner.run() calls, so a user can close their laptop and resume a conversation later without you manually reconstructing message history.
Pre-built tools that ship with the SDK
The SDK includes first-class wrappers for OpenAI's hosted tools, meaning you don't write any glue code to use them:
- Web Search — live web access through OpenAI's search infrastructure
- File Search — vector search over documents you've uploaded to OpenAI's file storage
- Code Interpreter — sandboxed Python execution for data analysis or math
- Computer Use — the agent controls a virtual computer with mouse and keyboard input, now generally available with configurable sandbox profiles
- MCP — any Model Context Protocol server can be registered as a set of tools with a single line of code
This is the practical reason teams already committed to OpenAI pick the Agents SDK over a provider-agnostic framework: these tools work out of the box and integrate natively with billing and tracing. You're not writing a custom wrapper around a search API and hoping the rate limits behave. For agents that need to run code safely, E2B-style code sandboxes are one common approach.
How the SDK fits into the AgentKit ecosystem
OpenAI's agent tooling isn't just the SDK anymore. At DevDay on October 6, 2025, OpenAI introduced AgentKit, a broader platform that bundles three additional pieces around the Responses API:
| Component | What it does | Code required? |
|---|---|---|
| Agents SDK | Code-first framework: Agent, Runner, handoffs, guardrails, tracing | Yes — Python/TypeScript |
| Agent Builder | Visual, drag-and-drop canvas for composing multi-agent workflows with preview runs | No — visual canvas |
| ChatKit | Embeddable chat widget with streaming, threading, and in-chat app rendering | Minimal — drop-in component |
| Connector Registry | Admin panel connecting Dropbox, Google Drive, SharePoint, Teams, and third-party MCP servers across ChatGPT and the API | No — admin configuration |
| Table: The four pieces of OpenAI's agent tooling stack and how much code each requires. |
The distinction matters for which one you pick. OpenAI's own guidance is that the Agents SDK is for "workflows that should continue as code" — version-controlled, testable, deployable through your normal CI/CD pipeline. Agent Builder, by contrast, is aimed at teams that want to compose an agent workflow visually without writing Python.
That said, Agent Builder's runway is short. OpenAI announced on June 3, 2026 that it's winding down both Agent Builder and its Evals product, with both going fully unavailable on the platform starting November 30, 2026. ChatKit is explicitly not part of that wind-down — it continues as a supported, general-availability product. If your team built workflows in the visual Agent Builder, that's now a migration project onto the code-first SDK, not a long-term platform to keep building on.
Multi-model support: it's not actually OpenAI-only
Despite the branding, the Agents SDK doesn't lock you into OpenAI models. Through a LiteLLM bridge, the same Agent, Runner, handoff, and guardrail code can run against Claude, Gemini, Mistral, or a locally hosted open-weight model. You lose the OpenAI-hosted tools — web search, file search, and computer use are OpenAI infrastructure, so they don't travel with you to another provider — but the core orchestration primitives keep working identically.
This is a meaningfully different position from a framework like the Anthropic SDK, which has no bridge concept at all because it isn't trying to be an orchestration layer in the first place; it's the raw model client. If your team wants "write once, swap models later" flexibility without adopting LangChain's much larger abstraction stack, the LiteLLM bridge is the practical middle ground.
Relationship to the Responses API
The Agents SDK is a thin client built on top of the Responses API, OpenAI's unified replacement for the older split between Chat Completions and the Assistants API. The Responses API handles statefulness, tool execution, and conversation memory server-side; the SDK's job is to wrap that in Python or TypeScript objects you can reason about.
Practically, this means three things for migration planning:
- If you're on Assistants, moving to the Agents SDK is close to a like-for-like swap — assistants become Agents, threads become conversations, runs become responses, and run steps become items. OpenAI's own migration guide walks through this mapping directly.
- If you're on Chat Completions, you keep more manual control over message history and tool orchestration, and the SDK layers the agent loop on top rather than replacing what you already built.
- If you're starting fresh, there's no reason to touch Chat Completions or Assistants at all — build directly on Responses via the SDK.
A complete working example
Here's a support agent with a tool, a handoff to a specialist, and an input guardrail, in under 30 lines:
from agents import Agent, Runner, function_tool, input_guardrail
@function_tool
def lookup_order(order_id: str) -> str:
return f"Order {order_id}: shipped"
@input_guardrail
def block_pii(input: str):
if "ssn" in input.lower():
raise ValueError("PII not allowed")
refund_agent = Agent(
name="Refunds",
instructions="Process refund requests politely.",
)
support = Agent(
name="Support",
instructions="Help customers. Hand off refunds.",
tools=[lookup_order],
handoffs=[refund_agent],
input_guardrails=[block_pii],
)
result = Runner.run_sync(support, "Where is order 1234?")
print(result.final_output)
Walk through what happens when a user asks "Where is order 1234?" First, block_pii runs against the input and passes. Then the Support agent decides whether to call lookup_order or hand off to Refunds — for a status question, it calls the tool, gets "Order 1234: shipped" back, and folds that into its final answer. If the user had instead asked for a refund, the Support agent would call the handoff, and the Refunds agent would take over the rest of the conversation. All of this — the guardrail check, the tool call, the handoff decision — shows up as discrete steps in the trace.
A more realistic pattern: triage plus specialists
Toy examples make the loop look simple, but production systems usually need a triage layer in front of several narrow specialists rather than one agent that tries to do everything. This is the same reasoning behind subagent architectures: a single agent juggling billing, technical support, and account changes in one system prompt tends to confuse itself about which instructions apply when. Splitting the work into a router plus focused specialists keeps each agent's prompt short and its tool list small, which in turn makes it more reliable.
triage = Agent(
name="Triage",
instructions="Classify the request and hand off. Do not answer directly.",
handoffs=[billing_agent, technical_agent, account_agent],
input_guardrails=[block_pii],
)
The Support/Refunds example above is a two-node version of this pattern. Scale it to five or six specialist agents and you have something close to what a real customer-support deployment looks like: one thin router, several narrow experts, and a shared guardrail that runs once at the entry point rather than being duplicated across every specialist.
OpenAI Agents SDK vs alternatives
| Framework | Vendor | Opinionatedness | Strength | Weakness |
|---|---|---|---|---|
| OpenAI Agents SDK | OpenAI | Low | Native OpenAI hosted tools, built-in tracing, small API surface | Hosted tools (web/file search, computer use) don't work with non-OpenAI models |
| LangChain / LangGraph | LangChain Inc. | High | Largest ecosystem, hundreds of integrations, graph-based agent topologies | Heavier abstractions, more frequent breaking API changes |
| Pydantic AI | Pydantic | Medium | Type-first design, structured outputs validated at the schema level | Smaller ecosystem, younger project |
| Anthropic SDK (direct) | Anthropic | None | Total control, no framework lock-in, first-class MCP support | You build the agent loop, handoffs, and tracing yourself |
| CrewAI | CrewAI | High | Fast to prototype "crews" of role-based agents | Less low-level control, more opinionated about agent roles |
| AutoGen | Microsoft | Medium | Strong for research-style multi-agent conversation patterns | Less production-hardened than the others on this list |
| Table: How the OpenAI Agents SDK compares to the five frameworks it's most commonly weighed against. |
Where each framework actually wins
Comparison tables flatten nuance, so it's worth being concrete about the scenarios where each choice is clearly correct rather than just "fine."
OpenAI Agents SDK wins when your product is customer-facing and needs web search or file search today, without you standing up your own retrieval infrastructure. A support bot that needs to look up a customer's order history from an uploaded PDF and check current shipping policy on the web is a textbook fit — both are pre-built tools with zero glue code.
LangGraph wins when your workflow is genuinely cyclic — an agent that loops between drafting, critiquing, and revising a document isn't well-served by the SDK's linear handoff model, which assumes control passes forward, not back and forth in a graph.
Pydantic AI wins when the primary risk in your system is malformed output, not orchestration complexity — a data-extraction pipeline pulling structured fields out of contracts benefits more from schema validation on every response than from hosted web search.
The raw Anthropic SDK wins when you specifically need Claude's reasoning behavior and don't want any framework opinions between you and the model — common for teams doing heavy prompt engineering iteration where framework abstraction gets in the way of seeing exactly what's sent to the API.
When to use the OpenAI Agents SDK
Pick it when:
- You are committed to OpenAI as the primary model provider.
- You want hosted web search, file search, or computer use without building your own.
- You want built-in tracing without standing up a separate observability stack.
- You prefer a small API surface — five concepts — over LangChain's much larger one.
Pick something else when:
- You want a genuinely framework-agnostic agent (Pydantic AI or the raw Anthropic SDK are stronger fits).
- You are already deep into LangChain integrations and switching costs more than it saves.
- You need a graph-based, cyclic agent topology where control can loop backward, not just hand off forward.
Cost and latency considerations
Every guardrail, tool call, and handoff in an agent run adds a round trip. A triage agent that hands off to a specialist costs at minimum two model calls instead of one, and a guardrail running in parallel still costs its own token budget even though it runs concurrently rather than sequentially. None of this is unique to OpenAI's SDK — it's true of any agent framework — but tracing makes the cost visible in a way that raw API logs usually don't, because each trace shows token counts per step rather than just a single aggregate number for the whole request.
The practical implication: use tracing during development specifically to look for agents that loop more than once or twice per turn. A support agent that calls lookup_order three times in a single run before answering is either mis-prompted or hitting a bug in how it's parsing the tool's return value — and you'll only catch that by reading the trace, not by reading the final output, which might look correct anyway.
Common pitfalls
- Skipping guardrails. They feel optional in development, when you're the only user testing edge cases. They stop being optional the moment real users start typing things you didn't anticipate.
- No evals. Agents drift silently as you tweak prompts and add tools. Without an eval suite running against a fixed test set, you won't notice a regression until customers complain — and by then you won't know which change caused it.
- Over-handoff. Three handoffs in a workflow is manageable. Ten is a debugging nightmare, because tracking which agent is "in control" at any given point in a long trace gets genuinely hard to follow. Prefer flatter agent graphs — one triage layer and a handful of specialists, not a deep chain.
- Ignoring traces. The tracing dashboard exists specifically so you don't have to guess why an agent looped or called the wrong tool. Teams that skip it end up debugging by re-reading raw API logs, which is strictly slower.
- Forgetting guardrail scope. Because input guardrails only apply to the first agent in a handoff chain and output guardrails only apply to the last, a check you assumed was running on every agent in the chain might only be running on one of them. Verify this explicitly rather than assuming.
- Migrating from Assistants too late. August 26, 2026 is a hard shutdown date, not a soft deprecation warning. Start the migration now if you haven't, since the Responses API's data model (conversations, items) is different enough from threads and runs that it isn't a one-line change.
Common mistakes when comparing frameworks
A frequent misconception is treating "OpenAI Agents SDK" and "AgentKit" as the same thing. They aren't: AgentKit is the umbrella product name covering the SDK plus Agent Builder, ChatKit, and the Connector Registry. A team that says "we use AgentKit" for a code-first, no-visual-canvas deployment is really just describing SDK usage — Agent Builder is the no-code layer, and as of the June 2026 wind-down announcement, it's on its way out anyway.
A second common mistake is assuming multi-model support via LiteLLM gives you full feature parity with OpenAI models. It gives you parity on the orchestration primitives — Agent, Runner, handoffs, guardrails — but not on hosted tools. A Claude-backed agent running through the LiteLLM bridge cannot call OpenAI's web search or computer-use tools, because those are OpenAI infrastructure, not SDK features.
What's new in the SDK for 2026
- MCP support is now first-class: any MCP server registers as agent tools with one line, no custom wrapper needed.
- Computer use is generally available with configurable sandbox profiles, rather than the earlier limited preview.
- Sessions persist conversation state across multiple runs, useful for long-running agent contexts that outlive a single process.
- Sandbox execution and manifest-based workspaces were added in an SDK update, strengthening the harness around what an agent can touch on disk and giving teams a declarative way to define an agent's runtime environment.
- The wider AgentKit ecosystem consolidated, with Agent Builder and Evals being wound down (final availability November 30, 2026) while ChatKit remains a supported, general-availability product for embeddable chat interfaces.
Frequently asked questions
Q: When did the OpenAI Agents SDK launch? A: March 2025, alongside the Responses API. It's the supported, code-first successor to the Assistants API.
Q: When does the Assistants API shut down? A: OpenAI has set August 26, 2026 as the shutdown date. Teams still on Assistants need to migrate to the Responses API, either directly or through the Agents SDK, before that date.
Q: Can the OpenAI Agents SDK use Claude or Gemini? A: Yes, through a LiteLLM bridge. You lose OpenAI-hosted tools — web search, file search, computer use — when running on other providers, but the agent loop, handoffs, guardrails, and tracing all still work.
Q: What is AgentKit, and is it the same as the Agents SDK? A: No. AgentKit is a broader product OpenAI launched at DevDay in October 2025 that bundles the Agents SDK together with Agent Builder (a visual, no-code canvas), ChatKit (an embeddable chat widget), and the Connector Registry (an admin panel for data connectors). The SDK is the code-first piece within that larger product.
Q: Is Agent Builder still available? A: OpenAI announced on June 3, 2026 that it's winding down Agent Builder and Evals, with both becoming unavailable on the platform starting November 30, 2026. ChatKit is not affected and remains generally available.
Q: How is the Agents SDK different from LangChain? A: The Agents SDK is intentionally small — five core concepts, native OpenAI feature integration, minimal abstraction. LangChain and LangGraph are much larger, with hundreds of integrations and support for cyclic, graph-based agent topologies. Pick OpenAI's SDK for simplicity and hosted tools; pick LangChain for ecosystem breadth or non-linear workflows.
Q: Does the SDK support MCP? A: Yes. MCP support is first-class — any Model Context Protocol server can be registered as tools for an agent with a single line of configuration.
Q: Is the OpenAI Agents SDK open source? A: Yes. Both the Python and TypeScript SDKs are open source under permissive licenses, and you can self-host the orchestration logic. Hosted tools — web search, file search, computer use, and the tracing dashboard — still require an OpenAI API account.
Q: Do guardrails apply to every agent in a handoff chain? A: No, and this trips people up. Input guardrails run only on the first agent in a chain; output guardrails run only on the agent that produces the final response. A guardrail attached to your triage agent won't automatically re-check output several handoffs downstream.
Q: What's the difference between a handoff and a regular tool call? A: Mechanically, a handoff is implemented as a special kind of tool call that swaps in a new agent to continue the conversation, rather than returning a result to the current agent. Functionally, a tool call gets you data; a handoff transfers control of the rest of the run to a different agent entirely.
The takeaway
The OpenAI Agents SDK earns its adoption by staying small: five primitives that map directly onto OpenAI's hosted infrastructure, with tracing built in from day one instead of bolted on later. That focus is also its boundary — the moment you need a genuinely cyclic workflow, full model independence, or the hosted tools while running a non-OpenAI model, you're better served by LangGraph, the raw Anthropic SDK, or Pydantic AI. The real deadline to act on, regardless of which framework you pick long-term, is August 26, 2026: that's when the Assistants API goes dark, and the Responses API (with or without the Agents SDK wrapped around it) is the only supported path forward.
Read next:
- AI Agents Explained — How Autonomous AI Systems Actually Work
- AI Subagents Explained — Parallel AI Work
- What Is Pydantic AI? Type-Safe LLM Apps
Sources
- OpenAI Agents SDK documentation, Agents/Handoffs/Guardrails/Tracing pages — openai.github.io/openai-agents-python
- OpenAI Developer Platform, Responses API and Agents SDK guides — developers.openai.com/api/docs/guides/agents
- OpenAI, "Introducing AgentKit" (DevDay, October 6, 2025) — openai.com/index/introducing-agentkit
- OpenAI Developer Platform, Assistants API migration guide (shutdown date August 26, 2026) — developers.openai.com/api/docs/assistants/migration
- OpenAI Developer Platform, ChatKit guide — developers.openai.com/api/docs/guides/chatkit
- Model Context Protocol specification — modelcontextprotocol.io
- LiteLLM documentation — docs.litellm.ai
Follow new articles
Add SciHub101 to your feed reader to see new science and technology stories.
About the Author
SciHub101 is an independent science and technology publication founded and edited by Buğra Sözeri, a software engineer and app developer based in Türkiye. AI tools assist with drafting and research. Source documentation in the existing archive is uneven, and articles are being reviewed and corrected. The Editorial Team byline identifies editorial responsibility; it does not certify specialist or independent human review. Where we compare products, anything built by our own team is labelled as such — see the editorial guidelines and About page for how corrections and disclosures work.
Related Articles

What Is Cursor? AI Code Editor Explained
Cursor is an AI-first code editor built as a VS Code fork, now a SpaceX subsidiary. How Tab, Composer, and Agent mode actually work, and what they cost.

LLM Evaluation Explained — Measuring AI Quality
LLM evals systematically measure AI output quality. Learn benchmarks, LLM-as-judge, RAGAS, and the 2026 toolchain — Promptfoo, Braintrust, LangSmith.

What Is Agentic AI? Workflows, Tools, and Real Limits
Agentic AI is the next buzzword, but the useful concept is simple: models that plan, call tools, check results, and repeat toward a goal.

What Is Cline? VS Code AI Coding Agent
Cline is a free, open-source VS Code extension that turns the editor into an autonomous AI coding agent. How it works, pricing, and when to use it.

Claude Skills Explained — Anthropic's New Feature
Claude Skills are folder-based modules that extend Claude with scripts, instructions, and resources. Here's how they work and differ from MCP.

Deep Research AI Explained — Beyond Chat
Deep Research AI agents autonomously read papers, search the web, and write cited reports in minutes. Here's how they work and which to use.