openai/openai-agents-js

openai/openai-agents-js

What it does Provides a JavaScript/TypeScript SDK for building multi‑agent workflows that can call LLMs, use tools, enforce safety rules, hand off work between agents, and keep conversation history. It works with OpenAI APIs and is provider‑agnostic.

How it works (core concepts)

• Agent – an LLM configured with instructions, tools, guardrails, and handoffs.
• Sandbox Agent – an agent paired with a filesystem workspace for longer‑running tasks (beta).
• Realtime Agent – low‑latency agent for spoken interactions in the browser.
• Agents as tools / Handoffs – delegate sub‑tasks to other agents.
• Tools – functions, MCP, or hosted tools that let agents take actions.
• Guardrails – configurable safety checks for input and output.
• Human in the loop – built‑in ways to involve people during runs.
• Sessions – automatic conversation‑history management.
• Tracing – tracks each run for debugging and optimization.

Key features

• Text, sandbox, and realtime agent types.
• Tool integration, guardrails, handoffs, sessions, tracing.
• Works in Node.js ≥ 22, Deno, Bun; experimental Cloudflare Workers support.
• Requires @openai/agents and zod for schema validation.

Supported environments

• Node.js 22 or later
• Deno
• Bun
• Experimental: Cloudflare Workers with nodejs_compat enabled

Getting started

npm install @openai/agents zod

Text agent example

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);

Sandbox agent example (macOS/Linux)

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' }) } },
});

const result = await run(
  agent,
  'Inspect the repo README and summarize what this project does.',
  { sandbox: { client: new UnixLocalSandboxClient() } }
);
console.log(result.finalOutput);

Realtime agent example (browser)

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Assistant', instructions: 'You are a helpful assistant.' });
const session = new RealtimeSession(agent);
await session.connect({ apiKey: '<client-api-key>' });

Set OPENAI_API_KEY for text/sandbox agents; for browser realtime agents obtain a short‑lived token from your server.

Limitations (as noted in README)

• Sandbox Agents are in beta; on Windows you must use DockerSandboxClient or a hosted sandbox client.
• Realtime agents require a browser/WebRTC setup.
• Cloudflare Workers support is experimental and needs nodejs_compat.
• No mention of performance benchmarks or production‑ready guarantees beyond the described features.