OpenAI Agents API

TL;DR

来源说明：本卡片基于 OpenAI 官方文档与开发者社区公告整理，非第一人称实测；beta 阶段接口可能调整，请以官方文档为准。

它到底是个什么

OpenAI 在官方博客里把话说得很直白：随着 Codex 与 ChatGPT for Work 扩到数百万人，「有用的 agent 需要一个强大的 harness 来管理上下文、高效使用工具、协调子 agent」，同时还要有「能让它们连续可靠运行数天」的基础设施。Agents API 就是把这两样东西打包卖成一项托管服务。

它的开源底座是 GitHub 上的 openai/codex 仓库——harness 逻辑是公开可读的，这给了一条退路：不想被托管服务锁定，就自己部署开源 harness。

四个核心对象

核心能力

长时运行：自动上下文压缩

会话接近上下文上限时，harness 自动压缩并保留关键信息——不需要你自己写摘要逻辑，agent 就能跑几小时乃至几天。这是自研 agent 最容易做砸的一块：要么上下文溢出，要么摘要把关键约束丢了。

成本优化：tool search

只按需加载相关工具定义，而不是每次请求都把几十个工具的 schema 全塞进上下文。工具多的场景下这是实打实的 token 节省。

并行：原生 subagent

"agent": {
  "model": "gpt-6-astra",
  "multi_agent": { "enabled": true, "max_concurrent_subagents": 3 }
}

主 agent 拆解任务、并行派发给 subagent、再合并结果。官方客户案例中，Ciridae 称 subagent 流带来 4 倍延迟下降；SafetyKit 称案件审查单案成本下降 60%；Hypha 称 harness 与沙箱分离后失败响应减少 86%（均为客户自述数据，非第三方复现）。

执行环境：八家沙箱可选

OpenAI 托管沙箱之外，官方点名集成了 Blaxel、Cloudflare Dev、Daytona、DigitalOcean、E2B、Modal、Oracle、Runloop、Vercel，覆盖托管环境、VPC 内部署与不同硬件规格。对有合规或 GPU 约束、不能把代码执行交给第三方的团队，这是能不能用的分水岭。

价格

成本提示：容器是新增科目。社区已有开发者提醒，第一次用托管沙箱要先算清容器开销再批量起容器；长时会话 + subagent 并行会同时放大 token 与容器两块账单。

上手 5 分钟

import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "mcp",
        server_label: "observability",
        transport: { type: "http", server_url: "https://observability.example.com/mcp" },
      },
    ],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: ["vault_YOUR_VAULT_ID"],
  environment: {
    type: "openai_hosted",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input: "Investigate service-api's elevated 5xx rate over the last 30 minutes.",
});

请求需带 beta header；文档以 gpt-6-astra 为参考模型。完整参数见官方 Agents API 概览与 quickstart。

同类对比

一句话区分：要省运维、已绑 OpenAI → Agents API；要跨模型或数据自控 → 开源 harness / 私有化平台；要可视化给业务同学用 → Dify / Coze。

国内使用注意事项

• 网络与账号：沿用 OpenAI 账号体系，需稳定代理；频繁切 IP 有风控风险。
• 数据合规是硬门槛：公测期数据处理在美国且不支持 ZDR，涉及个人信息出境或行业监管的场景，短期内不建议上托管版。
• 替代路线：优先评估国内可私有化的 Dify / Coze、或国产模型 + 开源 harness 自建，见 国产编程模型。

避坑清单

1. 先确认合规再写代码：ZDR 与数据驻留是上线前的第一道门，别等接入完成才发现不能上生产。
2. 批量起容器前算成本：沙箱按运行时长计费，长会话 + 并行 subagent 会同时放大两块账单。
3. beta 接口会变：预留升级窗口，别把 beta.agents.* 的返回结构硬编码进核心逻辑。
4. subagent 不是免费的加速：并行拆分会放大 token 消耗，先用小任务验证收益再铺开。
5. 不要指望它替你做工具设计：harness 只解决运行时，工具、知识、工作流仍然是你自己的活——这也是 OpenAI 反复强调的部分。

适合 / 不适合

在生产里跑长时 agent 的团队；已绑 OpenAI 模型、不想自研会话与上下文管理的团队；需要 subagent 压延迟的场景；要保留自有执行环境的企业。
跨模型可迁移的 agent 平台；数据不出境 / ZDR 硬性要求；成本极度敏感的批量作业；国内直连环境。

相关阅读

• 资讯：OpenAI 发布 Agents API 公测 · AI 编程工具周报 2026-09-13
• 同类：Codex CLI · Dify · Coze · CrewAI · Claude Code
• 模型：GPT-6 Astra
• 概念：AI Agent · MCP 协议 · Agent 记忆 · 上下文工程

Long-tail quick picks

长尾检索速查：下面三项对应「OpenAI Agents API 开源版 / 免费版 / 国内可用」等搜索意图，方便直接跳转。

Open-source alternatives

• 是否开源：部分开源（托管服务闭源，底层 harness 来自开源 openai/codex 仓库）
• 想找全开源替代？看这几个：DeepSeek Harness · n8n · CrewAI

Free tier

• 是否有免费档：否（API 本身免费，但 token 与容器照常计费）
• 价格概要：API 不额外收费；按 token、工具与容器（沙箱）计费
• 预算敏感可转开源自部署路线：DeepSeek Harness（MIT）或 Dify（可私有化）

China availability

• 是否国内可用：否
• 中文友好度评分：2 / 5
• 国内访问需稳定代理；公测期数据留在美国且不支持 ZDR，合规场景建议走私有化方案：Dify / Coze / FastGPT。

来源

• Introducing the Agents API — OpenAI 官方
• Introducing the Agents API and hosted sandboxes — OpenAI Developer Community
• Agents API 概览（官方文档）
• OpenAI Codex 开源仓库
• OpenAI opens Agents API beta — GenAI Daily

本卡片由 AI 之家编辑部根据以上公开资料整理，非厂商付费内容；公测期功能与定价以 OpenAI 官方文档为准，欢迎在 反馈邮箱 反馈更新。