Loading…
Stack Guide · OpenAI Agents SDK
The OpenAI Agents SDK is OpenAI's own framework for building agents in Python. It provides handoffs between specialized agents, guardrails as typed filters, built-in tracing through the OpenAI dashboard, and native integration with the Responses API.
The first-party origin means it stays synchronized with new OpenAI capabilities, when the Responses API gets new features, the Agents SDK surfaces them first. The tradeoff is that it's OpenAI-specific: no multi-provider support, and a less expressive orchestration model than LangGraph for complex conditional workflows.
These are our notes on when that tradeoff is worth it and when it isn't.
Building on OpenAI's stack?
The first-party advantages are real in specific contexts. These are the situations where they matter most.
If your organization has existing OpenAI API usage, existing spend commitments, and established monitoring through the OpenAI dashboard, the Agents SDK is a natural next step. The authentication, the billing, and the model access are already in place. Adding agent orchestration through the SDK adds one dependency, not a new vendor relationship.
The Agents SDK has first-class support for agent handoffs: a triage agent determines what kind of request this is and hands it off to a specialized agent, a billing agent, a technical support agent, a sales agent. The handoff transfers context cleanly and the receiving agent knows what it's been handed. This pattern is common in customer service and support automation.
Every agent run is traced automatically and visible in the OpenAI platform dashboard. You can see which agent ran, what tools it called, what the model returned, and where time was spent, without setting up a separate tracing infrastructure like LangSmith or Langfuse. For teams already using OpenAI's dashboard, this is zero-configuration observability.
The Agents SDK has input and output guardrails built into the agent definition. An input guardrail runs before the main agent to validate or filter the request, checking for off-topic inputs, policy violations, or format problems. An output guardrail runs after to validate the response before it's returned. This is cleaner than implementing the same logic as pre/post-processing around an unguarded agent.
Three capabilities define what the SDK actually provides and how it differs from building the same patterns manually.
Agent handoffs with context passing
When an agent determines that a request belongs to a different specialized agent, it executes a handoff. The context (the original message, any tool call results, relevant metadata) transfers to the receiving agent. The handoff is a first-class operation in the SDK, not a workaround. The receiving agent can see the full context of why it was handed this request.
Responses API with native tool calling
The Agents SDK is built on the Responses API, which has native tool calling support. Tools are defined as typed schemas and the model decides when and how to call them. The SDK handles the tool-call loop automatically: the model calls a tool, the SDK runs it, returns the result to the model, and the model decides if it needs to call another tool or return a final response.
Input and output guardrails
Guardrails are typed filters defined alongside the agent. An input guardrail receives the user message and either passes it through, modifies it, or terminates the run with an error. An output guardrail receives the agent's response and applies the same options. Guardrails run as separate LLM calls, which adds latency but allows complex validation logic that simple regex or rules can't provide.
The SDK's constraints are narrow but firm. These three situations are clear disqualifiers.
Multi-provider architectures
The Agents SDK is OpenAI-specific. It does not support Anthropic, Google, Mistral, or other providers through the same abstraction. If your architecture needs to route some requests to Claude and others to GPT, or if you want the option to switch providers as the market evolves, LangGraph or LangChain gives you that flexibility. The Agents SDK does not.
Complex stateful graph-based orchestration
The Agents SDK models agent behavior as a linear conversation with handoffs. LangGraph models agent behavior as an explicit directed graph with typed state, conditional edges, and checkpointing. For workflows that require complex conditional routing — 'if the analysis step found X, go to path A, otherwise go to path B, unless condition C is true in which case escalate': LangGraph is more expressive. The Agents SDK is less flexible for complex branching logic.
Non-Python teams not using OpenAI
The Agents SDK is a Python library. If your backend is TypeScript, the Agents SDK requires a separate Python service. If you're not using OpenAI models, the SDK provides no value. These constraints are narrow but firm. For TypeScript teams on OpenAI, the Vercel AI SDK with Mastra or direct SDK usage is a more natural fit than a Python dependency.
The Agents SDK earns its place in specific project contexts. Here is where we find it genuinely useful.
We use the Agents SDK when a client is already committed to OpenAI — has an enterprise agreement, existing usage in their platform, and wants minimal new dependencies. The built-in tracing integrates directly with their existing OpenAI dashboard, which saves setup time and gives their engineers a familiar interface for monitoring agent behavior.
The handoff pattern maps well to tiered support systems: a triage agent classifies the request and routes it to a billing specialist, technical support specialist, or escalation agent. The context passing ensures the receiving agent has everything it needs without making the user repeat themselves. This is one of the cleaner use cases for the Agents SDK's specific abstractions.
For applications where agent outputs need to comply with policy (financial advice disclaimers, medical information caveats, off-topic deflection) the SDK's output guardrails provide a systematic way to enforce those policies. We define guardrails as typed filters that check every output before it reaches the user, rather than hoping the system prompt is sufficient.
The SDK's clean abstractions invite specific misuse patterns. These are the ones that cost the most in production.
Treating it as provider-agnostic
The Agents SDK is built on OpenAI's Responses API and is tightly coupled to OpenAI models. Teams that start with it expecting to switch providers later are in for an unpleasant rewrite. If multi-provider flexibility is a requirement (now or in the future) design the architecture around a provider-agnostic layer from the start.
Over-using guardrails for logic that belongs in the agent
Guardrails are expensive: each one is a separate LLM call. We've seen architectures where five different guardrails run on every request, adding multiple seconds of latency and significant cost. Guardrails are for enforcement of hard rules that must hold regardless of what the agent does. Business logic (routing decisions, conditional behavior, validation that depends on context) belongs in the agent or in tool code, not in guardrails.
Not using the Responses API's native tool calling
Some teams wrapping the Agents SDK implement tool calling manually, parsing the model's output for tool invocations and dispatching them themselves. The Responses API has native structured tool calling that the Agents SDK surfaces directly. The native pattern is more reliable, produces better-structured tool call payloads, and benefits from the model's training on the Responses API format. Use the SDK's tool definition system.
Tell us about the workflow, how many agents, what the handoffs look like, and whether you need guardrails or complex conditional routing. We can give you a direct opinion on whether the Agents SDK fits or whether LangGraph is the better foundation.