OpenAI Agents API 公测上手：从 API key 到第一个云端 agent

OpenAI 把驱动 Codex 和 ChatGPT for Work 的那套 agent harness，以 Agents API 公测的形式开放给了所有开发者。一次调用就能起一个能读写文件、跑代码的云端 agent。这篇是完整的上手流程。

开通 API key

去 platform.openai.com 的 API Keys 页面新建一个 application API key，权限勾上 api.agents.read、api.agents.write（管 session）和 api.responses.write（管模型推理），然后 export 到环境变量里，比如 export OPENAI_API_KEY="你的key"。

注意：这个 key 不要放进 agent 的沙箱环境里。

装 SDK

按你熟悉的语言装最新版官方 SDK，Python 用 pip install --upgrade openai，JavaScript/TypeScript 用 npm install openai。

目前是公测阶段，请求里需要带 OpenAI-Beta: agents=v1 这个 header，官方 SDK 会自动加上，用 cURL 手写请求才需要自己加。

发起一个 session

调用新的 client.beta.agents.sessions.create 接口，传入 model（比如 gpt-6-astra）、instructions、environment（选 openai_hosted 就是用 OpenAI 托管的沙箱）和 input（具体任务描述），设 stream: true 就能实时看到 agent 的执行过程。

这一次调用就相当于起了一个能读写文件、跑代码的云端 agent。TypeScript 的例子：

import OpenAI from "openai";

const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions: "写干净的代码，跑一下，汇报真实输出。",
  },
  environment: { type: "openai_hosted" },
  input: "写一个 tree.py，打印当前目录的文件树，跑一下给我看结果。",
  stream: true,
});

for await (const event of events) {
  console.log(JSON.stringify(event));
}

跟踪执行进度

流式事件里留意 agent.session.turn.completed，代表这一轮跑完了，但完成不等于任务一定成功，还要看 agent 汇报的实际执行结果。

如果看到 turn.failed、turn.cancelled 或 session.failed，说明中途出了问题或被取消了。

流断了的话，先用 session_id 把之前保存的记录取回来，别直接重跑。

继续对话或收尾

记下第一次调用返回的 session_id，后面想让 agent 接着干活，直接用这个 session_id 发送后续输入就行，不用重新起一个 session。

任务做完了，需要的文件记得先下载保存，再调用 delete 把 session 清掉。

和内容工作流的关系

这套 Agents API 和内容生产那类工作流（拉取信源、整理成文、发布）是两条不同的技术栈，目前没有直接关系，纯粹是拿来单独做 agent 类产品用的。

计费方面，公测阶段免费接入，正式定价按 token 和工具调用量计费。