OpenAI Agents API 迁移是一项基础设施决策。OpenAI 可以接手 Codex Harness、Session、编排、上下文压缩与恢复，应用仍需负责业务工具、权限、结果验证和最终交付。本文把这条责任分界转成一套可执行、可回滚的迁移审计表。
阅读时间：约 7 分钟 · 约 2600 字
TL;DR
- 先划清三方责任：应用服务器、托管 Harness、执行环境。
- 分别审计 Session 状态、工具权限、故障恢复、可观测性和数据控制。
- 用冻结的真实任务集对新旧运行时做同口径评测。
- 在故障恢复、拒绝动作和单个合格任务总成本通过门禁前，保留可回滚适配层。
- 截至 2026-09-11，public beta 仅支持美国数据驻留，不支持 ZDR，自托管 Sandbox 也不改变这一点。
OpenAI 实际接手了什么
OpenAI 于 2026 年 9 月 10 日发布 Agents API，当前状态为 public beta。官方将它定义为基于 Codex Harness 的托管服务，覆盖长任务 Session、上下文管理、工具使用与 Subagent 协调。
Agents API 架构文档给出了更适合迁移决策的三层模型：
| 层级 | 主要责任方 | 关键职责 |
|---|---|---|
| 应用服务器 | 企业 | 投递任务、接收事件、处理函数工具、执行业务政策、交付结果 |
| Agent Harness | OpenAI | 运行模型与工具循环、维护 Session、压缩上下文、编排与恢复 |
| 执行环境 | OpenAI、合作伙伴或企业 | 执行代码、暴露文件与网络、管理算力和存储生命周期 |
一次 API 调用可以创建 Session，生产责任仍然跨越三层。托管编排减少了重复建设，也把原来隐含在自研代码里的故障边界、状态语义和运营证据移进新的平台合同。
审计一：状态归谁
Agent 状态至少包含五类：
- 对话状态：指令、消息、Turn、Item 和中途 Steering。
- 工作状态：文件、产物、检查点和中间结果。
- 应用状态：客户记录、流程状态、审批状态和幂等键。
- 外部状态：工单、部署、邮件、付款等已经提交的副作用。
- 评测状态：任务输入、预期结果、轨迹和审核结论。
Session 文档说明，一个 Session 会持续保存 Agent 配置、对话和已保存工作。管理文档同时要求应用把 Session ID 存进自己的数据存储。
实际边界很清楚：OpenAI 保存 Session，企业仍需建立业务对象到 Session 的持久映射。恢复流程不应从在控制台里搜索开始，而应从一条稳定关系开始：
业务流程 ID
-> Agents Session ID
-> 当前 Turn ID
-> 最近一次已验证业务状态
-> 幂等键
业务真相应留在 Session 之外。Session 能说明 Agent 尝试了什么，业务系统才负责证明最终接受了什么。
审计二：谁有权行动
托管 Harness 可以选择和调用工具，企业仍负责定义工具、身份与批准边界。
每个工具都应回答五个问题：
| 问题 | 必须保留的证据 |
|---|---|
| 谁发起动作 | 已认证用户、服务身份与业务角色 |
| Agent 可调用什么 | 版本化工具 Schema 与允许列表 |
| 凭据能访问什么 | 源系统权限与拒绝路径测试 |
| 哪些动作需要批准 | 风险等级、批准人、有效期与批准回执 |
| 什么证明动作完成 | 对权威系统执行写后重读 |
OpenAI 的 Sandbox 安全文档明确指出，Agent 生成的代码可以访问环境里可见的文件、凭据和网络。官方建议隔离工作负载、限制外连目标、分离应用密钥与环境密钥，并通过凭据代理处理第三方访问。
自托管 Sandbox 只改变代码在哪里运行。工具授权、秘密暴露和 Agents API 留存仍需独立设计与测试。
审计三：失败后怎样恢复
恢复能力应通过故障注入证明。至少测试四类故障：
- Harness 或 Turn 失败：应用能否识别生命周期失败，并安全继续或终止。
- 工具处理器失败：待处理函数调用恢复时，业务动作是否只执行一次。
- 执行环境丢失：哪些文件能够恢复，新环境能否重新连接正确 Session。
- 外部系统部分成功：工具已经写入、响应却丢失时，重试前能否识别已有结果。
验收对象应该是业务提交状态。以工单 Agent 为例，成功意味着正确工单只修改一次、证据已附加、客户收到正确结果。Turn 完成只是中间信号。
审计四：能否看清与算清
可观测性文档列出了控制台日志、Session 事件、保存历史、Turn 检查、Subagent 命令执行和 Token 使用量。它也明确说明，Trace API 获取与外部 Trace Exporter 尚未进入 public beta API。
迁移因此需要回答两件事：
- 现有事件响应流程能否通过受支持接口取得足够证据。
- 财务能否计算每个合格业务结果的总成本。
成本口径要覆盖 Root Agent 与 Subagent Token、重试、工具、Sandbox 算力、合作伙伴费用、失败运行和人工复核时间。公告称 Agents API 不收取独立附加费，模型、工具和托管 Sandbox 仍按各自费率计费。
发布公告中的客户陈述包括评测分提高、延迟降低、单案例成本下降和失败减少。这些数字适合生成验证假设。公告没有提供任务集、样本量和基线配置，迁移结论仍需依赖自己的冻结任务集。
四步完成可回滚迁移
先从常见生产任务和真实失败中抽取代表性任务集，冻结输入、预期结果、权限边界与评分规则。新旧运行时使用同一口径：
| 指标 | 作用 |
|---|---|
| 合格任务率 | 衡量审核后的业务完成质量 |
| 人工处理时间 | 捕获隐藏运营成本 |
| P50 与 P95 完成时间 | 同时观察常态与长尾 |
| 单个合格任务总成本 | 纳入重试、工具、算力和复核 |
| 拒绝动作准确率 | 检查最小权限与批准边界 |
| 恢复成功率 | 检查恢复过程是否产生重复副作用 |
| 可诊断失败率 | 检查运营人员能否定位失败层级 |
迁移可以分四步推进：
- 适配层：让新旧运行时共用内部任务、工具与结果接口。
- 影子运行：在复制或只读输入上运行 Agents API，关闭业务写入。
- 受控写入：只开放低风险、可逆动作，并强制写后重读。
- 逐步切流：质量、恢复、安全、可观测性和成本门禁全部通过后扩大流量。
适配层保留到回滚演练真正完成。开放源代码提升了 Harness 核心逻辑的可见性，托管服务与仓库代码的逐版本行为等价仍需自行验证。可迁移性最终来自企业自己的接口和测试集。
当前 public beta 约束
Agents API 概览当前说明，Session 数据仅支持美国区域驻留，Zero Data Retention 尚未支持。选择 self-hosted Sandbox 也不会使 Agents API 获得 ZDR 资格。
这些信息的核验日期为 2026-09-11。public beta 变化速度快，每次扩大生产使用前都应重查留存、区域、定价、API Schema 和可观测性边界。
FAQ
Agents API 与 Agents SDK 应怎样选择
当 Session、编排、压缩、恢复和执行环境运维构成实际瓶颈时，Agents API 的托管能力价值更高。当 Harness 行为、跨模型路由或完整部署控制本身属于产品差异化时，SDK 或自研运行时会保留更多控制权。
Self-hosted Sandbox 是否意味着整个 Agent 都留在 VPC
Self-hosted 让执行环境留在企业基础设施中，OpenAI 仍运行 Harness 与 Session。当前文档同时明确，自托管不会让 Agents API 满足 ZDR。
重试时怎样避免重复业务动作
为每次业务操作生成稳定幂等键，记录权威结果，并在重试前读取现有状态，写入后再次确认。Session 恢复和业务事务恢复属于两套机制。
最小迁移评测需要什么
冻结一组真实任务和失败样本，在相同输入与政策下比较合格任务率、长尾延迟、人工处理时间、总成本、拒绝动作、恢复成功率和可诊断性。
迁移判断
Agents API 为持久云端 Agent 提供了可信的托管基础。迁移价值取决于当前瓶颈是否位于 Session、编排、压缩与恢复层。区域、ZDR、可导出观测能力或 Harness 差异化形成硬约束时，当前版本更适合继续验证。
下一步：选择 20 个代表性生产任务，加入 3 个故障注入案例，让新旧运行时共用同一工具适配层。只有新系统交付了更高质量的合格结果，同时保留经过演练的回退路径，迁移才算通过。
参考资料
- OpenAI：Introducing the Agents API，2026-09-10。
- OpenAI：Agents API overview。
- OpenAI：Agents API architecture。
- OpenAI：Run and continue sessions。
- OpenAI：Manage sessions。
- OpenAI：Sandbox security。
- OpenAI：Observability and usage。