用 OpenAI Agents API 搭一个托管云 Agent：Codex 同款 harness 上手实操

Agents API 用的不是普通用户密钥，而是 OpenAI 平台项目里的 application API key。官方文档列出的权限有三项，缺一项就会在创建会话时报权限错误：

# 需要的权限范围
api.agents.read          # 读取 agent / 会话
api.agents.write         # 创建与操作会话（session operations）
api.responses.write      # 模型推理（model inference）

# 导出到环境变量
export OPENAI_API_KEY="your-api-key"

先装新版 SDK。Python 端只要一条命令，注意要用 --upgrade，因为 beta.agents 命名空间是新增的：

pip install --upgrade openai
# 验证版本里有 beta.agents
python -c "from openai import OpenAI; c=OpenAI(); print(hasattr(c.beta, 'agents'))"

新建 quickstart.py。这段代码会创建一个会话，让 Agent 在沙箱里写出 tree.py、执行它，并把真实输出回报：

from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the "
              "files in the current directory. Run it and show me the output.",
        stream=True,
    ) as events:
        for event in events:
            # 原样打印事件，先看清协议长什么样
            print(event.to_json(indent=None), flush=True)

运行 python quickstart.py。如果不想装 SDK，也可以用 cURL 直接打接口，此时 必须手动带上 Beta 请求头，SDK 会自动加：

curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted" },
    "input": "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
    "stream": true
  }'

这是本篇最容易被忽略、却最容易在生产里翻车的一节。官方文档专门提醒：「回合完成」不等于「所有工具都成功」。需要区分的事件类型如下：

把判断逻辑写成代码，而不是靠肉眼看日志：

OK = "agent.session.turn.completed"
BAD = ("agent.session.turn.failed",
       "agent.session.turn.cancelled",
       "agent.session.failed")

def consume(events):
    turn_done = False
    for event in events:
        name = event.type
        if name in BAD:
            raise RuntimeError("会话异常结束: %s" % name)
        if name == OK:
            turn_done = True
    # 关键：completed 之后仍要校验业务结果
    return turn_done

会话是有状态的。把事件里的 session_id 存下来，就能在同一上下文里继续下一条指令，例如「给 tree.py 加一个最大深度参数，运行并展示输出」。

# 1) 从事件中保存 session_id
session_id = None
for event in events:
    sid = getattr(event, "session_id", None)
    if sid:
        session_id = sid

# 2) 继续会话：先打开事件流，再发送跟进输入
with client.beta.agents.sessions.continue_(  # 具体方法名以官方文档为准
    session_id,
    input="Add a maximum-depth option to tree.py, run it, and show me the output.",
    stream=True,
) as events:
    for event in events:
        print(event.to_json(indent=None), flush=True)

environment 决定代码在哪跑。托管沙箱开箱即用，自托管适合已有基础设施的团队，第三方沙箱则在 GPU、冷启动、长会话等维度各有取舍。官方列出的沙箱合作方包括 Blaxel、Cloudflare、Daytona、DigitalOcean、E2B、Modal、Oracle、Runloop、Vercel。

Agents API 内置了子智能体能力：打开多智能体模式后，复杂任务会被拆成若干独立片段并行处理，每个子智能体维护自己的上下文以保持专注，主智能体负责协调与汇总。并发子智能体数量可以设上限，避免一次开太多把预算烧穿。

agent={
    "model": "gpt-6-astra",
    "instructions": "Coordinate subagents and merge their findings into one report.",
    # 多智能体开关与并发上限（字段名以官方 multi-agent 指南为准）
    "multi_agent": {"enabled": True, "max_concurrent_subagents": 3},
}

harness 里另外两个和成本直接相关的机制也值得知道：上下文压缩——会话接近上限时自动压缩早先的上下文，保留继续干活必需的信息，开发者不用自己写摘要逻辑；工具搜索——按需加载工具定义，而不是一次性全塞进提示词，既省 token 又保住模型缓存。

会话可以保留继续用，也可以删掉。删除接口很简单：

result = client.beta.agents.sessions.delete("sess_123")
print(result.to_json())

# 或直接用 cURL
curl -X DELETE "https://api.openai.com/v1/agents/sessions/sess_123" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"