Skip to content

OpenAI Agents SDK (TypeScript)

OpenAI's TypeScript SDK for agent apps: agents, tools, handoffs, guardrails, approvals, sessions, tracing, realtime voice and sandbox agents, with install, a first example and release notes.

GroupMulti-Agent
Current versionv0.22.0
Bonds withTs

OpenAI’s TypeScript library for agent applications, with the same primitives as the Python SDK: agents, tools (including other agents and MCP servers), handoffs, guardrails, human approvals, sessions and tracing, plus realtime voice agents for the browser and sandbox agents with a workspace. It runs on Node.js, Deno and Bun.

Install

Terminal window
npm install @openai/agents@0.22.0 zod

Version

v0.22.0 · checked 2026-11-19 · Node.js 22+ · Zod 4

Best for

Full-stack agents, HITL-approved workflows, browser-side tools.

This guide targets @openai/agents 0.22.0; all @openai/agents* packages share one version. The packages are versioned 0.Y.Z and a minor release may break public interfaces, so pin an exact version and check this table before upgrading. Taken from the upstream changelogs; Breaking marks changes that can affect existing code.

ReleaseChanges
0.21Breaking: Runloop sandbox provider removed; usage-detail values need narrowing to numbers before arithmetic.
0.20Breaking: automatic MCP tool discovery stops at 64 pages unless maxListPages is set; model calls after approval resumes count towards maxTurns.
0.19Agent-tool streaming callbacks capped at 1024 pending events (onStreamMaxPendingEvents); resumed MCP calls bound to their original server; default tool-parse failures redacted.
0.17–0.18Blocked tool outputs redacted from replay state; Unix-local and Docker sandbox file operations hardened.
0.16Testing utilities in @openai/agents/testing: scripted models, sandbox sessions, Realtime.
0.15Breaking: requires the openai Node SDK v7.2+ (Node.js 22+); default model gpt-5.6-luna; newer MCP protocol negotiation with legacy fallback.
0.14Sensitive model and tool data no longer logged by default; default task and turn tracing with a per-run opt-out.
0.13Default Realtime model gpt-realtime-2.1.
0.11Breaking: local sandbox sources outside the base directory need explicit path grants; Realtime defaults upgraded.
0.10Breaking: default model switched to gpt-5.4-mini.
0.9Sandbox agents (@openai/agents/sandbox).
0.7Opt-in model retry policies (modelSettings.retry, retryPolicies).
0.5Responses WebSocket transport and withResponsesWebSocketSession().
0.4Breaking: Zod v3 support dropped; Zod v4 required for schema-based tools and outputs.

Always set model explicitly if you depend on a particular model: the default has changed twice.

import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions: 'You are a helpful assistant.',
});
const result = await run(agent, 'What is 2 + 2?');
console.log(result.finalOutput);

Ready? Start Zero → Hero Step 1 →


DateVersionChangesReviewer
2026-10-240.22.0Deep-dive audit: all 61 TypeScript blocks re-checked under tsc --strict and run against ScriptedModel; corrected the tool-guardrail error handling (a thrown tool tripwire arrives wrapped in ToolCallError); documented toolExecution.preApprovalInputGuardrails; removed an invented regex routing rule from the diagrams.—
2026-10-210.22.0Rewrote the comprehensive guide (every block passes tsc --strict and runs against ScriptedModel), the production guide around the SDK’s own controls, and the middleware page as lifecycle events, tool guardrails and approvals; added agent.asTool(), MCP, hosted tools, sandbox and realtime sections; folded the “features” page into the comprehensive guide and this page (one release table, corrected from the changelog); reduced the Swarm page to a short note, since Swarm was Python-only.—
2026-10-210.22.0Re-verified all code against the current release with the TypeScript compiler; replaced invented APIs (new Session(), inputGuardrail(), trace(), requiresApproval, approvalHandler, outputSchema, createMCPServer, litellm/ model strings); fixed package names; “What’s new” rewritten from the upstream changelogs.—
2026-05-09 – 2026-05-290.11.1 – 0.11.6Routine version bumps with export checks against each installed release.Claude routine
2026-04-210.8.5Banner bumped to the then-installed release.—
2026-04-090.8.3Guide revised for 0.8 (approval flows documented, browser bundle notes).—
2025-110.3.2Initial TypeScript guide; Swarm migration; MCP.—

Note: Python implementation lives at OpenAI Agents SDK (Python).