OpenAI Agents SDK (JavaScript/TypeScript)

The SDK is a runner around a model loop. An Agent holds instructions, tools, guardrails and a list of handoffs; run() calls the model, executes tool calls, and repeats until a final output is produced or control passes to another agent. Tools include local function tools, OpenAI-hosted tools such as web search, MCP servers and sandbox capabilities.

The docs describe two multi-agent patterns. With handoffs, a triage agent transfers the conversation to a specialist, which becomes the active agent. With agents as tools, a manager agent calls specialists through agent.asTool() and stays responsible for the answer. Orchestration in plain code, such as chaining runs or running them in parallel, is also covered. There is no separate graph or workflow engine.

State across turns is handled by sessions, which prepend stored history to each run and persist new items afterwards. The package ships an in-memory session for development and a session backed by OpenAI's Conversations API; other stores implement the Session interface. Within a run, RunState captures progress and can be serialized with toString() and restored with RunState.fromString(). Traces of model calls, tool calls and handoffs go to the OpenAI Traces dashboard by default.

A function tool, an agent exposed with asTool(), or a hosted MCP tool can require approval through needsApproval, either always or via an async check on the arguments. When a call needs approval, the run ends the turn with result.interruptions instead of executing it. The application calls result.state.approve(item) or result.state.reject(item), optionally with alwaysApprove / alwaysReject so later calls to the same tool follow that decision, and then passes the state back to run().

This works across handoffs and nested agents-as-tools, because interruptions surface on the outer run. For long pauses, result.state.toString() stores the run and RunState.fromString(agent, saved) restores it, so a reviewer can decide later in another process. Guardrails can also stop a run when input or output fails a check.

npm install @openai/agents zod

import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';

const refund = tool({
  name: 'issue_refund',
  description: 'Refund an order',
  parameters: z.object({ orderId: z.string() }),
  needsApproval: true,
  execute: async ({ orderId }) => `Refunded ${orderId}`,
});
const billing = new Agent({ name: 'Billing', instructions: 'Handle refunds.', tools: [refund] });
const triage = new Agent({ name: 'Triage', instructions: 'Send billing questions to Billing.', handoffs: [billing] });

let result = await run(triage, 'Please refund order A-17');
while (result.interruptions?.length) {
  for (const item of result.interruptions) result.state.approve(item);
  result = await run(triage, result.state);
}
console.log(result.finalOutput);

• Supported server runtimes are Node.js 22+, Deno 2.35+ and Bun 1.2.5+; Cloudflare Workers need nodejs_compat and manual trace flushing.
• The SDK uses Zod v4 for tool schemas and structured output.
• OPENAI_API_KEY must be set (or setDefaultOpenAIKey() called); browser realtime sessions should use a short-lived client token minted on your server.
• Tool search and deferred tool loading need the OpenAI Responses API; the AI SDK adapter for other providers does not support them.
• Versions follow 0.Y.Z, and a minor bump can contain breaking changes; v0.18.0, for example, moved Docker sandbox file APIs inside the container.

Yes, as a client. Agents can use hosted MCP tools through the Responses API or connect to Streamable HTTP and stdio MCP servers. The docs do not describe running an MCP server.

No. A maintainer said in issue #171 that built-in A2A support was not planned at the time, and no A2A code was found in the repository on 2026-09-30.

The SDK is MIT-licensed. Model calls are billed by whichever provider you use, such as the OpenAI API.

Node.js 22+, Deno and Bun are supported server runtimes; Cloudflare Workers have limited support, and realtime voice agents run in the browser.

It is a separate repository for JavaScript and TypeScript with the same core ideas (agents, tools, handoffs, guardrails, sessions) and its own release line, currently 0.18.