OpenAI Agents SDK vs Claude Agent SDK: Building Agents on the Two Big Platforms

Official Sources#

The agent SDK race has quietly become one of the more consequential bets in developer infrastructure. Two platforms now offer opinionated, batteries-included SDKs for building autonomous agents: OpenAI's Agents SDK (TypeScript-first, with a Python port) and Anthropic's Claude Agent SDK (the same engine that powers Claude Code, exposed as a programmable interface in Python and TypeScript). Both are production-grade, both have strong ecosystems, and choosing between them is less about raw capability and more about which orchestration model fits the way your team thinks about agents.

This post is a ground-level comparison of what each SDK actually gives you - the primitives, the orchestration patterns, the sandboxing story, and the practical trade-offs for teams committing to one platform's stack.

Last updated: October 23, 2026

What Each SDK Is, and Where It Came From#

The OpenAI Agents SDK (npm: @openai/agents) was designed as a TypeScript-first framework for defining agents, wiring tools, routing between agents via handoffs, and applying guardrails at the input and output boundaries. Its conceptual model is explicit: an Agent object holds instructions, a model name, tools, and a list of potential handoffs to other agents. The run() function (or Runner.run()) drives the loop. Zod schemas define tool parameters and structured output types. The library is MIT-licensed and ships a Model interface so you can technically point it at non-OpenAI backends, but the defaults and hosted tools are tightly coupled to OpenAI's infrastructure.

The Claude Agent SDK (npm: @anthropic-ai/claude-agent-sdk, pip: claude-agent-sdk) is different in character: it is the Claude Code engine made programmable. Where the OpenAI SDK asks you to construct agents declaratively, the Claude SDK's primary interface is the query() function - you describe a task in a prompt, declare which tools are allowed, and the agent loop runs. The SDK ships with a substantial set of built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Monitor, AskUserQuestion) that execute in-process as MCP servers. Subagents are defined as AgentDefinition objects and invoked by the orchestrating agent via the Agent tool. The SDK requires Python 3.10 or later for the Python package; the TypeScript package bundles its own Claude Code binary.

Orchestration Primitives#

This is where the two SDKs diverge most visibly.

The OpenAI Agents SDK uses handoffs as its primary multi-agent primitive. A handoff is a tool exposed to the model - if you hand off to an agent named Refund Agent, the model sees a tool called transfer_to_refund_agent. The model decides when to invoke it, transfers the conversation state to the new agent, and control shifts. You can customize the handoff with handoff() - setting inputType for structured payloads on transfer, onHandoff callbacks, inputFilter to control what conversation history the new agent sees, and isEnabled predicates to conditionally expose handoffs. Alternatively, agents can be composed as tools via agent.asTool(), where the subordinate agent returns a result to the calling agent rather than taking over the conversation.

The Claude Agent SDK uses subagents instead. You define named agents with AgentDefinition (description, system prompt, allowed tools) and include Agent in the parent's allowedTools. The orchestrating model decides when to spawn a subagent, delegates a task, and receives the result back in its context. Subagent messages carry a parent_tool_use_id field for tracing. The mental model is more like function calls that happen to be autonomous agents - the parent retains control throughout, which makes it easier to reason about state but means you need to be explicit about how work is divided.

Neither model is strictly superior. Handoffs suit pipelines where a specialist takes full ownership of the next leg of a conversation. Subagents suit orchestration patterns where a coordinator dispatches parallel or sequential tasks and synthesizes results.

Tools: Guardrails vs Hooks#

For tool validation and lifecycle control, the two platforms make opposite choices.

OpenAI's SDK leans on guardrails - dedicated validation objects that run at the boundaries of agent execution. Input guardrails run on the first user message. Output guardrails run on the final agent response. Tool guardrails (set on individual tool() definitions) run before and after each function-tool invocation. Each guardrail returns a GuardrailFunctionOutput that either allows the request through, rejects it with a message, or throws a tripwire to halt the entire run. Guardrails can run in parallel with the model call (default, lower latency) or sequentially before it (safer for blocking malicious input). This is a clean, declarative safety layer but it is scoped: guardrails do not intercept handoffs, hosted tools, or built-in execution tools like computerTool and shellTool.

The Claude Agent SDK uses hooks - callback functions registered for specific lifecycle events: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit, and others. A HookMatcher binds a hook to a pattern of tool names (e.g., "Edit|Write"). Hooks can log, transform, block, or audit any tool invocation. Because the built-in tools (Bash, Edit, Read, etc.) are first-class citizens that flow through the same hook pipeline, you get consistent observability across everything the agent does - not just your custom functions. The trade-off is that you write more imperative code; there is no built-in tripwire abstraction, so blocking requires returning a specific structure from the hook callback.

Sandboxing and Hosted Tools#

OpenAI offers sandbox agents - isolated filesystem workspaces where an agent can read, write, and execute code without touching the host machine. This is a hosted execution environment: the agent gets a clean container, a shellTool and computerTool for running commands and interacting with GUIs, and an applyPatchTool for structured file edits. For teams building coding agents or anything that needs untrusted code execution, this is a significant capability that removes a whole class of infrastructure work.

The Claude Agent SDK does not ship an equivalent hosted sandbox in the SDK itself. Execution happens in the local environment where the SDK is running. You control isolation via permission modes (ClaudeAgentOptions.permission_mode, e.g., acceptEdits for auto-approving edits) and by restricting allowedTools. For production deployments, you would bring your own containerization. This gives more flexibility but requires more setup. If you want Anthropic to host the loop instead, the same overview points to Managed Agents, a separate hosted harness with sessions in an Anthropic-managed cloud sandbox or a self-hosted sandbox on your own infrastructure - see managed agents vs LangGraph vs DIY.

MCP Ecosystem#

Both SDKs support MCP, but with different emphases.

The OpenAI Agents SDK added mcpServers as an agent-level property, letting you mount MCP-backed tools alongside native tool() definitions. The integration is relatively recent and the docs treat it as one tool source among several.

The Claude Agent SDK is architecturally built around MCP. The built-in tools are implemented as in-process MCP servers. Connecting to external MCP servers (Playwright for browser automation, database connectors, custom tooling) is a first-class pattern with direct documentation and examples. Given that Claude Code itself has driven significant adoption of the MCP ecosystem, teams that have invested in MCP servers will find the Claude SDK is a natural host for them.

Head-to-Head Comparison#

Model Lock-In: The Honest Picture#

Both platforms have gravitational pull toward their own models.

The OpenAI Agents SDK ships a Model interface that lets you substitute a custom provider, but the hosted tools (code interpreter, file search, computer use) require OpenAI infrastructure. If you want the sandbox, you are on OpenAI's platform. The SDK's defaults assume GPT-4.x or GPT-5.x class models with the Responses API.

The Claude Agent SDK is more explicit about multi-cloud support - Bedrock, Vertex AI, Azure AI Foundry, and the Anthropic API are documented as first-party authentication paths. But the underlying model is always Claude. The SDK is a wrapper around Claude Code's execution engine; it does not expose a model substitution interface.

In practice, the question is less "can I swap models?" and more "am I comfortable with this provider's model roadmap?" Both Anthropic and OpenAI are shipping new models frequently. Teams that need multi-provider flexibility should evaluate frameworks like LangGraph or keep their own thin abstraction layer regardless of which SDK they start with.

Pricing Context#

Pricing for both platforms changes frequently and should be verified at the time of your evaluation. For the Claude Agent SDK, Anthropic's overview tells developers to use API key authentication, and says Anthropic does not allow third-party developers to offer claude.ai login or rate limits for products built on the SDK unless previously approved, so standard token pricing applies to a production agent. An earlier version of this post cited a dedicated monthly Agent SDK credit pool for subscription plans starting June 15, 2026; that statement no longer appears on the current overview page, so check Anthropic's billing documentation rather than relying on it. OpenAI's agent execution via the Responses API similarly uses token-based pricing with additional costs for hosted tool usage (code interpreter runs, file storage). Do not plan a production cost model around numbers in blog posts - both providers have updated pricing multiple times this year.

Decision Guide#

Choose the OpenAI Agents SDK if:

• Your team is TypeScript-first and wants ergonomic Zod-typed tools and structured outputs out of the box.
• You need hosted sandboxed code execution without managing containers.
• Your multi-agent workflows are conversation-routing problems where handing off to a specialist makes more sense than delegating a subtask.
• You are already invested in OpenAI's hosted tools (code interpreter, file search).

Choose the Claude Agent SDK if:

• You are building agents that primarily work with codebases, file systems, and shell commands - the built-in tool suite is a significant head start.
• Your team has existing MCP servers you want to connect, or you want to leverage the broader MCP ecosystem that Claude Code's adoption has driven.
• You want fine-grained lifecycle control over every tool call via hooks, with a consistent interface across both built-in and custom tools.
• You are deploying on Bedrock, Vertex, or Azure and want first-party support for those auth paths.
• You want the same underlying engine that powers Claude Code - useful if your agents are doing developer workflow automation.

Consider a framework like LangGraph if:

• You need model-provider flexibility as a hard requirement.
• Your orchestration logic is complex enough that you want explicit graph-based control flow rather than either SDK's loop.
• You are already using LangChain's ecosystem.

Both SDKs are past the "interesting prototype" stage. Teams should evaluate them on the specific shape of their agent - what tools it needs, how it delegates work, and what safety contracts matter in production - rather than on model benchmarks or brand preference.

FAQ#

Can I use the OpenAI Agents SDK with non-OpenAI models?#

The SDK exposes a Model interface that lets you substitute a custom model implementation, so technically yes. In practice, the hosted tools (sandbox execution, code interpreter, file search) require OpenAI infrastructure. If your agent relies on those hosted capabilities, you are effectively on OpenAI's platform. For pure LLM-plus-function-tools agents, the custom Model interface is a viable escape hatch.

Does the Claude Agent SDK require Claude Code to be installed?#

For the TypeScript package, no - it bundles its own Claude Code binary as an optional dependency. For the Python package, the SDK calls the Claude Code engine under the hood, but you do not need to install Claude Code as a separate CLI tool in your production environment. You do need a valid ANTHROPIC_API_KEY (or configured cloud credentials for Bedrock/Vertex/Azure).

How do handoffs differ from subagents conceptually?#

With handoffs, the receiving agent takes over the conversation - the original agent steps back. With subagents, the orchestrating agent dispatches a task and waits for a result, then continues. Handoffs are better modeled as routing (the model decides where a conversation should live). Subagents are better modeled as delegation (the orchestrator breaks a task into pieces and merges results). Many real-world agent workflows need both patterns at different levels of the pipeline. Voice agents now get a native version of the delegation pattern too: GPT-Live can hand typed decisions to the Decisions API without a round trip through your app.

Is the Claude Agent SDK the same thing as calling the Anthropic API directly?#

No. The Anthropic Messages API gives you a single model call. The Claude Agent SDK wraps Claude Code's full execution engine, including the agentic loop, built-in tool execution, hook lifecycle, subagent management, and permission controls. It is a higher-level abstraction - closer in spirit to a framework than to a raw API client. If you want just a model call, use the Anthropic SDK (@anthropic-ai/sdk). If you want an autonomous agent that can read files, run commands, and spawn subagents, use the Claude Agent SDK.

Continue Reading#

• Durable AI Agent Frameworks Compared - one crashing, two-day-approval run through LangGraph, Mastra, Pydantic AI and the OpenAI Agents SDK
• The Pushback on Amodei's Exponential Essay: Too Slow, Too Convenient, or About Right?
• Give Your Site a Voice: Build a Conversational Support Agent with ElevenLabs Agents
• Claude Agent SDK vs LangGraph: Choosing Your Agent Stack in 2026
• Claude Code Projects: Coordinator, Threads, and Limits - Anthropic's hosted coordinator for parallel Claude Code cloud threads
• Claude Agent SDK vs OpenAI Agents SDK comparison - the side-by-side table
• Intro to Agents 101 course - provider-agnostic agent concepts, built hands-on
• Tool Calling Under the Hood: Claude Messages vs OpenAI Responses
• Multi-Agent Orchestration Patterns: Diagrams and Framework Support (2026)
• Claude Agent SDK in Late 2026: What Is New and How to Use It
• Pydantic AI V2 in Late 2026: Capabilities, Graphs, Evals and MCP
• OpenAI Agents SDK in Late 2026: What Is New in Python and TypeScript - sandbox agents, guardrails, compaction sessions and the upgrade checklist

Sources#

• OpenAI Agents SDK - Agents guide: https://openai.github.io/openai-agents-js/guides/agents (scraped June 10, 2026)
• OpenAI Agents SDK - Handoffs guide: https://openai.github.io/openai-agents-js/guides/handoffs (scraped June 10, 2026)
• OpenAI Agents SDK - Guardrails guide: https://openai.github.io/openai-agents-js/guides/guardrails (scraped June 10, 2026)
• Claude Agent SDK - Overview: https://code.claude.com/docs/en/agent-sdk/overview (scraped June 10, 2026; re-checked October 23, 2026)
• Claude Code documentation overview: https://code.claude.com/docs (scraped June 10, 2026)