摘要： 本文完整演示如何使用 OpenAI Agents API，在一次 POST /v1/agents/sessions 调用中同时定义 Agent、启动 OpenAI 托管的 Codex Harness、创建隔离 Sandbox、提交首个编码任务并流式接收执行事件。核心结论是：这套接口把“模型推理＋命令执行＋文件工作区＋会话状态＋产物下载”组合成了可编程 Cloud Agent，但任务仍是异步执行，生产环境必须保存 Session/Turn ID、处理断线恢复、限制网络和凭据权限，并对发布、删除、合并等高风险动作保留人工审批。本文适合开发者、自动化团队和希望把 Codex 能力接入 n8n、WordPress、CI 或企业系统的读者。
核心结论
OpenAI Agents API 可以用一次创建 Session 的 API 请求启动 Cloud Agent：请求体同时包含 agent、environment、input 和 stream，OpenAI 负责运行托管的 Codex Harness、配置 openai_hosted Sandbox，并让 Agent 在其中写文件、运行命令和返回结果。但“一次 API 调用启动”不等于“一次同步调用立刻拿到最终文件”；Turn 是异步工作单元，应用需要消费事件流或接收 Webhook，并在完成后下载 Artifact。
- 值得使用： 适合需要真实执行代码、生成文件、验证结果和持续对话的 Agent 应用，而不只是生成一段文本。
- 最小调用：
POST /v1/agents/sessions中放入模型、指令、托管环境、任务和stream: true，即可创建 Session 并启动首个 Turn。 - 关键区别： Codex Harness 是围绕模型的执行与编排层；Sandbox 是隔离计算环境；Session 是持久会话；Turn 是一次异步工作周期。
- 成本组成： 模型 Token、所启用工具以及托管容器分别计费；官方没有把它们合成一个固定的“Cloud Agent 单次价”。
- 生产建议： 默认关闭网络或采用域名白名单，API Key 留在应用侧，产物统一写入
/workspace/outputs，高风险动作增加独立审批。
如果你正在搭建 AI 编程或自动化系统，可以同时参考 AI Stack Nav 的 Codex 教程检索页 与 Agent API 实战内容，把本文示例扩展为 WordPress 修复、n8n 节点开发或 CI 故障调查流程。
背景与主要变化
传统模型 API 的中心对象是“请求与响应”：应用发送提示词，模型返回文字或工具调用意图。真正的 Coding Agent 还需要工作目录、Shell、依赖安装、文件修改、任务状态、断线恢复和产物保存。若团队自行拼装这些能力，往往还要部署队列、容器平台、事件总线、对象存储和权限代理。
Agents API 把这些能力提升为一等对象。官方定义了四个核心概念：Agent、Environment、Session、Events/Items。对于 OpenAI 托管环境，应用只负责创建任务和接收事件，OpenAI 运行 managed Codex harness，并管理 Agent 使用的 Sandbox。
| 概念 | 负责什么 | 本文中的例子 | 不能替代什么 |
|---|---|---|---|
| Agent | 模型、指令、工具、MCP 与行为设置 | gpt-6-astra＋编码验收指令 | 不是独立虚拟机 |
| Codex Harness | 规划、工具循环、命令执行协调、上下文管理 | 写脚本、运行测试、汇报证据 | 不是业务权限系统 |
| Environment | 文件、进程、包和网络所在环境 | openai_hosted Sandbox | 不是长期对象存储 |
| Session | 保存配置、对话和工作状态 | 一个仓库修复会话 | 不等于单次请求 |
| Turn | Session 中一轮异步工作 | “修复 Bug 并运行测试” | 不保证所有工具都成功 |
| Event/Item | 过程状态与保存的输入输出 | 创建、命令、消息、完成事件 | 不应只靠控制台打印保存 |
| Artifact | Turn 完成后发布的不可变输出 | ZIP、报告、补丁文件 | 不等于 Sandbox 内任意文件 |
标题中的“一次 API 调用”准确指创建 Session 时可一起发送初始 input。它会启动第一轮工作，并可通过同一连接流式返回事件。之后若要继续修改、补充要求或纠偏，应复用 session_id，而不是每次新建 Session。
当前接口位于 SDK 的 beta.agents 命名空间；直接使用 cURL 时还需要 OpenAI-Beta: agents=v1。因此生产代码应锁定 SDK 版本、记录接口版本，并预留字段变化的兼容测试。
Codex Harness 到底提供了什么
Codex Harness 不是单一模型别名，而是围绕模型建立的执行契约和运行循环。根据官方 Agents API 概览，托管 Harness 可以运行命令和代码、应用 Skills 与指令、通过工具或 MCP 连接外部数据、接受运行中 Steering、压缩上下文、把独立工作委派给 Subagents，并恢复已有 Session。
一个典型编码任务会经历以下循环：
- 读取任务、指令和可用能力。
- 检查工作区文件及约束。
- 制定或更新执行步骤。
- 调用 Shell、文件编辑或外部工具。
- 运行测试并读取真实输出。
- 根据失败证据继续修复。
- 把需要保留的文件写入
/workspace/outputs。 - 生成结果消息并结束 Turn。
这比“让模型返回一段建议代码”更接近真实工程交付，因为结果可以经过运行验证。但 Harness 仍然可能误判、遗漏测试或执行不合适的命令。企业必须用 Sandbox、工具白名单、分支保护和独立验收层约束它。
调用前准备：权限、SDK 与任务边界
登录后阅读全文
以下为核心实操内容。登录或免费注册后，即可查看完整步骤、参数配置、提示词和报错解决方案。
事实依据与来源
本文关于 Agent、Environment、Session、Events/Items 四个核心概念，以及托管 Codex Harness 支持命令执行、Skills、MCP、Steering、上下文管理、Subagents 与恢复能力的描述，来自 OpenAI Agents API 官方概览。
本文关于一次 sessions.create 同时创建 Session、提交首个任务和流式接收事件，所需 api.agents.read、api.agents.write、api.responses.write 权限，以及 OpenAI-Beta: agents=v1 Header 的说明，来自官方 Quickstart 与 Sessions 文档。
本文关于网络 enabled、disabled、restricted、精确域名白名单、Workspace、/workspace/outputs、一小时失活可能到期、关闭流不会取消任务，以及 Artifact 和文件限额的内容，来自 OpenAI-hosted Sandbox 与 Files and Artifacts 官方文档。
文中的 WordPress 插件调查流程、幂等状态机、独立 CI、人工审批与成本指标属于实施建议，不代表 OpenAI 官方承诺。代码按官方 Python SDK 示例结构整理，但未使用用户的真实 API Key 发起计费测试；具体 SDK 版本、账户资格、Rate Limit、价格和地区可用性仍应以控制台及官方页面为准。
本文没有采用第三方 Benchmark，也未宣称固定性能提升比例。
内容核验日期：2026 年 09 月 14 日
FAQ
Agents API 和 Assistants API 是同一个接口吗？
不是。本文使用的是新的 Agents API，其核心对象包括 Agent、Environment、Session、Turn 与 Artifact，示例路径为 /v1/agents/sessions。不要把旧 Assistants API 的 Thread、Run 示例直接套用到本文代码；迁移时应按官方最新指南逐字段核对。
“一次 API 调用启动 Cloud Agent”是否意味着最终结果同步返回？
不是。一次创建请求可以同时启动 Session 和首个 Turn，并通过流返回过程事件；但 Turn 本质上异步运行。客户端断线、长时间执行和人工审批都要求应用保存 ID，并使用事件、Items 或 Webhook追踪最终状态。
必须使用 GPT-6 Astra 吗？
官方当前 Quickstart 以 gpt-6-astra 演示托管编码任务，因此本文沿用该模型 ID。其他模型能否用于某项 Agents API 能力，应以创建 Session 时的模型可用性和官方模型目录为准，不能只凭模型支持普通 Responses API 就推定它支持全部 Harness 能力。
Agents API 是否免费？
不能把它视为免费功能。官方说明模型、OpenAI 工具和 OpenAI-hosted Sandbox 分别按对应标准费率计费。具体价格、赠送额度与项目限额以 OpenAI Platform 的 Price 页面和控制台为准。
API Key 应该放进 Cloud Sandbox 吗？
不应该。官方 Quickstart明确要求把应用 API Key 保留在 Sandbox 外。需要访问外部系统时，应通过最小权限、短期、可撤销的凭据或受控工具代理，不要把组织级长期密钥放进输入文件或提示词。
如何让 Agent 访问互联网？
在 openai_hosted 环境的 network 中选择 enabled 或 restricted。生产环境优先使用 restricted 并列出精确域名；若不需要联网，则显式设置 disabled。只在提示词中写“请上网”不会替代网络策略和工具配置。
Sandbox 中生成的文件会永久保存吗？
不会把整个 Sandbox 当作永久磁盘。Workspace 文件只在 Sandbox 存在期间跨 Turn 保留；写入 /workspace/outputs 并在 Turn 完成时发布的 Artifact 可以在 Sandbox 到期后下载。删除 Session 前仍应把关键文件保存到自己的长期存储。
关闭流式连接会取消任务吗？
不会。官方明确说明关闭 Event Stream 不会取消正在运行的任务。应用应保存 Session ID，断线后查询已有状态；否则重新提交可能造成重复执行和额外费用。
可以让 Cloud Agent 直接发布 WordPress 或合并 PR 吗？
技术上可以通过工具或外部连接赋予能力，但不建议让同一 Agent 完成“编写、批准、发布”闭环。更安全的方案是 Agent 生成补丁和报告，独立 CI 验证，人类或独立审批身份确认后再发布。
什么时候应选 Self-hosted Sandbox？
当任务必须访问企业内网、使用特定镜像或硬件、遵守数据驻留要求，或者组织希望自行控制执行隔离时可评估 Self-hosted。代价是团队要自行负责环境生命周期、网络安全、资源调度、监控与受限 Executor Key 管理。
参考来源
- OpenAI Agents API Overview
- OpenAI Agents API Quickstart
- OpenAI Run and Continue Sessions
- OpenAI-hosted Sandboxes
- OpenAI Sandbox Security
- OpenAI Files and Artifacts
- OpenAI Session Webhooks
工具选型与提示词资料
适合阅读工具评测、工具推荐、对比测评类文章后继续转化。
