OpenAI Agents SDK for JavaScript: What @openai/agents Actually Ships

The gap @openai/agents fills in a TypeScript codebase

Building a single LLM call is easy. Building a loop where one agent decides to hand work to another, where tool arguments are validated before execution, where a guardrail can reject an input before it reaches the model, and where you can later see the full trace of what happened, is a pile of plumbing most teams write badly the first time. The OpenAI Agents SDK for JavaScript packages that plumbing as a library. The README describes it as a lightweight framework for building multi-agent workflows in JavaScript and TypeScript, and lists the moving parts explicitly: agents, sandbox agents, realtime agents, handoffs, tools, guardrails, human in the loop, sessions and tracing.

The audience is narrow and identifiable. You are writing TypeScript or JavaScript, you are on Node.js 22 or later, Deno or Bun, and you want the orchestration layer to be a dependency rather than a homegrown abstraction. Cloudflare Workers are listed as experimental support with nodejs_compat enabled, which tells you the maintainers consider edge runtimes a secondary target rather than a primary one.

The provider-agnostic claim is the part worth scrutinising. The README says the SDK supports OpenAI APIs and more, and the repository ships an examples/model-providers directory, so non-OpenAI models are contemplated. But the default path, the tracing UI and the realtime transport are all shaped around OpenAI's own services. Treat provider-agnosticism as an extension point you will have to configure, not a default you inherit.

How the SDK routes a run: agents, handoffs, sessions and tracing

The central object is an Agent: an LLM configured with instructions, tools, guardrails and handoffs. You call run(agent, input) and get back a result whose finalOutput holds the model's answer. That is the whole surface for the simplest case, and the README's haiku example shows exactly that shape.

The interesting mechanism is what happens when an agent cannot finish alone. Two delegation patterns exist. Agents as tools wraps another agent so it can be invoked like a function, which keeps control in the calling agent. Handoffs transfer the conversation outright, which is the right model when the task genuinely changes owner. The distinction matters in production: with agents as tools, the parent still owns the final response; with a handoff, it does not.

Sessions sit underneath this and manage conversation history across runs automatically, so you are not re-serialising message arrays by hand. Guardrails run as input and output validation, which means a rejected input is caught before the model call rather than after. Tracing records agent runs so you can inspect and debug them, and the README points at a tracing UI screenshot.

Sandbox Agents extend the same run() call with a filesystem workspace. The README's example builds a manifest entry with gitRepo({ repo: 'openai/openai-agents-js' }) and passes a sandbox client in the run options. That is the design: the workspace is declared, not implied, and the client that materialises it is injected. It is a clean separation, and it is also the newest and least settled part of the SDK.

Installing @openai/agents and running your first agent

Installation is a single npm command. The README pairs the SDK with zod, which the acknowledgements credit for schema validation, so install both even if your first agent defines no tools.

npm install @openai/agents zod

Set OPENAI_API_KEY in your server environment. The README states this explicitly for text and sandbox agents, and warns against putting a long-lived key in the browser for realtime work.

The minimal text agent is short enough to paste into a script and run. It defines an Agent with a name and instructions, then calls run() with a prompt.

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

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
});
const result = await run(
  agent,
  'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);

What you should see is the model's text on stdout, read from result.finalOutput. If you get an authentication error instead, the API key is missing from the environment the process actually sees.

For a workspace agent, the import path changes and you must supply a sandbox client. The README uses UnixLocalSandboxClient from @openai/agents/sandbox/local.

import { run } from '@openai/agents';
import { gitRepo, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace Assistant',
  model: 'gpt-5.5',
  instructions: 'Inspect the repo before changing files.',
  defaultManifest: {
    entries: { repo: gitRepo({ repo: 'openai/openai-agents-js' }) },
  },
});

Note the model field is set here and absent from the plain Agent example, and that the client is passed at run time rather than construction time. Both details are easy to get wrong on a first attempt.

Where the SDK is the wrong tool

Sandbox Agents are labelled beta in the README. That is the single most important sentence in the document for anyone planning production work. Beta means the manifest shape, the client interface or the run options can change between minor versions, and the repository's release cadence (three releases inside a week in September 2026, according to the release list) suggests the surface is still moving.

Platform support is the second constraint. UnixLocalSandboxClient is documented as supported on macOS and Linux. On Windows the README directs you to DockerSandboxClient or a hosted sandbox client. If your CI runs Windows runners and you want workspace agents, you are adding a Docker dependency you may not have budgeted for.

Realtime agents come with their own wiring problem. The README's browser example passes an apiKey directly to session.connect(), and the surrounding text tells you not to do that in production: you are supposed to have your server mint a short-lived ephemeral client token and pass that instead. The SDK gives you the hook, not the token service. If you expected the framework to handle browser credential exchange, it does not.

Finally, if your workflow is a single prompt and a single response, none of this earns its keep. Handoffs, sessions, guardrails and tracing are overhead when there is one agent and one turn. A plain API call is the better choice there, and the SDK does not pretend otherwise.

How it compares to the Python Agents SDK and to the Vercel AI SDK

The obvious alternative is the Python Agents SDK from the same organisation. The two share a conceptual vocabulary: agents, handoffs, guardrails, sessions, tracing. The practical difference is the runtime and the ecosystem. Python gives you the data and ML libraries; TypeScript gives you the web stack. If your agent needs to sit inside a Next.js route handler and share types with a React frontend, the JavaScript SDK removes a service boundary that the Python SDK would force you to create. The repository ships examples/nextjs and examples/ai-sdk, which suggests the maintainers expect that deployment shape.

The other comparison is the Vercel AI SDK, which the repository ships an example for (examples/ai-sdk). The approaches differ in where the abstraction sits. The AI SDK is primarily a model-calling and streaming layer with UI hooks; the Agents SDK is an orchestration layer with delegation, validation and trace semantics built in. If your problem is 'stream tokens into a chat component', the AI SDK is closer to the problem. If your problem is 'one agent must decide whether to hand off to a specialist and I need to audit that decision', the Agents SDK is closer.

There is also the option of writing the loop yourself. The SDK's value is concentrated in guardrails, sessions and tracing, which are the three things teams most often implement twice before getting right. If you have already built those, the SDK is a rewrite, not an upgrade.

Maintenance, release cadence and the MIT licence

The repository is not archived, and the last push was on 2026-09-14, the same day as the most recent commit activity reflected in the release list. Releases v0.17.1, v0.17.2 and v0.18.0 all landed within the week before that, which is a fast cadence for a library at version 0.x. Fast cadence cuts both ways: fixes arrive quickly, and so do breaking changes. The 0.x major version is the honest signal here, and the README's beta label on Sandbox Agents confirms it.

Upgrade cost is concentrated in three areas. The sandbox manifest and client interfaces are the most likely to shift. Model names appear as string literals in examples, so a model deprecation becomes a code change. And because the SDK depends on zod for schema validation, a zod major version bump propagates into your tool definitions. Pinning versions in package.json and reading the changelog entries under .changeset before upgrading is the practical posture.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is permissive and standard for a framework of this kind. It says nothing about the OpenAI API terms that govern your actual model calls, which are a separate agreement entirely. This is not legal advice; if the distinction between SDK licence and API terms matters to your organisation, that is a question for counsel.

Editorial conclusion

Adopt it if your stack is TypeScript on Node.js 22 or later and you want handoffs, guardrails, sessions and tracing without assembling them from primitives. Skip it if you need a stable sandbox API today, since the README labels Sandbox Agents beta, or if you run Windows without Docker, because UnixLocalSandboxClient is documented as macOS and Linux only. Before committing, verify the current published version on npm, confirm your Node runtime meets the stated floor, and check whether the hosted sandbox client you intend to use is documented in the sandbox clients guide.

Frequently asked questions

Official sources

1. License: MIT
2. openai/openai-agents-js on GitHub
3. Project website
4. README
5. Releases