Install
npm install @openai/agents@0.22.0 zodOpenAI'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.
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
npm install @openai/agents@0.22.0 zodVersion
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.
| Release | Changes |
|---|---|
| 0.21 | Breaking: Runloop sandbox provider removed; usage-detail values need narrowing to numbers before arithmetic. |
| 0.20 | Breaking: automatic MCP tool discovery stops at 64 pages unless maxListPages is set; model calls after approval resumes count towards maxTurns. |
| 0.19 | Agent-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.18 | Blocked tool outputs redacted from replay state; Unix-local and Docker sandbox file operations hardened. |
| 0.16 | Testing utilities in @openai/agents/testing: scripted models, sandbox sessions, Realtime. |
| 0.15 | Breaking: requires the openai Node SDK v7.2+ (Node.js 22+); default model gpt-5.6-luna; newer MCP protocol negotiation with legacy fallback. |
| 0.14 | Sensitive model and tool data no longer logged by default; default task and turn tracing with a per-run opt-out. |
| 0.13 | Default Realtime model gpt-realtime-2.1. |
| 0.11 | Breaking: local sandbox sources outside the base directory need explicit path grants; Realtime defaults upgraded. |
| 0.10 | Breaking: default model switched to gpt-5.4-mini. |
| 0.9 | Sandbox agents (@openai/agents/sandbox). |
| 0.7 | Opt-in model retry policies (modelSettings.retry, retryPolicies). |
| 0.5 | Responses WebSocket transport and withResponsesWebSocketSession(). |
| 0.4 | Breaking: 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 →
| Date | Version | Changes | Reviewer |
|---|---|---|---|
| 2026-10-24 | 0.22.0 | Deep-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-21 | 0.22.0 | Rewrote 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-21 | 0.22.0 | Re-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-29 | 0.11.1 – 0.11.6 | Routine version bumps with export checks against each installed release. | Claude routine |
| 2026-04-21 | 0.8.5 | Banner bumped to the then-installed release. | — |
| 2026-04-09 | 0.8.3 | Guide revised for 0.8 (approval flows documented, browser bundle notes). | — |
| 2025-11 | 0.3.2 | Initial TypeScript guide; Swarm migration; MCP. | — |
Note: Python implementation lives at OpenAI Agents SDK (Python).