OpenAI Agents JS

OpenAI 官方发布的轻量级多智能体工作流与语音代理框架，支持 TypeScript 与 Node.js，提供 Agent 编排、Handoffs、Guardrails、工具集成、结构化输出及内置 Tracing。

项目概述#

OpenAI Agents SDK (JavaScript/TypeScript) 是 OpenAI 官方推出的轻量级、强大的多智能体工作流与语音代理框架。项目旨在解决多智能体协作、工具调用编排、输入输出安全校验以及语音交互集成等核心工程挑战。

核心特性#

智能体能力#

Agents: 可配置指令、工具、Handoffs 和 Guardrails 的 LLM 实体
Handoffs: 在代理之间动态移交控制的专用工具调用机制
Parallelization: 并行执行多个代理或工具并汇总结果

安全与合规#

Guardrails: 输入/输出可配置的安全与校验检查，并行于代理执行
Human-in-the-Loop: 内置在流程中引入人工审批或介入的机制

工具与扩展#

Tool Integration: 将函数转为工具（基于 Zod 的参数校验与自动 schema 生成）
MCP 支持: 集成 MCP 服务器工具
Model Flexibility: 通过 Vercel AI SDK 适配器支持非 OpenAI 模型
Long-running Functions: 支持挂起与恢复的长时运行函数

数据处理#

Structured Output: 支持纯文本与基于 schema 的结构化输出
Streaming: 实时流式输出与事件推送

语音能力#

Realtime Voice Agents: 通过 WebRTC 或 WebSocket 构建实时语音代理
Voice Pipeline: 通过 STT/TTS 将文本代理链接为语音代理

可观测性#

Tracing: 内置运行追踪，用于可视化、调试与优化

技术架构#

模块结构#

项目采用 Monorepo 结构（pnpm workspace）：

packages/agents: 主包 @openai/agents，聚合核心功能
packages/agents-core: 核心逻辑与抽象定义
packages/agents-openai: OpenAI API 集成层
packages/agents-realtime: 实时语音代理能力
packages/agents-extensions: 扩展模块

运行环境#

Node.js ≥22、Deno、Bun
实验性支持 Cloudflare Workers（需启用 nodejs_compat）
提供面向浏览器的独立优化包

依赖#

主包名: @openai/agents
当前版本: v0.5.1
对等依赖: zod ^4.0.0
许可证: MIT

核心机制#

Agent Loop（代理循环）#

调用 run() 启动循环
若响应包含 handoff，切换到目标代理继续循环
若有工具调用，执行工具并将结果追加到消息历史继续循环
可通过 maxTurns 限制最大轮次

最终输出判定#

结构化模式（有 outputType）: 必须返回匹配 Schema 的数据
文本模式（无 outputType）: 首次产生不含工具调用或 Handoff 的消息即为结束

Guardrails 执行#

输入校验与代理逻辑并行执行，触发违规时抛出 GuardrailTripwireTriggered 异常

快速开始#

# 安装
npm install @openai/agents zod

# 环境变量
export OPENAI_API_KEY=sk-...

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

适用场景#

多智能体编排与协作系统
工具调用型工作流（如天气查询、Web 搜索、文件搜索）
需要输入/输出安全校验与合规护栏的生产应用
实时语音代理（浏览器或服务器端）
人工审批/介入流程（高风险操作需人工确认）
复杂流程的可观测与调试