Skip to content

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.

StudiedLast reviewed 4 min read

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.

A runner loops between the model, tools and handoffs, and pauses when a tool needs approval

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.

Sources

  1. OpenAI Agents SDK documentationopenai.github.io
  2. Handoffsopenai.github.io
  3. Human-in-the-loopopenai.github.io
  4. Tracingopenai.github.io
  5. Model context protocol (MCP)openai.github.io
  6. openai-agents-python on GitHubgithub.com
  7. openai-agents-js on GitHubgithub.com