OpenAI Agents SDK TypeScript
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);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.6-sol', 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);import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Assistant', instructions: 'You are a helpful assistant.',});
// Automatically connects your microphone and audio output in the browser via WebRTC.const session = new RealtimeSession(agent);await session.connect({ apiKey: '<client-api-key>',});OpenAI Agents SDK for TypeScript 是一个轻量、易用且抽象概念极少的软件包,可用于构建智能体 AI 应用。它是我们早期智能体实验项目 Swarm 的升级版本,可用于生产环境,同时也提供 Python 版本。Agents SDK 仅包含一小组基本组件:
- 智能体,即配备指令和工具的 LLM
- 沙盒智能体,将智能体与隔离的文件系统工作区、shell 命令、文件编辑、快照和沙盒会话状态相结合
- 语音智能体,支持低延迟语音交互,并具备工具、护栏、交接和对话历史记录功能
- Agents as tools 和交接,允许智能体将特定任务委派给其他智能体
- 护栏,用于验证智能体的输入
结合 TypeScript,这些基本组件足以表达工具与智能体之间的复杂关系,在智能体需要时为其提供真正的工作区,让您无需经历陡峭的学习曲线即可构建实际应用。此外,SDK 还内置了追踪功能,让您能够可视化、调试和评估智能体流程,甚至为您的应用微调模型。
Agents SDK 的优势
Section titled “Agents SDK 的优势”SDK 的设计遵循两项原则:
- 功能足够丰富,值得使用;基本组件足够精简,易于快速掌握。
- 开箱即用,同时允许您精确自定义其行为。
以下是 SDK 的主要功能:
- 智能体循环:内置智能体循环,处理工具调用,将结果返回给 LLM,并持续运行直到任务完成。
- 沙盒执行:当任务需要工作区时,为智能体提供隔离的文件系统工作区、shell 命令、文件编辑、快照和沙盒会话状态。
- 语音智能体:构建低延迟语音交互,支持自动打断检测、上下文管理、护栏等功能。
- TypeScript 优先:使用原生 TypeScript 语言特性编排和串联智能体,无需学习新的抽象概念。
- Agents as tools 和交接:一种强大的机制,用于在多个智能体之间协调和委派工作。
- 护栏:在智能体执行的同时并行运行输入验证和安全检查,并在检查未通过时快速失败。
- 函数工具:将任意 TypeScript 函数转换为工具,支持自动生成模式和基于模式的验证。
- MCP 服务器工具调用:通过内置集成,将 MCP 服务器的工具与函数工具一同提供给智能体。
- 会话:持久化记忆层,用于维护智能体循环中的工作上下文。
- 人工干预:内置机制,支持在智能体运行过程中引入人工参与。
- 追踪:内置追踪功能,用于可视化、调试和监控工作流,并支持 OpenAI 的评估、微调和蒸馏工具套件。
npm install @openai/agents zodSDK 需要 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) | 需要更底层的组合、自定义提供商接入或特定集成。 | 大多数新用户在有明确需求之前都可以忽略这些软件包。 |
Hello world 代码示例
Section titled “Hello world 代码示例”对于文本工作流,可以从常规的 Agent 开始。当智能体需要在文件系统中工作,或在较长的任务中保留工作区状态时,请使用沙盒智能体。
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.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.6-sol', 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);(运行此代码时,请确保设置 OPENAI_API_KEY 环境变量)
export OPENAI_API_KEY=sk-...先选择一条路径,完整跑通端到端流程,再回来阅读更深入的指南。
快速开始 构建您的第一个文本智能体,并了解 SDK 的核心工作流。
快速入门 当智能体需要文件、shell 命令、补丁或可恢复的沙盒状态时,从沙盒智能体开始。
快速开始 构建语音交互时,从语音智能体开始。
如果您知道自己要完成什么任务,但不确定哪个页面有相关说明,请参考此表。
| 目标 | 入门指南 |
|---|---|
| 构建第一个文本智能体并查看一次完整运行 | 快速开始 |
| 添加函数工具、托管工具或 agents as tools | 工具 |
| 为智能体提供隔离的文件系统和 shell 工作区 | 快速入门 |
| 在交接与管理者式编排之间做出选择 | 智能体编排 |
| 在多轮对话之间保留记忆 | 运行智能体和会话 |
| 使用 OpenAI 模型、WebSocket 传输或非 OpenAI 提供商 | 模型 |
| 查看输出、运行条目、中断和恢复状态 | 执行结果 |
| 构建低延迟语音智能体 | 快速开始 |