# OpenAI Agents SDK TypeScript

面向开发者的 TypeScript SDK，用于构建文本代理、沙盒工作区代理和实时语音代理，并支持工具调用、代理协作与工作流追踪。

- Findings24: <https://findings24.com/zh-CN/tools/openai-agents-js>
- 网站: <https://openai.github.io/openai-agents-js>
- 价格: Free
- 分类: AI 智能体构建工具, AI 智能体基础设施, AI 软件开发工具包

## 什么是 OpenAI Agents SDK TypeScript？

OpenAI Agents SDK TypeScript 是一款面向开发者的工具包，提供一组精简的基础组件，用于构建代理式 AI 应用。代理将语言模型与指令和工具结合起来，而原生 TypeScript 支持无需单独的工作流语言即可完成编排。

该 SDK 支持文本任务、在隔离文件系统工作区中运行的代理，以及实时语音交互。它将执行、委派、验证和追踪整合到一个工具包中，默认支持 OpenAI 模型，并提供适用于受支持 Vercel AI SDK 模型的适配器。

## OpenAI Agents SDK TypeScript 能做什么？

### 内置代理循环

处理工具调用，将工具结果返回给语言模型，并持续执行直到任务完成。TypeScript 函数可以通过自动生成模式和基于模式的验证转换为工具。

### 沙盒工作区

为需要持久工作环境的任务提供隔离文件系统、Shell 命令、文件编辑、快照和沙盒会话状态。

### 实时语音代理

支持低延迟语音交互，并提供自动中断检测和上下文管理。在浏览器中，RealtimeSession 可通过 WebRTC 连接麦克风输入和音频输出。

### 委派与工具连接

通过将代理作为工具以及交接机制，协调专用代理。内置 MCP 集成可将服务器工具与本地函数工具一同提供。

### 验证与人工参与

与代理执行并行运行输入防护措施，并在检查未通过时快速失败。人在回路机制允许人员参与代理运行的各个环节。

### 追踪与会话记忆

内置追踪功能可将代理工作流可视化、调试并监控。会话会在代理循环中维护工作上下文，而追踪支持 OpenAI 的评估、微调和蒸馏工具。

## 使用场景

### 代码仓库检查与编辑

向工作区助手提供一个 Git 代码仓库，让其使用沙盒文件和 Shell 命令进行检查、总结或修改。快照和会话状态支持跨较长任务持续工作。

### 浏览器应用中的语音助手

构建一个可接受麦克风输入并通过音频回应的助手，同时使用工具并保留对话历史。中断处理支持来回的语音交流。

### 使用专用代理的工作流

使用交接或代理作为工具的调用，将较大任务的一部分分派给具有不同指令和工具的代理，以协调各自的贡献。

## 常见问题

### 如何安装 SDK？

运行 \`npm install @openai/agents zod\`。SDK 要求使用 Zod v4。对于文档中的 OpenAI 文本和沙盒示例，请设置 OPENAI\_API\_KEY 环境变量。

### 应该从哪个软件包开始？

对于大多数文本、沙盒和实时应用，请使用 @openai/agents。如果只需要独立的实时软件包，请选择 @openai/agents-realtime。较底层的软件包支持自定义提供商连接和特定集成。

### 可以使用其他提供商的模型吗？

可以，通过 @openai/agents-extensions 中的 Vercel AI SDK 适配器使用。它支持 AI SDK 提供商规范 v2、v3 和 v4。该适配器处于 beta 阶段；文档建议测试所选提供商，并对 OpenAI 模型使用默认提供商。

### AI SDK 适配器有哪些限制？

它不支持延迟加载 Responses 工具、工具搜索或 Programmatic Tool Calling。PDF 输入可以使用 base64 数据或公开 URL，但需取决于提供商的支持；通过该适配器不支持 OpenAI 文件 ID。

## 快速信息

- **产品类型**: 代理应用 SDK
- **主要语言**: TypeScript
- **默认 OpenAI API**: Responses API 和 Chat Completions API
- **主要 npm 软件包**: @openai/agents
- **文档**: https://openai.github.io/openai-agents-js