Last month a client asked me a question I didn’t have a crisp answer for: should their support-ticket router be built on the Claude Agent SDK or the OpenAI Agents SDK? I’d shipped small things with both, but never run a real Claude Agent SDK vs OpenAI Agents SDK comparison on the same workflow, side by side, with the same failure cases in mind. So that’s what I did.
If you’ve looked at either SDK’s docs, you already know the surface-level pitch sounds identical: give an LLM some tools, let it plan its own steps, get a result back. The marketing copy barely differs. What differs is what happens the moment your agent needs to delegate a subtask, or a tool call needs to be checked before it runs. That’s where the two architectures stop looking alike.
Here’s what I found after building the same two-specialist workflow in both: where the delegation models actually diverge, where the safety models solve different problems, and the three mistakes I made that you probably will too.
Claude Agent SDK vs OpenAI Agents SDK: Two Different Mental Models
The one-line version: Claude’s SDK spawns subagents through a built-in Agent tool, each one running in an isolated context that can execute in parallel. OpenAI’s SDK does handoffs: one agent transfers the entire conversation to another, and only one agent is “active” at a time.
That sounds like a minor implementation detail. It isn’t. A subagent’s context starts fresh. It never sees your main conversation history, only the prompt string you hand it through the tool call. A handoff, by contrast, carries the conversation forward; the new agent picks up where the last one left off, same history, same thread. Pick the wrong mental model for your use case and you’ll spend a day debugging an agent that “forgot” something it was never actually given, or one that’s dragging around context it didn’t need. It’s the same layer of confusion I ran into comparing AutoGPT, CrewAI, and LangGraph a while back, just one level up the stack.
How the Claude Agent SDK Delegates Work
Install is pip install claude-agent-sdk (or uv add claude-agent-sdk), and the package bundles its own Claude Code binary, so you don’t install Claude Code separately on most platforms. Set ANTHROPIC_API_KEY and you’re running. The entry point is query(), an async generator that streams messages as the agent reasons, calls tools, and reports results.
Subagents are defined with AgentDefinition objects and handed to query() through the agents option. Claude invokes them through a built-in tool literally named Agent (it was called Task before Claude Code v2.1.63, so if you’re matching on tool names for logging, check for both):
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="A customer wants a refund and is also asking about their invoice.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Agent"],
agents={
"billing-specialist": AgentDefinition(
description="Handles invoice and payment questions.",
prompt="You answer billing questions precisely. Cite the invoice line items you used.",
tools=["Read", "Grep"],
),
"refunds-specialist": AgentDefinition(
description="Handles refund eligibility and processing.",
prompt="You check refund policy against order history before approving anything.",
tools=["Read", "Grep"],
model="sonnet",
),
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())Claude decides on its own when to spawn which subagent, matching your task to each one’s description. The two specialists can run concurrently: the docs default to 20 subagents at once and a nesting depth of 3 (subagents spawning their own subagents), both tunable through environment variables. There’s also a hard spend cap, max_budget_usd, that counts subagent API calls toward the same total and kills the query with an error_max_budget_usd result when it’s hit. Nobody enjoys discovering a runaway agent tree after the invoice arrives, so I’d set this on anything that isn’t a quick local test.

How the OpenAI Agents SDK Delegates Work
Install is pip install openai-agents. The core primitives are Agent and Runner. You build an agent with instructions and tools, then run it with Runner.run_sync (or the async Runner.run):
from agents import Agent, Runner, handoff
billing_agent = Agent(
name="Billing agent",
instructions="Answer invoice and payment questions precisely.",
)
refund_agent = Agent(
name="Refund agent",
instructions="Check refund policy against order history before approving anything.",
)
triage_agent = Agent(
name="Triage agent",
instructions="Route billing questions to Billing agent, refund requests to Refund agent.",
handoffs=[billing_agent, handoff(refund_agent)],
)
result = Runner.run_sync(triage_agent, "I want a refund and I have a billing question.")
print(result.final_output)Every agent you pass into handoffs becomes a tool the model can call, named transfer_to_<agent_name> by default. Calling it hands the entire conversation to that agent. It changes who’s driving the conversation, not just who’s handling one subtask. If you need structured data passed along with the handoff rather than just the conversation history, wrap the target in handoff() and give it an input_type (a Pydantic model) plus an on_handoff callback that receives the validated data. That’s the piece most tutorials skip, and it’s the piece you actually need the moment “route to refunds” has to carry an order ID along with it.
Guardrails vs Permissions: Two Different Safety Models
Here’s the confusing part: neither SDK’s safety system maps cleanly onto the other’s, because they’re solving different problems.
OpenAI’s guardrails validate content: the input before the agent processes it, or the output before it reaches the caller. You write a function, decorate it with @input_guardrail or @output_guardrail, and return a GuardrailFunctionOutput with a tripwire_triggered flag:
from agents import Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered, Runner
from agents.decorators import input_guardrail
@input_guardrail
async def block_policy_violations(ctx, agent, user_input):
text = user_input if isinstance(user_input, str) else str(user_input)
return GuardrailFunctionOutput(
output_info="policy keyword check",
tripwire_triggered="social security number" in text.lower(),
)
agent = Agent(
name="Support agent",
instructions="Help customers with billing questions.",
input_guardrails=[block_policy_violations],
)
try:
Runner.run_sync(agent, "Can you look up my refund using my social security number 123-45-6789?")
except InputGuardrailTripwireTriggered:
print("Blocked: input guardrail tripped.")Miss that try/except and the tripwire doesn’t fail gracefully, it raises straight through your call stack. I’d treat every guardrail as something that can throw, not just something that can flag.
Claude’s permission system validates tool calls, not content. It’s a six-step pipeline (hooks, deny rules, ask rules, permission mode, allow rules, then your canUseTool callback) that decides whether a specific tool invocation is allowed to run at all. The permission modes range from default (ask when unsure) through acceptEdits (auto-approve file writes) to bypassPermissions, which approves nearly everything and which Claude Code refuses to even start under sudo outside a recognized sandbox. There’s no equivalent of “check whether this text contains a policy violation” built in. You’d build that yourself with a PreToolUse hook, which is really just a human-in-the-loop check you wire up on your own.

Side-by-Side: Claude Agent SDK vs OpenAI Agents SDK
| Dimension | Claude Agent SDK | OpenAI Agents SDK |
|---|---|---|
| Delegation model | Subagents via the Agent tool; isolated context, can run in parallel | Handoffs; conversation transfers to the next agent, same history |
| Install | pip install claude-agent-sdk (bundles a Claude Code binary) | pip install openai-agents |
| Core entry point | query(), streams an async iterator of messages | Runner.run_sync / Runner.run |
| Safety primitive | Permission modes + hooks, gates tool execution | Input/output guardrails, gates content, raises on trip |
| Concurrency controls | Built-in: max concurrent subagents (default 20), max depth (default 3) | Not documented as a built-in primitive; you’d manage it yourself |
| Spend cap | max_budget_usd, hard stop, counts subagent spend | Not surfaced in the official docs I checked; build your own tracking |
| Built for | Operating a computer: reading, editing, running commands | Routing between domain specialists |
Pros and Cons of Each
Pros of the Claude Agent SDK
- Subagent isolation keeps a noisy exploration (dozens of files read, grepped, discarded) from bloating your agent’s context window; the parent only sees the final summary
- Hard budget and concurrency caps are built in, not something you bolt on after a surprising bill
- The tool surface (Read, Edit, Bash, WebSearch, MCP) is the same one Claude Code itself runs on, so it’s battle-tested on exactly the kind of “operate the filesystem and shell” tasks a lot of internal tooling needs
Cons of the Claude Agent SDK
- A subagent’s context is genuinely empty except for the prompt string you pass it. Forget to include a file path or an error message and it has no way to ask the parent for it
- A bare allow-rule entry like
allowed_tools=["Read"]auto-approves that tool before yourcanUseToolcallback ever runs, so a safety check you wrote there is silently skipped for that tool
Pros of the OpenAI Agents SDK
- Guardrails are a clean, explicit primitive for “check this content before/after,” which is a different and genuinely useful thing from gating tool calls
- Handoffs map naturally onto a triage-and-route structure: if your actual problem is “figure out which specialist should own this conversation,” the model fits without any adapting
- Built-in tracing gives you a visual run-through of the whole session without wiring up your own logging
Cons of the OpenAI Agents SDK
- Because the handoff tool name is generated from the agent’s name (
transfer_to_<agent_name>), two agents with the same name produce identical tool names to the model. Worth checking if you’re generating agents dynamically - No documented built-in spend or concurrency cap in what I reviewed; if an agent hands off in a loop, you’re the one who has to notice

Common Pitfalls
Treating a subagent like a function call with memory. It isn’t. Unless you explicitly fork the conversation, a Claude subagent starts with zero parent history. I lost twenty minutes once to a subagent that kept “forgetting” a decision I’d made three turns earlier in the main thread. It had never seen that turn in the first place.
Not catching the tripwire exception. OpenAI’s own example code wraps the guardrail-protected run in try/except. Skip that and your service returns a 500 instead of a clean “that request was blocked” response.
Assuming allowed_tools constrains bypassPermissions mode. It doesn’t. The docs are explicit here: listing specific tools in allowed_tools while also setting permission_mode="bypassPermissions" still approves every other tool, Bash and Write included, because unlisted tools fall through to the permission mode, not to a denial. If you need bypass mode with limits, use disallowed_tools instead.
Running headless without a budget cap. Claude’s subagents can spawn their own subagents up to three layers deep by default, and Opus-family models delegate more eagerly than smaller ones. Set max_budget_usd on anything unattended. There’s no equivalent safety net on the OpenAI side if a handoff chain starts looping; you have to watch for it yourself, probably through tracing.
Conclusion
If your agent’s job is closer to “operate on a codebase or a filesystem and get something done,” I’d reach for the Claude Agent SDK: the tool permission model and the subagent isolation were clearly built for exactly that, because they’re the same machinery running Claude Code itself. If your job is closer to “take an incoming request and route it to the right specialist, with clear content rules at the boundary,” the OpenAI Agents SDK’s handoffs and guardrails fit that shape without any bending.
Don’t pick based on which one you read about first. Build the smallest version of your actual workflow in both, a day each tops, and see which one’s failure modes are the ones you’re prepared to debug at 2am. That’s the only test that actually tells you anything.
FAQ
Do I need Claude Code installed separately to use the Claude Agent SDK?
Usually not. Both the Python and TypeScript packages bundle a native Claude Code binary. The exception is when pip installs a source distribution instead of a platform wheel (ARM64 Windows is the case the docs call out), in which case you install Claude Code natively and the SDK finds it on your PATH.
Can I use both SDKs in the same project?
Nothing technical stops you from calling both from one service. I wouldn’t make it the default plan, though. The harder part isn’t the code, it’s keeping two different delegation mental models (subagents vs handoffs) straight across a team that has to maintain both.
Which SDK is cheaper to run?
Neither one, inherently. Cost comes down to model choice and how many agents you let spin up. The practical difference is tooling: Claude’s SDK has a max_budget_usd hard stop that counts subagent spend against the same total. The OpenAI Agents SDK docs I checked don’t surface an equivalent built-in cap, so you’d track spend yourself, likely through tracing.
What happens when an OpenAI guardrail trips?
The run raises InputGuardrailTripwireTriggered or OutputGuardrailTripwireTriggered rather than returning a flagged result you have to check for. If you don’t wrap the call in try/except, that exception propagates straight up through your own code.
Do Claude’s subagents run in parallel by default?
They can. Claude decides when to spawn one and whether to run it in the background; by default, up to 20 subagents can run concurrently and nesting goes three layers deep, both adjustable through environment variables (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH).


