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 中未提及效能基準或超出所述功能之外的生產就緒保證。