大家好，我是小木头。OpenAI 最近发布了 Agents API，目前还是公开测试版本。它把 Codex 背后的 Agent Harness、Session 托管沙箱、文件 Skills 等能力通过 API 提供给开发者。它面向的场景是让模型真正接手一个需要持续推进的任务。

开发者提交自己的目标和运行配置，Agent 可以在 Session 调用工具、运行命令、处理文件、生成产物。这里咱们可以称它为 artifact，也就是产物，并把整个工作过程持续的返回给应用。OpenAI 托管的是 Agent 持续工作的运行层，包括模型与工具之间的循环、上下文管理、Session 生命周期管理、事件记录、任务恢复。

执行任务所使用的环境仍然可以由开发者自行的选择，既可以直接使用 OpenAI 托管的沙箱，也可以接入自己的沙箱或者企业的基础设施。工具、MCP 服务、Skills、业务数据、网络权限和安全策略，也都可以由开发者提供并掌控。

所以 Agents API 提供的是一套可以组合的 Agent 基础设施。OpenAI 负责维护通用的 Harness，开发者呢把自己的执行环境和业务能力接进来，共同组成真正面向产品的 Agent。为了把第一次上手讲得更具体一些，在今天的演示中，我们先使用 OpenAI hosted sandbox 也就是它所托管的沙箱环境。

未来我们再通过完整的演示，来看看怎样连接自己的 Sandbox。这期视频我们先快速理解 Agents API 再用两个真实请求验证它。我们会看看文件怎样进入工作区，Agent 怎样执行命令，结果怎样变成可以下载的 artifact。然后上传一个 Skill，让同一个任务按照可复用的方法来执行。

Agents API 最重要的部分，是 OpenAI 把 Codex 背后的 Agent Harness 作为托管能力开放出来。Harness 可以理解为模型之外的 Agent 运行层，它组织模型调用和工具调用，把工具结果送回模型。管理长任务中的上下文，在需要时压缩历史，协调 subagent 并维护 Session 从创建执行到等待到继续的整个生命周期。

这些能力共同组成一个 Agent loop，模型负责判断下一步做什么，Harness 负责让这个判断可以连续的变成行动。发起工具调用、记录调用的结果、更新上下文，妥善的处理失败再进入下一轮。OpenAI 会在服务端运行并更新这一层。

开发者可以直接使用与 Codex 一起演进的执行逻辑，Session、Turn 和 Items 是这一套运行层对外暴露的对象。他们让应用能够跟进一个持续运行的、持续执行的任务，而不是只能等待一次模型生成结束。OpenAI 托管 Harness 同时呢把执行环境保留为可以选择的边界，最直接的选择当然就是 OpenAI hosted sandbox。

OpenAI 负责创建和连接 Linux 工作区，开发者配置网络权限、环境变量、依赖包和输入文件。它适合快速启动，这也是我们本期视频使用的方式。任务也可以运行在开发者自己的基础设施里，自托管环境可以连接企业 VPC、自定义镜像、内部数据、密钥系统和特殊的硬件资源。

开发者还可以选择第三方合作伙伴提供的计算环境，根据启动需求，根据 CPU、GPU、内存等硬件需求，还有像地理区域以及价格方面去做的取舍。这部分呢会留到未来的演示中再来做介绍。工具、MCP 服务、Skills、业务知识和工作流，继续呢由开发者提供。

他们决定 Agent 能够访问哪些系统、遵守什么规则、什么方法，以及最终怎样进入真实的产品。模型与托管 Harness、可选择的执行环境、开发者自己的能力层，共同组成完整的 Agent。这套分工带来的直接变化是开发者和开发团队可以减少维护通用 Agent loop 的工作，把更多精力放在任务设计、权限安全和业务能力上。

同时，Session、事件流以及任务执行产物，也就是 artifacts 给产品提供了稳定的接入对象。让长任务可以观察、继续和交付结果。Agents API 的入口是 /v1/agents/sessions，请求头当然了包含 API key，还需要 agents=v1 的 Beta 标记以及 JSON 内容类型。

请求体里面指定模型、执行环境、输入文件、任务指令，并且开启流式的返回。先看左侧这条完整的 curl authorization 读取本地环境变量中的 API key，画面呢并不显示真实的密钥。OpenAI-Beta 指定 agents=v1，Content-Type 是 application/json。

最后通过 data-binary 把整个请求文件提交到 sessions 这个 endpoint，以后任务变复杂时我们仍然可以把请求体保留成独立的文件，方便版本管理和重复的测试。这次我选择 openai_hosted 关闭网络访问，把 amounts.csv 以内联文件的形式放进到工作区。

也就是 /workspace/amounts.csv，任务非常简单了读取 CSV 检查 amount 列计算行数和总额再把结果写到 workspace 的 outputs/summary.json 文件中。内联文件包含三个关键字段 type 是 inline，path 决定它在沙箱里的位置。

data 保存文件经过 base64 编码后的内容，这里的 base64 只是文件传输形式 Agent 启动后看到的是普通的 CSV 文件。对于更大的输入也可以先通过 OpenAI 的 Files API 上传再在环境配置里引用 file ID。curl 发出以后服务端返回 HTTP201 并且创建 Session，后续的命令执行、工具结果、最终回答以及 artifact 都属于这一次的 Session。

对于第一次理解 Agents API 可以先这么理解，一次 API 请求启动一个能够在执行环境里持续工作的 Agent 任务。因为请求里设置了 stream=true，服务端会持续的返回 SSE 事件。这里展示的是刚才那次真实请求脱敏后的记录。

最开始是 agent.session.created 表示 Session 和它的执行环境已经创建，随后是 turn.started 表示当前任务开始推进了。Agent 每产生一项工作都会出现对应的 item 事件，例如一条命令会先以 command_execution 加入再携带执行状态和输出完成。

最后还会看到 output_text、turn.completed 和 Session 回到 idle 状态产生文件时，这个 artifact 也会跟这次 Turn 建立关联。所以这里有三个层次 Session 是持续存在的任务容器，turn 是其中的一次推进或者一次任务的迭代。

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

Session 创建以后输入文件已经出现在了工作区目录中，我们先执行 PWD 确认工作目录再用 cat 命令直接查看 amounts.csv 文件的内容。文件里有 3 行数据 Alpha 是 10 beta 是 20 gamma 是 30。这里没有用截图代替也没有省略实际的输入，大家看到的命令和内容都是来自这次真实的请求记录。

这个小任务刻意的没有去依赖公网也没有额外的安装软件这样呢可以让我们把注意力集中在 Agents API 自己所提供的文件和执行流程上。关闭网络访问以后 Agent 仍然能够使用已经挂载的输入和沙箱自带的 Python 完成工作。

接下来 Agent 用 Python 读取 CSV 校验 amount 列计算出 3 行总额 60，并写入 summary.json 文件。写完之后他再一次用 cat 命令来读取结果确认 rows、total 以及 verified 都符合任务要求。画面中保留了完整的 Python heredoc，第一步用 DictReader 读取 CSV，第 2 步把 amount 转换成整数再求和。

第三步创建 outputs 目录并写入 JSON，任务指令要求写完以后呢重新读取所以最后的 cat 命令也是一次结果的校验。这些命令都属于 Session 的工作记录而不是后期为了咱们的画面效果临时编造的一个输出。任务完成以后 summary.json 会作为 artifact 发布，我们先调用 Session 的 artifacts 接口拿到 artifact ID、文件名和大小。

再调用 content 接口把文件下载到本地，第一条 get 请求访问当前 Session 的 artifacts 列表。响应里的 path 是 /workspace/outputs/summary.json，文件大小是 43 个字节。同时包含一个 artifact ID，这个 ID 是后续下载的定位信息。

视频中呢咱们保留的是末位的几位。第二条 get 请求在路径后面加上 artifact ID 和 content，并通过 curl 保存到本地。请求仍然需要 Authorization 和 beta header，也就是说文件不会因为任务结束就直接出现在本机，应用需要明确的调用 Artifacts API 把它取回来。

下载完成后咱们可以执行 cat 下载下来的 summary.json，内容仍然是 3 行总额 60 verified 为 true。到这里输入文件、沙箱命令、生成文件、artifact 下载和本地的复核就形成了一个闭环，这也是 Agents API 最直观的价值。

Agent 可以在托管执行环境里读取文件、运行代码，并把可交付的文件结果带回给应用。第二次请求我们给同一个 CSV 任务增加一个 Skill，这个 csv-report Skill 里面有真实的 SKILL.md 文件规定了校验步骤和输出格式。

既要生成 JSON 也要生成 Markdown 报告，还要在结果里标记实际使用的 Skill 名称。先用 find 命令查看目录这个示例里只有一个 SKILL.md，再用 cat 命令展示一下它的完整内容确认 amount 只出现一次。

检查每一个值都是数字，用 Python 做计算写入 JSON 生成 Markdown 报告最后读取两个文件进行验证。这些要求会成为 Agent 在执行环境里可以读取的任务方法，我们先在本地用 cat 命令展示 SKILL.md。

再把整个 Skill 目录打包成一个 ZIP，请求体中的 skills 数组使用 inline 类型名称是 csv-report。ZIP 内容经过 base64 编码放进 source，这就是 Skill 真正进入 Agents API 请求的方式。

请求体仍然保留同一个 amounts.csv 文件，区别是 environment 下面多了一个 skills 数组。source.type 是 base64 media_type 是 application/zip data 就是 ZIP 的编码内容。然后 input 明确要求使用 csv-report Skill，这样呢我们就能用同一份输入来对比没有 Skill 时生成一个基础的 JSON。

而加载 Skill 后同时生成结构更完整的 JSON 和 Markdown 报告，现在用完整的 curl 提交第二次请求。服务端同样返回 HTTP201 Session 创建后 Skill 被挂载到了 workspace 的 .managed-agents/skills/csv-report。

执行记录里显示 Agent 读取了 SKILL.md，然后按照 Skill 方法处理 amounts.csv。这里有几个证据可以确认他不只是把 Skill 名字写进了请求，第一 Session 返回的环境信息中包含 csv-report。

第二托管环境出现对应的 managed skills 路径，第三事件流记录了 Agent 读取 SKILL.md 并按里面的要求验证字段和生成两种格式。第四最终 JSON 中出现了 skill_used，它的值是 csv-report Markdown 报告也使用了 Skill 规定的结构。

那这一次就生成了两个 artifacts：summary.json 和 report.md，把它们逐个下载到本地再分别用 cat 命令来查看一下。JSON 中除了 rows total 和 verified，还出现了 skill_used 它的值是 csv-report Markdown 报告包含了校验状态行数和总额。

这样呢就可以确认 Skill 确实被上传加载并且影响到了任务的结果，下载过程与第一个任务相同。先列出 artifacts 确认 skill-summary.json 是 81 个字节，skill-report.md 是 221 个字节。

然后分别请求两个 artifact 的内容，下载后用 cat 命令同样的展开内容查看一下 JSON 和 Markdown。对同一份 CSV 给出一致的三行总额 60，验证状态都是 true。所以第一次认识 Agents API 可以先抓住四个方面：首先创建 Session，把文件放进托管的沙箱。

让 Agent 在 workspace 执行任务再把结果作为 artifact 下载回来，Skills 则把一套可复用的方法和输出规范一起装进了执行环境。OpenAI 托管的是 Agent Harness 和可选的 hosted sandbox，开发者仍然决定任务的指令、输入文件、Skills、网络权限。

以及最后怎样来消费得到的数据或文件，那下一期我们再把执行环境切到自己的 sandbox 或者 VPC。看看同一套 Agents API 如何连接开发者自己的基础设施，如果这期视频对你有帮助欢迎关注也欢迎大家一键三连吧。

我是小木头我们下期见。