Agents SDK | OpenAI API
来源: https://developers.openai.com/api/docs/guides/agents 抓取时间: 2026-07-21 16:18:50
Agent 是能够进行规划、调用工具、跨专业 Agent 协作，并保持足够状态以完成多步骤工作的应用程序。
让您的第一个 Agent 运行起来
从 Agents SDK 快速入门 开始，安装 SDK、定义一个 Agent 并运行它。一旦成功，回到这里选择您的应用程序需要的下一个功能。
获取 Agents SDK
使用 GitHub 仓库获取更多示例、问题和特定语言的参考详情。 TypeScript SDK 在 GitHub 上打开 TypeScript SDK 仓库。 Python SDK 在 GitHub 上打开 Python SDK 仓库。
选择您的起点
| 如果您想要 | 从这里开始 | 原因 |
|---|---|---|
| 构建代码优先的 Agent 应用 | 快速入门 | 这是实现 SDK 集成工作的最短路径。 |
| 清晰地定义一个专业 Agent | Agent 定义 | 当您仍在为单个 Agent 制定规范时从这里开始。 |
| 选择模型、默认值和传输方式 | 模型和提供商 | 当模型选择、提供商设置或传输策略影响工作流时使用此选项。 |
| 了解运行时循环和状态 | 运行 Agent | 这里包含 Agent 循环、流式传输和延续策略。 |
| 在基于容器的环境中运行工作 | 沙箱 Agent | 当 Agent 需要文件、命令、包、快照、挂载或提供商链接时使用此选项。 |
| 设计专业 Agent 所有权 | 编排和交接 | 当您需要多个 Agent 且必须决定谁拥有回复时使用此选项。 |
| 添加验证或人工审核 | 防护措施和人工审核 | 当工作流应该在危险工作继续之前阻止或暂停时使用此选项。 |
| 了解运行返回什么 | 结果和状态 | 本页解释最终输出、可恢复状态和下一轮表面。 |
| 添加托管工具、函数工具或 MCP | 使用工具 和 集成和可观测性 | 工具语义在平台工具文档中；SDK 特定的 MCP 和追踪在这里。 |
| 检查和改进运行 | 集成和可观测性 和 评估 Agent 工作流 | 首先使用追踪进行调试，然后进入评估循环。 |
| 构建语音优先的工作流 | 语音 Agent | 使用 SDK 的语音管道和实时 Agent 模式。 |
使用 SDK 构建
当您的服务器负责部署、工具实现、状态存储和审批决策，而 SDK 运行 Agent 循环并调用这些工具时，请使用 SDK 路径。当您想要以下内容时，此路径是最佳选择：
- TypeScript 或 Python 中的类型化应用代码
- 对工具、MCP 服务器和运行时行为的直接控制
- 自定义存储或服务器管理的对话策略
- 与现有产品逻辑或基础设施的紧密集成
典型的 SDK 阅读顺序是：
- 从 快速入门 开始，在屏幕上获得一次有效运行。
- 使用 Agent 定义 和 模型和提供商 清晰地塑造一个专业 Agent。
- 随着工作流变得更加复杂，继续阅读 运行 Agent、编排和交接 和 防护措施和人工审核。
- 当应用逻辑依赖于运行对象或更深入的行为可见性时，使用 结果和状态 和 集成和可观测性。
Agents SDK 与 Responses API 对比
当您希望拥有循环时使用 Responses API。当您希望 SDK 运行它时使用 Agents SDK。
在以下情况下选择 Responses API
- 您希望直接控制模型交互、输出项、工具、状态和编排，无论工作流需要一次调用还是多次调用。
- 您希望直接在应用程序中实现自定义工具路由、循环或分支。
在 Responses 函数调用流程 中，您的应用程序接收函数调用、执行它们、返回它们的输出，然后再次调用模型。 例如，Responses API 工作流可能会搜索知识库并生成带引用的答案。
在以下情况下选择 Agents SDK
- 您希望 SDK 管理 Agent 循环和重复编排，如重复的工具调用或分支。
- 不同的专业 Agent 需要不同的指令、工具或策略。
- 您想要内置的会话、追踪、防护措施或可恢复的审批流程。
Agents SDK 运行器 执行工具循环，在交接后切换 Agent，并在运行完成或因审批暂停时停止。 例如，Agents SDK 工作流可能会调查支持请求、将其交给正确的专业 Agent、调用内部系统、请求退款审批并记录结果。
比较 Responses API 和 Agents SDK
| | Responses API| Agents SDK
---|---|---|---
最适合| 自定义模型驱动的功能和工作流| 具有定义工具和重复编排模式的有界对话或事务性工作流
核心抽象| 模型响应| Agent 运行
工具| 平台工具、函数调用和远程 Model Context Protocol (MCP)| 附加到可重用 Agent 的平台工具，加上工具包装器、本地 MCP 连接和 Agent 即工具
工作流编排| 您管理自定义循环和分支| SDK 提供 Agent 循环和生命周期
多 Agent 工作流| 自己构建路由和委托| 内置的 Agent 即工具和 交接
状态| 手动历史记录、响应链或 对话| 相同选项，加上 SDK 会话和可恢复运行状态
安全和审批| 工具特定的审批；您构建更广泛的控制| 输入、输出和工具 防护措施加上可恢复的审批流程
调试和追踪| 响应对象和 API 日志| 内置追踪 跨模型调用、工具、Agent、防护措施和交接