Harness profile
OpenAI Agents SDK: a small toolkit for agents, handoffs and guardrails
The OpenAI Agents SDK is an open-source library, in Python and TypeScript, for building agents that use tools, hand work to each other and pause for approval. It suits teams that want a light agent loop with tracing built in, rather than a full orchestration platform.
Explained from public sources. Mai has not built this yet.
On this page
In plain English
The OpenAI Agents SDK is a code library for building AI agents. You describe each agent with instructions and a set of tools, and the library runs the back-and-forth with the model until the job is done. Agents can pass a conversation to a better-suited colleague, and a tool can be marked so that a person must approve it before it runs. Every run leaves a trace you can inspect afterwards.
How it works
The SDK is deliberately small. The documentation names a handful of building blocks: agents (a model with instructions and tools), handoffs and agents used as tools for delegation, guardrails that check inputs and outputs, sessions that keep conversation history between runs, human-in-the-loop approvals, and tracing. You create an agent and pass it to a runner, and the runner loops: call the model, run any tools it asks for, follow any handoff, and repeat until there is a final answer.
In: Request. Then Runner loop. Then Triage agent, Billing agent, Research agent. Then Function tools, MCP servers, Hosted tools. Then You approve. Then Trace of the run.
Handoffs. The model sees each handoff as a tool, named after the receiving agent. When it chooses one, the receiving agent takes over the conversation and, by default, sees the full history. An input filter can trim what the next agent sees. If you want a specialist to answer a narrow question without taking over, the docs point you to wrapping that agent as a tool instead.
Tools and MCP. Tools can be plain functions, tools hosted by OpenAI, or tools on MCP servers. Local or remote MCP servers connect over stdio or Streamable HTTP (the older SSE transport is kept only for legacy servers), and a hosted option lets the OpenAI Responses API call a public MCP server directly. Approval can be required for all MCP tools, none, or a chosen list.
Approvals. A tool marked needs_approval (always, or decided per call) stops the run when the model tries to use it. The result lists the pending approvals, and the whole run state can be saved as JSON, approved or rejected later, and resumed. The docs warn that this saved state is not authenticated, so it should only live in storage your server controls.
Tracing. Tracing is on by default and sends runs to the OpenAI Traces dashboard. It can be turned off globally or per run, and traces can be routed to other observability tools through processors.
Beyond text. The SDK also offers realtime and voice agents, and sandbox agents that work inside an isolated workspace for longer tasks that inspect files and run commands.
The Python package needs Python 3.10 or newer. The TypeScript version runs on Node.js 22 and later, Deno and Bun. Both are MIT licensed and are libraries you run in your own code, not a hosted service.
What it does best
- Low ceremony. There are few concepts to learn. A working agent with tools is a few lines, and the loop is handled for you.
- Clear delegation. Handoffs and agents as tools are two distinct, named ways to split work, which makes a router with specialists easy to express.
- Approval that survives a restart. Pausing a run, saving its state and resuming it hours later fits real approval flows where a person answers in their own time.
- Guardrails as a first-class idea. Input and output checks run alongside the agent and can stop a run early.
- Tracing without set-up. Every run is traced out of the box, which helps a great deal while building.
Where it stops
- It is a loop, not a workflow engine. There is no graph of steps with durable checkpoints between them. Handoffs work within a single run. For multi-day processes with branches and retries, you build the outer structure yourself.
- Defaults lean towards OpenAI. Other models work through adapters, but the Responses API, hosted tools and the default trace destination are OpenAI services. If you need traces to stay in your own systems, you have to configure that.
- Tracing has a data caveat. The docs state that tracing is unavailable for organisations that use OpenAI under a Zero Data Retention policy.
- Memory is conversation history. Sessions keep the thread of a conversation. Long-term memory across users and weeks is yours to design.
Where it goes wrong
The common failure is trusting the loop with too much. A triage agent with many handoffs can pick the wrong specialist, and because the receiving agent sees the whole history by default, irrelevant or untrusted text travels with it. Input filters help, but you have to use them. Approval rules on MCP servers decide by tool name rather than by the arguments of the call, so a tool that is safe for one input and risky for another needs its own check. And saved run state has to be treated like any other sensitive record.
How Mai AI uses it
I would use the OpenAI Agents SDK when a client system is mostly one conversation at a time: a request comes in, a router sends it to the right specialist, a few tools run, and anything that writes to a real system waits for a person. That is a good match for its handoffs and resumable approvals. I would keep traces in the client’s own logging rather than relying only on the default dashboard.
The idea I take from it, whatever the stack, is the split between handing over a conversation and calling a colleague as a tool. Getting that choice right is most of routing and specialist agents, and its save-approve-resume approach is a clean model for human approval gates. For how these pieces come together in a system built around one business, see how Mai AI designs custom AI operations systems.
Questions and answers
Is the OpenAI Agents SDK free?
Yes. The library is open source under the MIT licence in both its Python and TypeScript versions. You still pay for the model calls it makes, whichever provider you use.
Can the OpenAI Agents SDK use models other than OpenAI?
Yes. The repository describes it as provider-agnostic: it uses the OpenAI Responses and Chat Completions APIs by default and reaches other providers through optional adapters such as LiteLLM and any-llm.
What is a handoff in the OpenAI Agents SDK?
A handoff passes control of the conversation from one agent to another. The model sees each handoff as a tool, for example one named after the receiving agent, and picks it when the request belongs elsewhere.
Does the OpenAI Agents SDK support MCP?
Yes. It can call tools on MCP servers over stdio or Streamable HTTP, and can let the OpenAI Responses API call a public MCP server for you as a hosted tool. Approval can be required per tool.
Where do OpenAI Agents SDK traces go?
By default, to the Traces dashboard in the OpenAI platform. You can switch tracing off, or send traces to other tools through custom processors. The docs say tracing is not available to organisations under a Zero Data Retention policy.
Patterns it is known for
- PatternRouting and specialist agents
Routing means one agent reads each request and hands it to the specialist best placed to handle it, such as finance, operations or sales. Each specialist has its own instructions, tools and permissions, which keeps answers sharper and access tighter than one agent trying to do everything.
- PatternSub-agents and parallel work
Sub-agents are helper agents that a lead agent starts for one well-defined piece of a larger job, each with its own fresh context, instructions and tools. Several can run at once and report back short findings, which makes broad tasks faster, at the price of more model usage.
- PatternThe tool layer and MCP
AI agents reach real systems through tools: named functions such as "find invoice" that the model asks to run, while ordinary code does the actual work. MCP, the Model Context Protocol, is an open standard for offering those tools and data to any AI application in the same way.
- PatternHuman approval gates
Human approval gates sort every action an AI agent can take into three levels: draft only, needs a person to approve, or allowed to run automatically. The agent prepares, a person signs off anything that matters, and the system refuses any action that does not match what was approved.
- PatternTraces and audit logs
You see what an AI agent did and why by recording a trace of every run, each model call, tool call and decision as a timed step, plus a separate audit log of every action that changed something and who approved it. Traces are for debugging; the audit log is the permanent record.
- PatternAgent safety
You make an AI agent safe by limiting what it can do, not by trusting what it says. Give it the narrowest tools and permissions, run risky work in a sandbox, require a person to approve consequential actions, and treat every email, document and web page it reads as possibly hostile.
Related entries
- Harness profileLangGraph
LangGraph is an open-source framework from LangChain for building stateful agents as graphs of steps, with saved checkpoints so a run can pause, wait for a person and resume. It is best for long-running, multi-step work where you want explicit control over every path.
- Harness profileClaude Code and Agent SDK
Claude Code is Anthropic's agentic coding tool that reads a codebase, edits files and runs commands from the terminal, IDE, desktop app or browser. The Claude Agent SDK packages the same agent loop and tools as a Python and TypeScript library, for building your own agents on Claude.
Sources
- OpenAI Agents SDK documentationopenai.github.io
- Handoffsopenai.github.io
- Human-in-the-loopopenai.github.io
- Tracingopenai.github.io
- Model context protocol (MCP)openai.github.io
- openai-agents-python on GitHubgithub.com
- openai-agents-js on GitHubgithub.com