ACP v2 草案发布后，AI 编程代理的会话协议和模型网关该怎么分层

AI 编程代理不再只是编辑器里的一个问答框。它可能在终端运行测试，在后台继续修改文件，等待用户批准一条命令，又在用户打开另一个客户端后恢复同一段任务。此时，最容易被混淆的两件事开始分开：客户端怎样同代理保持会话，以及代理怎样调用、切换和治理模型 API。

7 月 20 日，Agent Client Protocol（ACP）发布 v2 草案。它不是模型调用协议，也不取代 MCP；它定义的是 IDE、终端等客户端与编程代理之间的交互边界。v2 最大的变化，是不再把一次 session/prompt 请求等同于一整轮任务。提示被接受后，代理可以继续通过会话更新汇报进度、工具调用、状态与完成信号。

对正在接入多个编程代理、多个模型 API 的团队来说，这个变化值得关注。协议升级不应该迫使你重写模型路由规则，也不应让每个客户端各自保存供应商密钥、成本数据和降级逻辑。更稳妥的做法是：让 ACP 管理交互会话，让 MCP 管理工具连接，让独立的模型网关管理模型访问与调用治理。

先分清 ACP、MCP 和模型网关

这三个层都与 Agent 有关，但处理的对象不同：

层次	解决的问题	不应承担的问题
ACP	客户端与编程代理如何建连、恢复会话、展示进度、请求批准和呈现文件变更	统一模型计费、跨供应商重试策略
MCP	Agent 如何发现和调用外部工具、数据源或客户端提供的能力	代理界面的会话生命周期
模型网关	请求该发往哪个模型、失败如何降级、预算如何约束、调用如何审计	IDE 与 Agent 之间的 UI 事件语义

把它们混在一起，常见后果是：某个 IDE 升级协议后需要改模型 SDK；某个模型供应商变更后，所有客户端各自改密钥和限额；或者把会话事件日志当成成本账本，最后无法按团队、仓库、任务类型核对用量。

分层并不意味着三层完全没有关联。一条有用的关联是统一的关联 ID：客户端创建会话时生成或接收 sessionId，代理为一次任务生成 taskId，模型网关为每次推理生成 requestId。日志系统把这些 ID 关联起来，就能回答“这次代码修改用了哪些模型、做了几次重试、花费多少、是否调用了敏感工具”，但不会把任何一层的协议细节泄漏到另一层。

ACP v2 具体改变了什么

ACP 官方将 v2 定义为草案，并建议实现方通过显式版本协商和功能开关启用，同时保留 v1。这个约束比新字段本身更重要：现在适合做兼容性实现与受控测试，不适合默认替换现有生产链路。

1. 提示被接受，不代表任务已经结束

在 v1 中，session/prompt 的响应通常伴随整轮任务结束。v2 将其改为“已接受”的确认；运行中、需要操作与空闲完成等状态转到 session/update 通知里表达。这样，代理可以在后台持续工作，客户端也可以在代理空闲时继续发送输入，而不是把长任务硬塞进一个悬挂请求。

这会影响调用方的状态机。不要再把 HTTP 或 JSON-RPC 请求返回视为“代码已生成”或“任务成功”。客户端应以会话的 state_update 和停止原因判断前台任务是否完成；模型网关则应记录实际的模型请求完成、取消或失败。二者分别统计，才能避免把“提示已接收”误算成推理成功。

2. 更新变成按 ID 的增量状态

v2 为消息、工具调用和计划提供更一致的更新语义：省略字段表示保持不变，null 表示清空，传值表示替换，内容块可以追加。消息 ID 成为必需项，文件变更也从简单的新旧文本转为能表达新增、删除、修改、移动、复制和二进制文件的结构化变化。

这对审计和界面都有直接影响。客户端应按稳定 ID 做幂等更新，而不是把每条事件当作完整快照覆盖；日志系统应保留事件顺序与最终状态，而不是只保存最后一段文本。对于成本治理，建议把一次模型请求的 token、缓存命中、供应商返回码和重试次数记在网关侧，再用 sessionId、taskId 关联回会话。这能避免流式事件重复写入时造成重复计量。

3. 权限请求与客户端能力边界更明确

v2 的权限请求有独立的标题、可选描述与可扩展的操作对象，而不是只能绑定一种固定工具调用。迁移指南还指出，v1 中由客户端提供的文件系统和终端执行 API 在 v2 被移除；当 Agent 需要客户端侧工具时，应使用客户端提供的 MCP Server。

这意味着权限策略需要按资源和动作设计，而不是按“这个 Agent 是否可信”做一次性放行。例如，读取当前仓库、运行测试、访问网络、修改部署配置，应当是不同的策略维度。模型网关负责的是谁可以调用哪类模型、预算是多少、是否允许跨区域或跨供应商；工具授权仍应该留在客户端与 MCP 的边界上。

一个可落地的迁移顺序

以下顺序适合已经有编程代理、但不想因协议草案增加生产风险的团队。

第一步：把 v2 当成可选能力，而不是全量切换

在 initialize 阶段协商协议版本。支持 v2 的客户端发送 protocolVersion: 2；当对端只支持 v1 时，继续使用 v1。为 v2 增加独立功能开关，并按客户端、仓库或测试人群逐步打开。不要因为代理和客户端都能解析 v2，就直接删除 v1 路径。

验收时至少覆盖四类组合：v1 客户端连 v1 Agent、支持 v2 的客户端回退连 v1 Agent、v1 客户端连同时支持两版的 Agent，以及 v2 客户端连 v2 Agent。再补一组长任务测试，观察取消、权限等待、断线恢复和后台状态更新是否都能收敛。

第二步：先改会话状态机，再改界面

将客户端状态拆成“提示已接受”“前台运行”“等待操作”“已空闲”几个明确状态。接收 session/update 时按 ID 合并消息、工具调用与计划；收到完成状态才关闭任务 UI 或写入任务结果。文件 diff 的展示可以随后升级，但底层结构应先能保存新增、删除、移动等事件。

这样处理的好处是，界面不必猜测代理是否还在工作，也不会把一条迟到的流式更新错误归到下一次任务。对于多窗口或会话恢复场景，恢复过程应以会话事件和稳定 ID 为准，而不是只依赖本地临时状态。

第三步：让模型网关保持协议无关

无论调用来自 ACP v1、ACP v2，还是非 ACP 的自动化任务，模型网关都应接收一份稳定的调用上下文，例如：

workspace / repository / sessionId / taskId / caller / requestedCapability / budgetPolicy

网关根据任务策略选择模型与供应商，施加速率和预算限制，并在可接受的质量边界内处理超时或失败切换。它不需要理解 session/update 的具体字段，也不应该根据 IDE 的某个事件猜测是否要收费。反过来，ACP 客户端也不应保存供应商 API Key 或把模型名称写死在界面逻辑中。

在这层记录统一的调用事件：请求模型、实际模型、输入与输出 token、缓存或批处理信息、延迟、结果类别、重试链路与归属标签。对有敏感代码或数据驻留要求的请求，再把允许的区域与供应商作为路由约束，而不是事后审计字段。

第四步：分别测试三类失败

协议、工具和模型的失败表现不同，排障与降级也不应共用一个笼统的“重试”。

失败类型	例子	处理重点
会话失败	客户端断连、版本不兼容、后台状态迟到	恢复会话、幂等消费事件、保留 v1 回退
工具失败	用户拒绝授权、MCP 工具超时、工具参数无效	让代理获得明确结果，避免把工具失败伪装成模型错误
模型失败	限流、供应商超时、预算耗尽、模型不可用	在网关按任务策略重试、切换或停止，并保留可解释记录

如果这三类事件都只显示为“Agent 失败”，团队就无法判断该升级协议、修复工具权限，还是调整模型路由。分层后的目标不是多建一套平台，而是让每一层的失败有可追踪的责任边界。

现在最值得做的三件事

列出当前客户端、Agent、MCP Server 与模型供应商的版本和连接方式，确认哪些组件真的需要 ACP v2，哪些只是通过网关调用模型。
在测试环境实现 v1/v2 版本协商、会话状态更新和结构化变更的幂等处理，重点验证长任务、取消、权限等待与恢复。
检查模型调用是否已经有独立的凭据、预算、路由和审计边界；若还由每个客户端直连供应商，先收敛这一层，再扩大协议升级范围。

ACP v2 还在草案阶段，因此不需要抢着把每个客户端迁到新版本。但它已经把一个事实说得很清楚：AI 编程代理将越来越像持续运行的开发工作负载。会话协议负责让人和代理可靠协作，工具协议负责让代理获得受控能力，模型网关负责让每一次推理在成本、可靠性和合规边界内发生。把这三件事分开，后续无论更换 IDE、接入新代理还是调整模型，都不必牵动整条链路。