openai-agents-js: a TypeScript framework for multi-agent workflows and voice agents

What openai-agents-js actually removes from your codebase

Writing an agent loop by hand means owning the same five problems every time: deciding which model call happens next, parsing tool calls out of the response, feeding results back, keeping conversation history across turns, and recording enough to debug a run that went sideways. openai-agents-js takes those over. The README describes it as "a lightweight yet powerful framework for building multi-agent workflows in JavaScript/TypeScript" and lists the pieces it ships: agents, sandbox agents, realtime agents, agents as tools, handoffs, tools, guardrails, human in the loop, sessions and tracing.

The audience is TypeScript teams already calling a model API directly and now needing more than one agent, or needing the same agent to survive more than one turn. The provider-agnostic claim matters here: the README says the SDK supports OpenAI APIs "and more", and the repository carries an examples/model-providers directory, so the abstraction is not welded to a single vendor. If your workflow is one prompt and one response, this package is more machinery than the problem needs.

Agents, handoffs and sessions: the mechanism behind the abstraction

The core object is an Agent: a language model configured with instructions, tools, guardrails and handoffs. Delegation happens two ways. Handoffs transfer control to another agent, while agents as tools let one agent call another as if it were a function. Both are documented as separate guides, which suggests the distinction is deliberate rather than cosmetic: a handoff changes who is speaking, an agent-as-tool returns a result to the caller.

Sessions handle conversation history automatically across runs, so you are not rebuilding a message array on every request. Tracing records what happened during a run so you can inspect and debug the workflow. Guardrails sit on input and output validation, and the human-in-the-loop guide covers pausing a run for a person. Nothing in the README describes the internal scheduling algorithm, so treat the execution order as something to confirm against the guides rather than assume.

The package is a pnpm workspace with a packages directory and a docs site built on Starlight, and the repository acknowledges zod for schema validation. That dependency is not incidental: the install command asks for zod alongside the SDK, so tool argument schemas are validated at the boundary.

Installing openai-agents-js and running a first text agent

The README lists Node.js 22 or later, Deno and Bun as supported environments, with Cloudflare Workers supported experimentally when nodejs_compat is enabled. Install the SDK and zod together:

npm install @openai/agents zod

Set OPENAI_API_KEY in your server environment. The smallest useful program creates an Agent with a name and instructions, then passes it to 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);

This is the README's own example. What you should see is the model's text in result.finalOutput, printed to the console. If the key is missing or the runtime is older than Node 22, expect a failure before any model call is made. The repository also ships an examples/basic directory and a troubleshooting guide on the documentation site, which is where the README sends readers when the first run does not behave.

Sandbox and realtime agents are separate tracks with separate constraints

Sandbox agents pair an agent with a filesystem workspace and a sandbox environment for longer-running work. The README marks them beta and shows a SandboxAgent configured with a defaultManifest that mounts a git repo. The client choice is platform-bound: UnixLocalSandboxClient is supported on macOS and Linux, and the README explicitly directs Windows users to DockerSandboxClient or a hosted sandbox client. That is a real constraint, not a footnote, because it means the simplest local sandbox path is unavailable on one of the three major desktop platforms.

Realtime agents target spoken interaction with low latency. The README's example constructs a RealtimeAgent and a RealtimeSession, then calls session.connect with an API key, and notes that in the browser the session connects the microphone and audio output over WebRTC. The important detail is the credential path: for browser-based realtime agents the README says to use your server to create a short-lived ephemeral client token and pass that to session.connect. A static API key should not be shipped to the browser. That single requirement rules out a purely static frontend deployment.

Where openai-agents-js is the wrong tool

The framework assumes a JavaScript or TypeScript runtime of a recent vintage. Node 22 or later is a hard floor per the README, so teams pinned to an older LTS line cannot adopt it without a runtime upgrade, and Cloudflare Workers support is labelled experimental and depends on nodejs_compat. A team that cannot move its runtime should look elsewhere rather than fight the constraint.

Browser-only realtime is the second mismatch. Because the quickstart routes through a server-issued ephemeral token, an application with no backend cannot complete the documented setup. And the sandbox track is beta with a platform split on the local client, so anyone expecting a uniform local sandbox across macOS, Linux and Windows will not get one from UnixLocalSandboxClient.

There is also a scope question. If your product is a single model call with a fixed prompt, the agent, session, guardrail and tracing layers are overhead. The README does not argue otherwise; it presents these as the framework's core concepts, which implies the intended shape of a project is multi-step and multi-turn.

How it differs from wiring the OpenAI API directly

The direct alternative is calling the OpenAI API from your own TypeScript code, defining your own tool loop and storing your own conversation state. That approach has no framework to learn, no zod peer install, and no opinion about how a handoff should be represented. It also means you write the retry path, the tool-call parser and the trace format yourself, and you own every bug in them.

openai-agents-js trades that control for a documented set of primitives. Sessions replace your message-array bookkeeping. Guardrails replace ad hoc validation around model input and output. Tracing replaces whatever logging you would have added after the first confusing run. Handoffs and agents-as-tools replace a dispatch function you would otherwise design from scratch. The cost is that the shape of your orchestration now follows the SDK's concepts, and the README points to the documentation site for the details rather than reproducing them, so the guides are part of the learning surface. The JavaScript SDK also mirrors an equivalent Python SDK from the same organisation, which matters if your team is split across both languages and wants matching concepts.

Licence, release cadence and what an upgrade costs

The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence and imposes no copyleft obligation on your application. It says nothing about the OpenAI API terms, which govern your use of the model endpoints separately from the SDK code, and nothing here is legal advice.

On maintenance, the last push to the default branch was on 2026-09-14, three days before this writing, and the most recent tagged release is v0.18.0 from 2026-09-10, preceded by v0.17.2 and v0.17.1 on 2026-09-08. The version numbers are still in the 0.x range, so the project has not declared a stable major line. The repository carries a .changeset directory and a CONTRIBUTING.md, which indicates changes are tracked per release, but the README does not document a deprecation policy or a support window for older 0.x versions. Budget for reading the changeset notes before each minor bump, and pin the version in package.json rather than tracking latest.

Editorial conclusion

Adopt openai-agents-js if you are building text, sandbox or realtime agents in TypeScript and want handoffs, guardrails, sessions and tracing handled by the framework rather than by your own loop. Do not adopt it if you need a browser-only deployment with no server, since the realtime quickstart requires a server to mint an ephemeral client token, or if you are on Node below 22. Before committing, verify that your runtime is on the supported list, that your model provider is one the SDK actually reaches, and that you are comfortable with the SDK's tracing defaults, because the README points to the tracing guide rather than spelling out what is sent and where.

Frequently asked questions

Official sources

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