跳转到内容

OpenAI Agents SDK TypeScript

OpenAI Agents SDK

使用一小组基本组件构建文本、沙盒和语音智能体。

开始构建
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);

OpenAI Agents SDK for TypeScript 是一个轻量、易用且抽象概念极少的软件包,可用于构建智能体 AI 应用。它是我们早期智能体实验项目 Swarm 的升级版本,可用于生产环境,同时也提供 Python 版本。Agents SDK 仅包含一小组基本组件:

  • 智能体,即配备指令和工具的 LLM
  • 沙盒智能体,将智能体与隔离的文件系统工作区、shell 命令、文件编辑、快照和沙盒会话状态相结合
  • 语音智能体,支持低延迟语音交互,并具备工具、护栏、交接和对话历史记录功能
  • Agents as tools 和交接,允许智能体将特定任务委派给其他智能体
  • 护栏,用于验证智能体的输入

结合 TypeScript,这些基本组件足以表达工具与智能体之间的复杂关系,在智能体需要时为其提供真正的工作区,让您无需经历陡峭的学习曲线即可构建实际应用。此外,SDK 还内置了追踪功能,让您能够可视化、调试和评估智能体流程,甚至为您的应用微调模型。

SDK 的设计遵循两项原则:

  1. 功能足够丰富,值得使用;基本组件足够精简,易于快速掌握。
  2. 开箱即用,同时允许您精确自定义其行为。

以下是 SDK 的主要功能:

  • 智能体循环:内置智能体循环,处理工具调用,将结果返回给 LLM,并持续运行直到任务完成。
  • 沙盒执行:当任务需要工作区时,为智能体提供隔离的文件系统工作区、shell 命令、文件编辑、快照和沙盒会话状态。
  • 语音智能体:构建低延迟语音交互,支持自动打断检测、上下文管理、护栏等功能。
  • TypeScript 优先:使用原生 TypeScript 语言特性编排和串联智能体,无需学习新的抽象概念。
  • Agents as tools 和交接:一种强大的机制,用于在多个智能体之间协调和委派工作。
  • 护栏:在智能体执行的同时并行运行输入验证和安全检查,并在检查未通过时快速失败。
  • 函数工具:将任意 TypeScript 函数转换为工具,支持自动生成模式和基于模式的验证。
  • MCP 服务器工具调用:通过内置集成,将 MCP 服务器的工具与函数工具一同提供给智能体。
  • 会话:持久化记忆层,用于维护智能体循环中的工作上下文。
  • 人工干预:内置机制,支持在智能体运行过程中引入人工参与。
  • 追踪:内置追踪功能,用于可视化、调试和监控工作流,并支持 OpenAI 的评估、微调和蒸馏工具套件。
终端窗口
npm install @openai/agents zod

SDK 需要 Zod v4;通过 npm 安装 zod 将获取最新的 v4 版本。

大多数首次使用的用户只需选择以下其中一个入口:

入门选项适用场景说明
@openai/agents构建大多数文本、沙盒或实时应用。推荐的默认选项。它包含 OpenAI 提供商配置、位于 @openai/agents/sandbox 下的沙盒智能体 API,以及位于 @openai/agents/realtime 下的实时 API。
@openai/agents-realtime仅需要独立的 Realtime 软件包。适用于纯浏览器实时应用,或希望软件包范围更小的场景。
底层软件包(@openai/agents-core、@openai/agents-openai、@openai/agents-extensions)需要更底层的组合、自定义提供商接入或特定集成。大多数新用户在有明确需求之前都可以忽略这些软件包。

对于文本工作流,可以从常规的 Agent 开始。当智能体需要在文件系统中工作,或在较长的任务中保留工作区状态时,请使用沙盒智能体。

使用文本智能体的 Hello World 示例
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);
// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

(运行此代码时,请确保设置 OPENAI_API_KEY 环境变量)

终端窗口
export OPENAI_API_KEY=sk-...

先选择一条路径,完整跑通端到端流程,再回来阅读更深入的指南。

如果您知道自己要完成什么任务,但不确定哪个页面有相关说明,请参考此表。

目标入门指南
构建第一个文本智能体并查看一次完整运行快速开始
添加函数工具、托管工具或 agents as tools工具
为智能体提供隔离的文件系统和 shell 工作区快速入门
在交接与管理者式编排之间做出选择智能体编排
在多轮对话之间保留记忆运行智能体和会话
使用 OpenAI 模型、WebSocket 传输或非 OpenAI 提供商模型
查看输出、运行条目、中断和恢复状态执行结果
构建低延迟语音智能体快速开始