Agents API 的核心定位与架构分工

OpenAI 近期发布了处于公开测试阶段的 Agents API，旨在将 Codex 背后的 Agent Harness、Session 托管沙箱以及 Skills（技能）等核心能力以 API 的形式开放给开发者。这一接口的目标场景非常明确：让 AI 模型真正接手那些需要持续推进的复杂任务。开发者只需提交目标与运行配置，Agent 即可在 Session（会话）中调用工具、执行命令、处理文件并生成产物，同时将整个工作过程持续反馈给应用。OpenAI 负责托管的是 Agent 持续工作的运行层，包括模型与工具之间的循环交互、上下文管理、Session 生命周期维护以及事件记录和任务恢复机制。

在这种架构下，执行环境的选择权完全掌握在开发者手中。Agent 既可以使用 OpenAI 托管的沙箱，也可以接入开发者自有的沙箱或企业基础设施。工具、MCP 服务、Skills、业务数据以及网络权限和安全策略，均由开发者提供并掌控。这种设计使得 Agents API 成为一套可组合的 Agent 基础设施。OpenAI 维护通用的 Harness，而开发者将执行环境和业务能力接入其中，共同组成面向产品的 Agent。这种分工带来的直接变化是：开发团队可以减少维护通用 Agent loop 的工作，将更多精力集中在任务设计、权限安全和业务能力上。同时，Session、事件流以及作为执行产物的 Artifacts（产物），为产品提供了稳定的接入对象，使得长任务的可观察性、可恢复性和结果交付变得更加容易。

“OpenAI 负责维护通用的 Harness，开发者呢把自己的执行环境和业务能力接进来，共同组成真正面向产品的 Agent。”

托管 Harness：从单次生成到持续执行循环

Agents API 最重要的组成部分，是 OpenAI 将 Codex 背后的 Agent Harness 作为托管能力开放出来。Harness 可以理解为模型之外的 Agent 运行层，它负责组织模型的调用和工具的交互：将工具结果送回模型、管理长任务中的上下文（在需要时压缩历史）、协调子代理，并维护 Session 从创建、执行到等待再到继续的整个生命周期。这些能力共同构成了一个 Agent loop（智能体循环）。

在这个循环中，模型负责判断下一步做什么，而 Harness 负责让这个判断连续地转化为行动。它发起工具调用、记录结果、更新上下文，并妥善处理失败后进入下一轮迭代。OpenAI 在服务端运行并更新这一层逻辑，开发者可以直接使用与 Codex 一起演进的执行逻辑。Session、Turn（回合）和 Items 是这一运行层对外暴露的核心对象。它们让应用能够跟进一个持续运行的任务，而不是只能等待一次模型生成的结束。

Session 是持续存在的任务容器；Turn 是其中的一次推进或迭代；Items 则是推进过程中产生的消息、命令、工具结果和最终输出。应用既可以实时消费这些事件，也可以在之后重新读取 Session 的状态。对于需要执行几十秒甚至更久的任务，这种结构比只等待一段最终的文本更容易观察、恢复和接入到产品界面中。

“Harness可以理解为模型之外的Agent运行层，它组织模型调用和工具调用，把工具结果送回模型……协调 subagent 并维护Session从创建执行到等待到继续的整个生命周期。”

执行环境选择：OpenAI 托管沙箱 vs 自定义基础设施

在 Agents API 中，执行环境被保留为可选择边界。最直接的选择是使用 OpenAI hosted sandbox（托管沙箱）。由 OpenAI 负责创建和连接 Linux 工作区，开发者配置网络权限、环境变量、依赖包以及输入文件。这种方式适合快速启动，也是本期演示采用的方式。

当然，任务也可以运行在开发者自己的基础设施中。自托管环境可以连接企业 VPC、自定义镜像、内部数据、密钥系统和特殊的硬件资源。此外，开发者还可以选择第三方合作伙伴提供的计算环境，根据启动需求在 CPU、GPU、内存等硬件资源、地理区域以及价格方面做出取舍。这部分内容将在未来的演示中详细介绍。

无论执行环境如何变化，工具、MCP 服务、Skills、业务知识和工作流继续由开发者提供。他们决定 Agent 能够访问哪些系统、遵守什么规则以及最终怎样进入真实的产品。模型 + 托管 Harness + 可选执行环境 + 开发者能力层，共同组成了完整的 Agent。这种架构确保了灵活性：既利用了 OpenAI 在通用执行逻辑上的优势，又保留了开发者对数据安全和业务逻辑的绝对控制权。

“任务也可以运行在开发者自己的基础设施里，自托管环境可以连接企业 VPC、自定义镜像、内部数据、密钥系统和特殊的硬件资源。”

实战演示一：基础任务流程与 Artifact 交付

为了具体理解 Agents API，我们首先通过一个真实的 curl 请求来演示基础流程。API 入口为 /v1/agents/sessions，请求头需包含 API Key、Beta 标记 agents=v1 以及 JSON Content-Type。请求体中指定模型、执行环境（使用 openai_hosted 并关闭网络访问）、输入文件以及任务指令，同时开启流式返回（stream=true）。

本次演示的任务非常简单：读取工作区内的 amounts.csv 文件，检查 amount 列，计算行数和总额，并将结果写入 workspace/outputs/summary.json。输入文件以内联形式（inline）通过 base64 编码放入请求体，Agent 启动后看到的是普通 CSV。服务端返回 HTTP201 并创建 Session，后续所有命令执行、工具结果和最终回答都属于该 Session。

由于开启了流式返回，服务端持续发送 SSE 事件。记录显示：首先是 agent.session.created（Session创建），随后是 turn.started（任务开始）。Agent 每产生一项工作都会触发 item 事件，例如命令先以 command_execution 加入，再携带状态和输出完成。任务完成后生成 artifact，并与 Turn 关联。

在沙箱内部，Agent 首先执行 pwd 确认目录，再用 cat 查看 amounts.csv（包含 Alpha:10, Beta:20, Gamma:30 三行数据）。接着，Agent 使用 Python（利用沙箱自带的解释器）读取 CSV：第一步用 DictReader 读取，第二步将 amount 转为整数求和（总额60），第三步创建 outputs 目录并写入 JSON。最后通过 cat 命令读取结果进行校验，确认 rows、total 和 verified 字段符合要求。这些操作均属于 Session 的工作记录。

“因为请求里设置了 stream=true，服务端会持续地返回SSE事件……应用既可以实时的消费这些事件也可以在之后重新读取Session的状态。”

实战演示二：Skill（技能）的加载与复用

第二次请求我们在同一 CSV 任务中引入了 Skill。我们创建了一个名为 csv-report 的 Skill，其中包含真实的 SKILL.md 文件。该文件规定了详细的校验步骤和输出格式：既要生成 JSON，也要生成 Markdown 报告，并在结果中标记实际使用的 Skill 名称。

SKILL.md 的具体要求包括：确认 amount 只出现一次、检查每个值都是数字、用 Python 计算、写入 JSON、生成 Markdown 报告，最后读取两个文件进行验证。这些要求成为 Agent 在执行环境中可读取的任务方法。

在请求体中，我们通过 skills 数组上传该 Skill。使用 inline 类型，名称为 csv-report，ZIP 内容经过 base64 编码放入 source。请求体保留了相同的 amounts.csv，但在 environment 下增加了 skills 配置，并在 input 中明确要求使用 csv-report Skill。这样可以用同一份输入对比：无 Skill 时仅生成基础 JSON，加载 Skill 后则生成更完整的 JSON 和 Markdown 报告。

提交请求后，服务端返回 HTTP201。执行记录显示 Agent 读取了 SKILL.md 并按其方法处理数据。证据确凿： 1. Session 环境信息中包含 csv-report。 2. 托管环境中出现 .managed-agents/skills/csv-report 路径。 3. 事件流记录 Agent 读取 SKILL.md 并验证字段、生成两种格式。 4. 最终 JSON 中出现 skill_used: csv-report，Markdown 报告也遵循了 Skill 规定的结构。

“Skills则把一套可复用的方法和输出规范一起装进了执行环境……Agent读取了SKILL.md然后按照Skill方法处理amounts.csv。”

结果验证与闭环：Artifact 的获取与分析

任务完成后，生成的文件作为 Artifact 发布。我们需要调用 Session 的 Artifacts API 来获取结果。

首先，通过 GET 请求访问当前 Session 的 artifacts 列表。响应中返回了 artifact ID、文件名和大小。例如，summary.json（无 Skill 时）大小为 43字节；而在引入 Skill 后，生成的 skill-summary.json（JSON）大小为 81字节，skill-report.md（Markdown报告）大小为 221字节。这些数字直接反映了内容复杂度的增加。

接着，在路径后加上 artifact ID 和 content，通过 curl 将文件下载到本地。下载完成后，使用 cat 命令查看内容： - JSON 结果：包含 rows（3行）、total（60）、verified（true），以及新增的 skill_used 字段，其值为 csv-report。 - Markdown 报告：包含了校验状态、行数（3行）、总额（60），结构完整。

这一过程形成了完整的闭环：输入文件进入沙箱 -> Agent 执行命令/代码 -> 生成产物 -> Artifact API 下载 -> 本地复核。对于同一份 CSV，无论是否加载 Skill，核心数据（3行、总额60）保持一致且验证状态均为 true。这证明了 Skill 确实被上传加载，并有效影响了任务的结果格式和丰富度。

“下载完成后……JSON中除了rows total和 verified，还出现了 skill_used 它的值是 csv-report Markdown报告包含了校验状态行数和总额。”

结论

OpenAI Agents API 的公测版通过提供托管 Harness、可选执行环境和可插拔 Skills，重新定义了 Agent 的开发范式。它解决了长任务中上下文管理、状态恢复和结果交付的痛点，将通用的执行逻辑与开发者的业务数据隔离开来。通过两个真实案例可以看出：基础流程实现了从文件输入到 Artifact 输出的自动化闭环；而 Skill 机制则赋予了 Agent 可复用的任务规范和输出标准。开发者只需关注业务逻辑和安全策略，即可构建出稳定、可观测且具备生产能力的 AI Agent 应用。