概述

Agents API 现已推出测试版。开发者可以借助它，使用由 OpenAI 管理的 Codex 智能体构建应用。该智能体能够执行多步骤任务，并在同一会话中继续工作。

你的应用负责提供任务、工具和配置。OpenAI 负责管理智能体的会话，以及模型与工具之间的协调。

智能体能做什么？

根据所配备的工具和执行环境，智能体可以运行代码、编辑文件、使用 MCP 连接，以及为你的应用生成文件。你可以在同一会话中发送补充指令，或继续处理其他任务。

有关支持的功能和示例，请参阅 Agents API 概述。

如何开始使用？

1. 在你的 OpenAI 平台项目中创建应用 API 密钥。授予用于会话的 api.agents.read 和 api.agents.write 权限，以及用于模型请求的 api.responses.write 权限。

2. 按照快速入门指南配置智能体、创建会话并提交任务。

3. 跟踪会话事件，查看进度和结果。如果想继续处理任务，请保存会话 ID。

请将 API 密钥存放在智能体的沙箱之外。请求必须包含 OpenAI-Beta: agents=v1 请求头。OpenAI SDK 会自动添加此请求头。

我的智能体需要沙箱吗？

请选择适合任务的环境：

• 无环境：智能体只需回答问题或使用外部工具，无需使用内置 shell 命令或工作区文件。

• OpenAI 托管的沙箱：智能体需要运行脚本或处理文件，且你希望由 OpenAI 管理其沙箱。

• 自托管沙箱：你需要使用自己的基础设施、软件或专用网络。该环境的生命周期由你的应用管理。

有关配置详情，请参阅 Agents API 架构。

在哪里可以查看会话？

打开平台控制台中的日志，选择智能体，然后搜索会话 ID。你可以查看各个轮次、工具调用和子智能体的活动。

可观测性指南还介绍了如何查看已记录的 Token 用量。

事件流断开连接后该怎么办？

重试之前，请先获取现有会话及其已保存的条目。这样可以在提交更多任务之前，确认此前的执行情况。

一个轮次完成，并不意味着所有工具都已执行成功。请查看返回的结果。仅凭会话处于空闲状态，无法确认任务已成功完成。

用量如何计费？

模型请求按所选模型的 API 费率计费。OpenAI 工具和 OpenAI 托管的沙箱分别按适用的工具费率和容器费率计费。

当前费率请参阅 API 定价。

会话数据和文件如何处理？

Agents API 会保留会话状态，让任务能够跨轮次持续进行。不再需要的会话和已发布的产物可以删除。删除会话前，请保存你需要的所有文件。

Agents API 目前仅支持在美国进行数据驻留。它不支持零数据保留，即使使用自托管沙箱也不例外。有关数据控制的详情，请参阅 Agents API 文档。