Administrator
Published on 2026-11-11 / 10 Visits
0
0

托管 Agent API 可移植性:路由同名之后,审计控制面

把一个长程 Agent 从平台 A 迁到平台 B,最危险的时刻往往发生在第一个请求成功之后。

POST /agents 返回了 ID,POST /sessions 能启动任务,SSE 也持续吐出事件。表面上,迁移已经完成。随后网络闪断,客户端漏掉一条待审批事件;新平台的默认权限直接放行了工具;工具实际写入成功,重试又执行一次;会话显示 idle,业务工单却仍处在半完成状态。

Kimi Hosted Agents、Z Managed Agents 和 Claude Managed Agents 都在使用 Agent、Environment、Session、Events、工具与凭据库这些相近抽象。它们确实在形成共同的架构语言。生产可移植性仍要靠一份更细的控制面合同。

先冻结迁移后仍须成立的事实

迁移开始前,先把供应商 API 放到一边,写下七条业务不变量:

  1. 同一个业务动作最多提交一次。
  2. Agent 只能使用当前身份和任务明确授权的资源。
  3. 断线重连后,持久事件不丢失,业务转换不重复。
  4. 待审批工具必须停在可恢复状态,拒绝后不能继续执行。
  5. 凭据可以完成允许的请求,模型、文件、命令输出和事件历史看不到原值。
  6. 最终产物、会话状态和权威业务系统可以相互对账。
  7. 新运行时失败后,旧运行时能从最近一次已验证业务状态续接。

这七条才是可移植层。Agent、Session 和 Events 是各平台用来实现它们的组件。

站内的 OpenAI Agents API 迁移审计已经把单个平台拆成状态、权限、恢复和可观测性。本轮横向比较进一步问:多个托管 Harness 使用相似名词时,哪些差异仍会直接改变业务结果。

画一张控制面归属图

三家当前文档都能映射到同一张高层图:

业务系统
  -> 创建或引用 Agent 定义
  -> 选择 Environment
  -> 启动 Session
  -> 发送和接收 Events
  -> 处理审批与自定义工具
  -> 核对产物和外部状态

Kimi 快速开始把 Agent、Environment、Session 和 Vault 分成独立资源。智谱概述明确用 Agent、Environment、Session、Events 四个概念组织托管运行时。Claude Managed Agents也以持久 Agent 配置、环境和会话承载长程异步任务。

共同点足以降低学习成本,也足以支撑一个薄适配层。三份一手材料都没有宣称相互兼容,更没有形成统一协议。真正需要对账的是名词背后的状态机。

第一处错配:同一个 Session,保存的东西不同

会话里至少存在四种状态:

状态 应由谁提供真相 迁移验收
对话与事件 托管平台 断线后能列出完整历史并去重
沙箱文件与依赖 Environment 或 Session 跨轮、中断、归档和删除边界明确
业务对象 自有系统 用权威接口读回最终状态
第三方副作用 工单、支付、消息等目标系统 稳定幂等键阻止重复写入

Claude 的事件文档说明,会话进入空闲时会检查点化沙箱;Session 操作文档则说明删除会话、删除上传文件、删除内存和删除 Vault 是不同生命周期。智谱文档把每次 Session 的云沙箱与可复用 Environment 分开。Kimi 也将 Environment 配置和实际运行的 Session 分成不同资源。

所以,迁移模型里不要只留一个 persistent=true。至少保存:

workflow_id
provider
agent_id + effective_version
environment_id + effective_version
session_id
policy_hash
idempotency_key
last_verified_business_state

修改 Agent 或工具策略后,用一个已运行 Session 和一个新 Session 做对照,确认配置快照是否符合记录。否则,同一个 Agent ID 可能在两次事故复盘中代表不同能力。

第二处错配:都用 SSE,断点语义仍不一样

事件流的共同传输协议,容易让人误以为恢复也可以共用一段代码。

Kimi 的迁移指南建议先订阅再发消息,并用 Last-Event-ID 断点续读。智谱的 Events 文档明确 SSE 只传连接建立后的实时事件;重连时先开新流,再从最后一个 processed_at 用包含边界的条件补拉历史,最后按事件 ID 去重。Claude 的事件流文档同样把实时流定义为 live-only,恢复方式是先开新流、再拉完整历史、按 ID 排除重复。

三种做法追求同一个结果,游标合同并不相同。内部事件账本需要同时保留:

  • 供应商事件 ID 与原始类型;
  • 供应商排序字段与接收时间;
  • payload 哈希;
  • 是否已经触发业务状态转换;
  • 关联的工具调用、审批和结果 ID;
  • 未识别字段与完整原始事件引用。

故障注入要卡在最难的位置:收到 tool-use,尚未回传 result 时切断连接。通过条件是恢复后能找到同一未决调用,业务层只应用一次转换,最终还要从目标系统读回结果。

第三处错配:权限字段相似,默认值与执行主体不同

Kimi 的权限策略使用 enabled、always_allow 和 always_ask,内置工具与 MCP 工具在未显式配置时默认启用并放行。Claude 的 Agent toolset 默认 always_allow,MCP toolset 默认 always_ask;auto 代表服务端风险判断,它不是人工审核。智谱有两层默认值:创建 Agent 时省略 tools等价于空数组,不会启用内置工具集;但一旦声明 agent_toolset_20260601 或 mcp_toolset,工具集的 permission_policy默认就是 always_allow,除非显式覆盖。它也支持逐工具 always_ask,自定义工具仍由调用方应用执行。

从一个平台复制工具名称到另一个平台,可能在不改业务代码的情况下扩大权限。迁移清单应以动作风险为中心:

字段 必须回答的问题
executing identity 实际用谁的身份调用目标系统
resource scope 凭据能访问哪些租户、项目和对象
approval policy 自动放行、服务端判断还是人工确认
idempotency 超时重试如何识别已经成功的写入
verification read 哪个权威接口证明动作最终生效
audit evidence 哪个事件和业务回执能重建责任链

自定义工具尤其需要单独处理。平台权限策略可能只负责托管工具,最终业务写入仍由你的应用完成。身份有效也不代表动作已经获得授权,这一点与 MCP Agent 身份与委托的结论一致。

凭据可移植性要做一次真实泄露测试

Kimi 与 Claude 都提供 Vault 环境变量占位符:沙箱里看到占位值,真实凭据在允许的出站请求处替换;目标主机限制与 Environment 网络策略分别生效。智谱的 Vault 文档也明确,environment_variable 在沙箱中是 omasec_ 代理值,Agent 与沙箱拿不到原文;只有出站请求命中该凭据的 networking 目标主机规则时才替换真实秘密。这比把 Key 写进系统提示词安全得多,也有明确边界。

Kimi 文档指出,占位符不适合需要在本地验证真实 Key 或用真实秘密计算签名的客户端。Claude 文档提醒,用 Vault 凭据交换得到的新 Token 可能以明文回到沙箱。智谱同样说明,代理值不能用于本地签名,也不能直接放入 JSON body 完成需要原始秘密的换票。环境网络策略、凭据主机范围、返回 Token 和二次交换必须分别验证。

准备一个专用 canary secret,执行四项检查:

  1. 允许域名的请求成功。
  2. 禁止域名的网络请求失败。
  3. 禁止域名不会获得真实凭据替换。
  4. Prompt、沙箱文件、命令输出、事件历史和应用日志都搜索不到原值。

主机白名单只约束凭据替换时,还要同时验证沙箱网络策略。两层任何一层放宽,都会改变真实暴露面。

数据边界必须按部署路径填写

模型名称无法回答数据在哪里、由谁运营、保存多久、怎么删除。

Claude 当前明确标注 Managed Agents 不满足 Zero Data Retention,也不在 HIPAA BAA 覆盖内;会话历史、沙箱、会话产物、上传文件、Memory 和 Vault 分别遵循不同保留与删除路径。智谱允许在创建会话时启用客户密钥的业务事件落库加密,同时保留控制与遥测字段供调度和排障。

对于公开文档没有回答的地区、保留或删除问题,正确状态是 unknown,并在生产迁移前获取适用合同。相同的 Agent、Session、Events 外形,不能替另一个平台证明数据处理边界。

这部分还要区分平台运营方和云平台路径。一个功能可以在供应商 API、合作云或自托管沙箱上出现,控制面、数据面和责任主体仍可能不同。

用业务完成条件压住状态机差异

idle 只表示控制面停在某个位置。智谱文档中,session.status_idle 可能对应本轮结束、等待动作、重试耗尽或拒绝。Claude 的 Session 操作文档说明,Session 空闲时仍可能存在开放的 workflow run。Kimi 的 Session 操作与事件流文档则用 idle、running、terminated 和 stop reason 描述会话生命周期。

把完成条件写在业务系统:

accepted = 预期产物存在
        AND 权威业务记录匹配
        AND 外部写入次数为 1
        AND 没有未决工具调用
        AND 实际策略哈希等于批准版本

最终消息写得再完整,也不能替代这些检查。结果验收能跨平台,单个状态枚举只能留在适配器内部。

一轮可回滚的迁移顺序

先冻结一组真实任务,再让旧运行时与新运行时面对相同输入、权限和业务验收。

第一阶段只读或影子运行。重点验证事件恢复、配置快照、文件生命周期和拒绝动作。第二阶段开放低风险可逆写入,所有工具写入都带幂等键并执行 read-after-write。第三阶段故障注入,覆盖流断开、审批等待、工具提交后超时、沙箱中断和新平台不可用。第四阶段扩大流量,同时保留旧适配器,直到真实演练过回滚。

最小验收表如下:

场景 通过证据
流中断 历史与新流合并后无业务漏记和重复
待审批 allow 与 deny 都能恢复,并保存责任证据
写入后超时 重试先读权威系统,外部动作只发生一次
Session 配置变化 实际快照与迁移账本一致
凭据 canary 允许请求成功,Agent 可见状态没有秘密原值
资源删除 Session、文件、Memory、Vault 分别执行并核验
回滚 旧运行时从最近已验证业务状态继续

结论

托管 Agent API 已经在架构语言层收敛。这足以支持共享概念、内部 SDK 和运维工具,也能显著降低迁移的起步成本。

生产可移植性位于更高一层:业务 workflow ID、工具权限矩阵、事件去重账本、状态归属、数据边界、结果验收和已经演练过的回滚。把这些合同掌握在自己手里,各平台的差异就会变成适配工作,而不是迁移事故。

常见问题

三家托管 Agent API 已经兼容了吗?

当前一手文档显示资源模型与事件式交互相似,没有声明相互兼容。Headers、Schema、默认权限、恢复和生命周期仍需分别实现。

使用 SSE 是否就能共用恢复逻辑?

SSE 只统一传输。游标、历史查询、排序字段与去重方式仍有差异。内部应统一事件账本,保留原始供应商事件。

MCP 能否统一工具权限?

MCP 可以统一工具发现和调用结构。执行身份、平台默认权限、人工审批、凭据范围和业务读回仍要单独定义。

迁移前最少要证明什么?

用同一冻结任务集证明断线恢复、审批与拒绝、外部写入幂等、秘密不暴露、产物恢复、数据处理边界和回滚。

参考资料


Comment