@openai/agents

@openai/agents is OpenAI’s official TypeScript/JavaScript SDK for building multi-agent LLM workflows. It provides an Agent abstraction configured with instructions, tools, guardrails, and handoffs to other agents, plus a Runner that drives the full turn loop — tool execution, streaming, session/conversation history, and built-in tracing — so you don’t have to hand-roll the orchestration around a chat-completion loop yourself.

Beyond standard text agents, the package bundles three specialized surfaces under one install: Sandbox Agents (beta) that pair an agent with a filesystem workspace and a pluggable local/Docker/hosted sandbox client for longer-running coding-style tasks; Realtime Agents for low-latency, WebRTC-based voice interactions in the browser; and Model Context Protocol (MCP) tool support. It ships as a thin composition of sibling packages (agents-core, agents-openai, agents-realtime) that wire OpenAI in as the default model provider while keeping the core runner provider-agnostic underneath.

What You Get

• Agent & Runner core - Define agents with instructions, tools, and output types, then drive them with run(), which manages the full turn loop, streaming, and conversation history for you.
• Handoffs and guardrails - Delegate between specialized agents with typed handoffs, and attach input/output guardrails that can halt or redirect a run before it completes.
• Tool ecosystem - Call plain functions, hosted tools, and MCP servers as tools, with tool-level approval hooks for human-in-the-loop control over risky actions.
• Sandbox Agents (beta) - Pair an agent with a filesystem workspace and a local, Docker, or hosted sandbox client to run shell commands and apply patches across longer tasks.
• Realtime Agents - Build low-latency, WebRTC-based voice agents that share the same agent, tool, and guardrail abstractions as text agents.
• Built-in tracing - Every run, tool call, and handoff is captured as an exportable span tree for debugging and optimizing agent workflows without extra instrumentation.

Common Use Cases

• Customer-support triage - Route incoming requests between a general assistant and specialized agents (billing, technical, escalation) via handoffs.
• Autonomous coding assistants - Use a Sandbox Agent to inspect a repository, run commands, and apply patches across a multi-step coding task.
• Voice-driven assistants - Build a Realtime Agent that connects a browser microphone and speaker over WebRTC for spoken interactions.
• Research and multi-step workflows - Compose agents-as-tools and deterministic/parallel agent pipelines for tasks like financial or web research bots.

Under The Hood

Architecture The @openai/agents package is a thin composition root (packages/agents/src/index.ts) that wires together three sibling workspace packages: agents-core (the actual engine — agent.ts, a multi-thousand-line run.ts implementing the turn loop, handoff.ts, guardrail.ts, tool.ts, and a tracing/ subsystem), agents-openai (the default OpenAIProvider plus a tracing exporter), and agents-realtime (the voice/session layer, re-exported under a realtime namespace). At import time it side-effects by calling setDefaultModelProvider(new OpenAIProvider(…)) and setDefaultOpenAITracingExporter(), so importing @openai/agents wires OpenAI in as the default provider globally while agents-core itself stays provider-agnostic. The runner subsystem (packages/agents-core/src/runner/) is decomposed into roughly two dozen single-purpose modules — runLoop.ts, toolCaller.ts, toolExecution.ts, streamReconciliation.ts, sessionPersistence.ts, mcpApprovals.ts, siblingCancellation.ts — separating turn preparation, model invocation, tool execution, streaming reconciliation, and session persistence into isolated concerns rather than one monolithic Runner class. Handoffs and guardrails are modeled as first-class objects attached to an Agent, and tracing wraps every run/tool/handoff as an exportable span tree, so swapping the model provider, sandbox client, or tracing exporter doesn’t touch the core run loop.

Tech Stack A pure TypeScript monorepo managed with pnpm workspaces and tsc-multi for parallel package builds; runtime dependencies are minimal — debug for logging and the official openai REST client in the top package, with zod as a peer dependency for schema-validated tool and output definitions. It ships dual CJS/ESM builds via explicit per-subpath exports maps (./testing, ./sandbox, ./sandbox/local, ./realtime, ./realtime/testing, ./utils). Vitest is the test runner, with a separate integration config that exercises the live OpenAI API, and releases flow through Changesets with Husky pre-commit hooks. A companion Astro/Starlight documentation site lives alongside the packages and deploys through its own CI workflow. Supported runtimes are Node 22+, Deno, and Bun, with experimental Cloudflare Workers support.

Code Quality The workspace carries around 200 *.test.ts files (over 130 in agents-core alone) covering the run loop, tool execution, handoffs, guardrails, sessions, and sandbox behavior, plus a dedicated integration-tests directory that exercises the real OpenAI API and asserts a released API contract to catch breaking changes against previously published behavior — an unusually rigorous regression net for tracking upstream API drift. TypeScript’s full strict mode is enabled project-wide, ESLint runs through typescript-eslint’s flat config paired with eslint-config-prettier to keep linting and formatting from conflicting, and Prettier runs through Husky hooks pre-commit. Error handling is typed and explicit, with dedicated modules defining specific error classes rather than throwing bare errors or swallowing failures silently.

What Makes It Unique Beyond typical single-agent LLM wrappers, the SDK’s standout ideas are its Sandbox Agents (beta) — agents paired with a persistent filesystem workspace and a pluggable sandbox client (local Unix, Docker, or hosted), letting an agent run shell commands and apply patches across a longer-running task rather than just calling stateless tools — and a human-in-the-loop approval model built into the run loop itself, so a run can pause mid-turn for external approval before invoking a tool, including MCP tool calls. Combined with a first-class Realtime Agent path sharing the same agent/handoff/guardrail abstractions as text agents, and built-in tracing that exports a full span tree of a run without extra instrumentation, this goes further than most agent frameworks toward being a genuine runtime and workspace for agents rather than a thin chat-completion wrapper. Standard patterns like agents-as-tools and deterministic/parallel/routing agent flows are covered too, but those are well-trodden elsewhere.