OpenAI Agents API 怎么用？

官方资料（2026-11-02 核对）：Agents API Quickstart · Architecture · Sessions · OpenAI-hosted Sandbox · Sandbox Security · Files 与 Artifacts · Errors 与 Recovery · Observability 与 Usage

先判断是否真的需要 Agents API

Agents API 不是 ChatGPT 订阅权益，也不是 Agents SDK 的“付费升级”。模型、托管容器和第三方工具可能分别计费，上线前要按官方实时价格与实际任务链路估算。

准备 API Key、Scope 与 Beta 头

1. 在 OpenAI Platform 项目创建应用 API Key。
2. 授予 api.agents.read、api.agents.write 和 api.responses.write。
3. JavaScript 安装 npm install openai；Python 安装或升级 pip install --upgrade openai。
4. SDK 使用 beta.agents 命名空间并自动发送 Beta 头；cURL 需显式发送 OpenAI-Beta: agents=v1。
5. 应用 API Key 只留在服务端，不放进 Sandbox、浏览器、仓库、日志或提示词。

最小 JavaScript Session

import OpenAI from "openai";

const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
  agent: {
    model: process.env.OPENAI_MODEL,
    instructions: "完成任务，报告实际执行结果。"
  },
  environment: {
    type: "openai_hosted",
    network: { access: "disabled" }
  },
  input: "创建一个文本报告并保存到 /workspace/outputs/report.txt",
  stream: true
});

events.withResultCollection();
try {
  for await (const event of events) {
    console.log(event.type);
  }
  const result = await events.finalResult();
  console.log(result.session_id, result.output_text);
} finally {
  events.controller.abort();
}

示例用环境变量管理模型，避免把某个型号当成永久默认值。真实项目还要保存 session_id，对失败、取消和 required actions 分支做处理，并下载需要保留的 Artifact。

三种环境怎么选

托管 Sandbox 的工作目录是 /workspace；可配置 packages、files、setup_commands、env、container_size 与 network。默认网络策略可能受模板影响，生产上应显式选择 disabled 或只允许必要域名的 restricted。

Session 的正确生命周期

1. Create：创建 Session，同时提供 Agent、初始输入与环境。
2. Stream：持续接收事件，保存 Session 与 Turn 标识。
3. Outcome：检查 agent.session.turn.completed、failed 或 cancelled；idle 本身不是成功。
4. Required actions：如 Session 等待函数结果或环境连接，读取并完成 required_actions。
5. Inspect：读取 Session Items 和工具输出；Turn completed 也不保证所有工具成功。
6. Continue：先打开事件流，再用保存的 session_id 发送后续消息。
7. Delete：保存结果和文件后删除 Session，请求清理 Sandbox。

每次逻辑消息提交都生成一个幂等键并与消息一起保存。网络超时后重试同一提交时，复用原 session_id、消息和幂等键。

文件、Artifact 与 Sandbox 生命周期

• 输入文件可在创建 Session 时用 Files API ID 或 inline base64 提供到 /workspace。
• 把要保留的输出写进 /workspace/outputs；Turn 完成后会发布为不可变 Artifact。
• 自托管环境的文件通过你的提供方 API 或挂载文件系统读取，不会进入 OpenAI Artifacts API。
• Session 工作区可跨 Turn 使用，但不是永久存储；活动和 keep-alive 停止后，托管 Sandbox 可能被删除。
• 删除 Session 前下载或转存业务必须保留的文件；关闭事件流不会自动取消任务。

上传失败时读取 error.param 与 error.message。路径必须是 /workspace 下的绝对 POSIX 路径，并防止符号链接穿越、覆盖与超长路径。

安全：把密钥与业务授权留在 Sandbox 外

• 不同用户或敏感工作负载使用隔离环境，避免共享文件与状态。
• 应用 API Key 只在应用服务器；自托管 Executor 使用受限的 CODEX_API_KEY 连接环境。
• 第三方凭据放在 Vault、可信代理或函数工具处理器，不直接注入生成代码可读取的环境。
• 远程 MCP、函数工具和网络访问分别做域名允许列表、参数校验、身份授权、幂等与审计。
• 付款、删除、发布、外发数据和高影响命令必须有人审或等价政策控制；提示词不能替代执行边界授权。

错误恢复：先查状态，再重试

失败 Turn 可能已经写文件或调用外部服务。自动恢复必须先确认副作用；错误类型变化、超过重试上限或 Session 已 failed 时停止自动重试。

观测、成本与真实验收

在 Platform Agents 日志按 Session ID 查看 Turn、工具调用和子 Agent；同时保留业务侧的用户请求、审批、幂等键、外部结果与最终 UI 状态。Session / Turn usage 是 best-effort，可能暂时为 null，不能把 null 当作零费用或最终账单。

• 按“完成一个真实任务”统计模型多次调用、重试、子 Agent、工具、Sandbox 计算和第三方费用。
• 监控完成率、失败/取消率、required actions 等待、工具错误、平均 Turn 数、Artifact 下载与清理成功率。
• 对输入、工具、外发网络、凭据和日志做脱敏与租户隔离。
• 用固定评测集验证成功标准，不能只看 turn.completed。

生产上线检查清单

• 从一个 Session 和最小只读任务开始，模型与 SDK 版本通过配置和锁文件管理。
• API Key Scope 最小化；应用 Key 与第三方凭据不进入 Sandbox。
• 环境类型、包、文件、setup、网络和容器大小都显式配置并经过测试。
• 事件终态、required actions、幂等键、断流重连和人工接管都有分支。
• 文件路径、Artifact 保存、Session 删除和过期恢复已测试。
• 重试前检查副作用，设置截止时间、次数上限和人工接管。
• 日志、Trace、业务指标、费用告警与数据保留规则已启用。
• 正式验收同时检查输出、工具结果、业务状态、费用和用户界面。

常见问题

本文核对日期为 2026-11-02。Agents API 当前是 Beta，Header、SDK 命名空间、Session、环境、事件、限制与计费都可能变化；发布前请重新读取 Quickstart、Sessions、Sandbox、Security、Errors 与 Observability 官方文档。