openai/openai-agents-js

openai/openai-agents-js

What it does 提供一个 JavaScript/TypeScript SDK，用于构建可以调用 LLM、使用工具、执行安全规则、在代理之间交接工作并保持对话历史的多代理工作流程。它与 OpenAI API 兼容，并且是与提供者无关的。

How it works (core concepts)

• Agent – 配有指令、工具、防护栏和交接的 LLM。
• Sandbox Agent – 与文件系统工作区配对的代理，用于较长时间运行的任务（beta）。
• Realtime Agent – 低延迟代理，用于浏览器中的语音交互。
• Agents as tools / Handoffs – 将子任务委托给其他代理。
• Tools – 函数、MCP 或代理可以执行操作的托管工具。
• Guardrails – 可配置的输入和输出安全检查。
• Human in the loop – 内置的在运行过程中让人类参与的方式。
• Sessions – 自动管理对话历史。
• Tracing – 追踪每次运行以进行调试和优化。

Key features

• 文本、沙盒和实时代理类型。
• 工具集成、防护栏、交接、会话、追踪。
• 在 Node.js ≥ 22、Deno、Bun 中运行；Cloudflare Workers 的实验性支持。
• 需要 @openai/agents 和 zod 进行 schema 验证。

Supported environments

• Node.js 22 或更高版本
• Deno
• Bun
• 实验性：已启用 nodejs_compat 的 Cloudflare Workers

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 目前处于 beta 阶段；在 Windows 上必须使用 DockerSandboxClient 或托管的沙盒客户端。
• Realtime agents 需要浏览器/WebRTC 设置。
• Cloudflare Workers 支持是实验性的，并且需要 nodejs_compat。
• README 中未提及性能基准或超出所述功能之外的生产就绪保证。