OpenAI Agents SDK Guide: Building Tool-Using Agents

If you are building software that plans, calls tools, and finishes multi-step work, OpenAI’s Agents SDK is one of the cleanest ways to own that loop in application code. It is not a chat window, not a Zap, and not a substitute for Claude Code on a git repo.

This guide covers the concepts that matter in production — agents, tools, handoffs, guardrails, sessions, tracing — when to use the SDK versus fixed automation or productised coding agents, and the safety habits that stop demos from becoming incidents. Canonical documentation: OpenAI Agents SDK and the language-specific references on Python / TypeScript GitHub trees.

Companion theory: complete AI agents guide. First supervised loop without a framework: how to build your first AI agent. Connectors: What is MCP? and MCP advanced guide.

Concepts track OpenAI’s public Agents documentation as read for PromptHive coverage (verifiedAt 2026-08-05). APIs and package names move; the decision shape does not.

The short answer

One line: the Agents SDK is for builders embedding agent behaviour; coding CLIs are for developers finishing tickets; Zapier is for operators running fixed processes.

What the SDK actually is

OpenAI positions agents as applications that plan, call tools, collaborate across specialists, and keep enough state to complete multi-step work. The SDK’s job is to make that runtime boring:

• define one or more agents (instructions + tools + policies),
• run them until the task completes, needs a tool result, hands off, or pauses for approval,
• observe what happened (traces),
• resume after human review when you designed for it.

It is a production-oriented evolution of earlier multi-agent experiments (including Swarm-era ideas): few primitives, Python/TS-first composition, built-in tracing.

Core primitives (learn these five)

Around them: sessions (working memory across turns), results/state (what a run returns and how to continue), sandbox agents (isolated workspaces for files/commands when you need them), voice/realtime paths if your product is spoken.

You do not need every feature on day one. A single agent with two tools and a human approval on the write tool is already a real system.

Agents SDK vs Responses API

Official guidance is clear enough to quote as policy:

• Responses API — you own model interactions, tool dispatch, branching, and state. Best for custom features where the loop is your product logic.
• Agents SDK — the runtime manages recurring orchestration: tool loops, specialist routing, guardrails, resumable approvals, tracing.

Many codebases use both: SDK for managed workflows, raw Responses for simple paths. That is healthy, not indecisive.

Agents: writing a good specialist

A good agent definition is a job contract, not a personality bio.

Include:

1. Scope — what it must do and what it must refuse.
2. Tools allowed — the minimum set.
3. Output shape — structured final answer when a machine consumes it.
4. Escalation — when to hand off or pause for a human.
5. Non-goals — “does not refund,” “does not email customers,” “does not deploy prod.”

Bad instructions are novels. Good instructions are onboarding docs for a careful junior with dangerous buttons.

Model choice, provider setup, and transport sit in the models docs; treat them as ops decisions (latency, cost, data residency), not as magic.

Tools: the entire product risk

Tools are why agents exist and why they hurt.

Function tools

Turn application functions into tools with schemas (Pydantic-style validation in Python is a common pattern). Write descriptions like tickets for a junior: inputs, side effects, failure modes. Vague descriptions produce creative disasters.

Platform / hosted tools

Search, code execution, and other hosted capabilities appear in platform tool docs. Prefer them when OpenAI’s sandboxing beats your half-built alternative — still log and budget.

MCP tools

The SDK can call tools exposed via Model Context Protocol connections. That does not make MCP “safe by default.” Hosts must still obtain consent; tool descriptions remain untrusted unless the server is trusted; credentials stay outside the model. Deepen with What is MCP? and production multi-server habits in the MCP advanced guide.

Agents as tools

A manager agent invokes a specialist as a tool, gets a result back, and keeps ownership of the user-facing reply. Use this when the parent must synthesise multiple specialists without giving up the conversation.

Handoffs vs agents-as-tools (do not blur them)

Community pain usually comes from wanting dynamic routing but implementing one-way handoffs that never return. If you need “call A, then maybe B, then answer,” start with agents-as-tools or an explicit graph in your code — not infinite handoff hope.

Design specialist ownership using the orchestration docs; keep one clear owner for every user-visible message.

Guardrails and human review

OpenAI’s docs treat guardrails and human review as first-class when workflows should block or pause before risky work continues. Use them for:

• input validation (jailbreaks, out-of-policy requests),
• output checks (PII leak, hallucinated refund promises),
• tool approvals (money movement, external email, prod writes).

Architecture rule we reuse everywhere: the model may propose; only a human or a deterministic policy may commit irreversible effects. PromptHive runs that pattern on its own MCP catalogue path — proposals queue; humans publish. An unstaffed queue looks like downtime; staff the boundary.

If your “agent” cannot pause, it is not production-ready for high-stakes tools.

Sessions, results, and state

Multi-turn work needs a memory strategy:

• stateless runs with full history each time (simple, can get large),
• SDK sessions for working context inside a loop,
• your database for long-lived customer state (orders, entitlements) — never let the model be system of record for money or identity.

Read run results carefully: final output, intermediate items, which agent last owned the thread, and whether the run is resumable after approval. Build product UI around those states; do not invent a second shadow state machine that disagrees with the SDK.

Sandbox agents (when files and shell enter the chat)

Updated Agents SDK paths include sandbox agents: isolated workspaces with files, commands, packages, mounts, and resumable sandbox sessions. That is the right shape when the agent must produce artifacts or inspect repos without sharing your laptop’s ambient credentials.

It is still not a free pass to point the sandbox at production databases. Same blast-radius rules as Claude Code and Codex: git, review, least privilege.

Tracing, evals, and “it worked in the demo”

Built-in tracing across model calls, tools, agents, guardrails, and handoffs is a major reason to use the SDK instead of a home-grown loop. Use traces to answer “what did it try?” — the only question that matters after a bad action.

Then add evaluation loops for agent workflows (OpenAI documents agent evals separately). A single happy-path video is not a test suite. Score:

• tool-choice correctness,
• refusal on out-of-scope asks,
• approval pauses firing when they should,
• latency and cost per successful resolution.

When to use the Agents SDK vs Zapier / n8n

Fixed automation still wins for ops plumbing. See Zapier vs n8n, AI workflow automation, and AI automation for small business. Slogan that holds: agents draft product behaviour; workflows commit business process.

When to use the SDK vs coding agents (Codex / Claude Code)

Codex vs Claude Code is a product decision for humans writing code: OpenAI Codex vs Claude Code. The Agents SDK is how you ship agent features to users who will never open a terminal.

Do not “install the SDK” to replace Claude Code. Do not buy Claude Code seats to implement multi-tenant refund agents in your app.

A minimal architecture that survives production

1. One agent, two tools — e.g. lookup_order (read) and propose_refund (write that only creates a proposal).
2. Guardrail on inputs that mention competitors’ policy injection patterns or demand secret dump.
3. Human approval before execute_refund.
4. Trace export to your observability stack.
5. Hard budgets on model tokens and tool QPS.
6. Idempotency keys on any write tool.
7. Kill switch — feature flag that forces all runs into “propose only.”

Only after this is boring should you add handoffs, MCP servers, or sandbox coding.

Safety checklist (print next to the deploy button)

• Tool credentials are server-side, short-lived, least privilege.
• Tool descriptions and returned content are untrusted (prompt injection).
• Irreversible tools require approval or deterministic policy, not “the model is careful.”
• Multi-agent graphs have a clear owner and a max hop count.
• PII and secrets are redacted from traces where policy requires.
• You can reconstruct “agent X called tool Y with Z” after an incident.
• On-call knows how to disable the agent without taking down the whole API.

Failure arithmetic still applies: long dependent chains fail more often. Shorten them — complete AI agents guide.

Implementation ladder (two weeks, no cosplay)

Days 1–2: Hello-world agent from the quickstart; run with tracing on.
Days 3–4: One read-only function tool against a staging API; structured outputs.
Days 5–6: One write tool that only enqueues; human approval UI; resume path.
Day 7: Guardrails on input and final output.
Days 8–9: Eval set of 20 real tickets (including adversarial).
Days 10–11: Optional second specialist via agents-as-tools (not handoff soup).
Days 12–14: MCP only if a real external system must enter; otherwise ship.

If day 3 already needs five agents and twelve MCP servers, you are building a diagram, not a product.

Common failure modes

• God-agent with every tool “just in case.”
• Handoff loops with no termination.
• Silent tool errors swallowed into hallucinated success text.
• Using chat history as the ledger for payments or inventory.
• Equating demo latency with production p95 under tool timeouts.
• Skipping staffed approvals because “we’ll watch the dashboard.”

Worked example: support refund agent (shape only)

This is an architecture sketch, not copy-paste production code — APIs and package names move; the shape is the point.

1. Triage agent — tools: lookup_order, lookup_customer_tier. No writes.
2. Policy guardrail — blocks requests that demand “ignore refund policy.”
3. Refund specialist (agents-as-tools from a manager, or handoff if the user should stay with billing) — tool: propose_refund only.
4. Human approval UI — shows order, reason, amount, model rationale.
5. Executor (non-model or tightly gated tool) — execute_refund with idempotency key after approve.
6. Trace + ticket comment — permanent record of who approved what.

Notice what is missing: the model never holds the payments admin key; the model never emails the customer a “you’re refunded” message before the executor succeeds; the manager does not own fifteen unrelated tools.

Compare that to a Zapier flow that always refunds under $20 with a static rule — if the rule is truly static, you did not need an agent. Put the LLM only where judgment varies.

Multi-tenant product concerns

If your SaaS exposes an agent to many customers:

• Isolate credentials per tenant (or per workspace).
• Cap tool calls and tokens per tenant per day.
• Never let tenant A’s retrieved documents enter tenant B’s context.
• Store approvals and traces with tenant ids for legal hold.
• Provide a customer-visible “agent activity” log for trust.
• Default new workspaces to propose-only until they configure send/write.

These are product requirements, not nice-to-haves. A clever handoff graph will not save a confused-tenant incident.

How the SDK relates to MCP and coding agents (one more time)

People search “OpenAI agents” and land on all five. Send them to the right shelf.

Honest limits in 2026

The SDK makes orchestration legible. It does not make long autonomous professional work reliable. Benchmarks on multi-app professional tasks still show low absolute scores for long chains; design for supervision. Prefer checkable domains and short paths — the same advice we give for every agent product on best AI agents (2026).

Verdict

Use the OpenAI Agents SDK when you are a builder who needs a real agent loop inside an application: tools, optional handoffs, guardrails, approvals, and traces. Prefer the Responses API when you want full custom control of a short loop. Prefer Codex / Claude Code / Cursor for human developers in a repo. Prefer Zapier / n8n for fixed multi-app operations.

Start with one specialist, two tools, and a human gate. Add multi-agent complexity only when traces prove a single agent is the bottleneck — not when a blog post said “swarm.”

Where to go next

• Official: Agents SDK guide · Python SDK docs
• Complete AI agents guide · How to build your first AI agent
• Best AI agents (2026) — product picks by job
• OpenAI Codex vs Claude Code
• What is MCP? · MCP advanced guide
• AI workflow automation · Zapier vs n8n · Zapier review
• ChatGPT review · AI glossary