Agent Host Protocol 是什么:一个 Agent 会话多端同步

在 VS Code 里让 Agent 跑一个长任务,关掉窗口它就停了;换台电脑、换到手机,又得重新开。微软和 GitHub 用来解决这件事的是 Agent Host Protocol(AHP):一个独立进程托管 Agent 会话,编辑器、Copilot 应用、手机、网页都当客户端连上去,看到的是同一个实时会话。GitHub 工程博客 11 月 17 日写了它的设计过程,协议本身在 microsoft/agent-host-protocol 开源(MIT),规范最新版 v1.1.0。这篇讲清 AHP 管什么、不管什么,跟 ACP 怎么分工,以及想接入时从哪几条命令开始。
为什么需要一个协议
GitHub Copilot 最早是 VS Code 里的一个扩展,自带 harness。扩展挂在单个窗口上:关窗口 Agent 就没了,VS Code 一更新所有 Agent 都停,连远程机器又是一个和本地版本绑死的新扩展宿主。同一时期 Copilot 应用、GitHub 的 iOS 和 Android 应用也各自做了一套接云端 Agent 的集成。
每个产品都解决了自己的问题,但开发者想把 Agent 拉进自己的编辑器、终端、手机或者自己写的工具,就得一家家对接。AHP 就是那门共同语言:独立版本号,所有客户端看到同样的 Agent、历史和状态。
VS Code 8 月起在 Stable 和 Insiders 里启用了 Agent Host:它是一个独立进程,本地时作为 VS Code 的 utility process 运行,远程时作为独立服务器,跨多个编辑器会话一直活着。你在编辑器窗口里开的会话,可以在 Agents 窗口接着用同一个,不是复制一份。
协议长什么样
AHP 跑在 JSON-RPC 上(传输可以是 WebSocket、MessagePort 等),几个概念:
| 概念 | 含义 |
|---|---|
| Channel | URI 标识、可订阅的资源,每个有一棵不可变状态树。服务端必须实现 root、session、chat 三种,终端、changeset、遥测等可选 |
| Snapshot | 订阅时先拿到的当前状态,带 fromSeq |
| Action | 改状态的唯一方式,类似 Redux;服务端给每个 action 编 serverSeq 广播给所有订阅者 |
| Reducer | 纯函数 (state, action) → newState,服务端和客户端跑同一套 |
| Command | 命令式 RPC,比如 createSession、listSessions |
常用的 channel URI:ahp-root://(Agent 列表、终端、主机配置,永远存在)、ahp-session:/<uuid>(会话元数据和它的聊天列表)、ahp-chat:/<id>(一次聊天的轮次、流式输出、工具调用、待审批输入和变更集)、ahp-terminal:/<id>。有一条硬规则:每个请求和通知的 params 里都必须带 channel,所以服务端、客户端、中间代理只看 method 加 params.channel 就能路由。
按官方 Getting Started,发一条消息的流程是:
// 1. 握手,顺便订阅 root 和上次开着的会话
initialize(channel: 'ahp-root://', protocolVersions[], clientId, initialSubscriptions?)
// 2. 建会话并订阅;快照里 lifecycle 先是 'creating',就绪后收到 session/ready
{"method": "createSession", "params": {"channel": "ahp-session:/<uuid>", "provider": "copilot"}}
{"method": "subscribe", "params": {"channel": "ahp-session:/<uuid>"}}
// 3. 订阅默认 chat,派发一个 turn(客户端先本地乐观应用)
{"method": "dispatchAction", "params": {
"channel": "ahp-chat:/<cid>", "clientSeq": 1,
"action": {"type": "chat/turnStarted", "turnId": "turn-1",
"message": {"text": "Explain this code", "origin": {"kind": "user"}}}}}
服务端回广播的 action 通知里带 serverSeq 和 origin(哪个客户端、第几个 clientSeq),客户端据此对账。这就是规范里说的 write-ahead reconciliation:网络差的时候客户端先把排队的 action 发出去,显示加载状态,等服务端确认再落定;断线重连时带上最后看到的 serverSeq,补收漏掉的 action。
按 GitHub 博客的说法,Agent 这一块变得太快,所以 AHP 刻意不规定 Agent 怎么工作,只规定你怎么和它交互。
跟 ACP 怎么分工
Agent Client Protocol(ACP)定义一个客户端怎么跟一个编程 Agent 对话:初始化、认证、提示、流式更新、工具调用、权限,是点对点的。AHP 官方文档的定位是「AHP 是协调层,ACP 是通信层」:
| 关注点 | AHP | ACP |
|---|---|---|
| 多客户端 | 核心目的,N 个客户端看同一份状态 | 不涉及,假定一个客户端 |
| 状态归属 | Host 持有权威状态树,客户端对账 | Agent 持有会话状态 |
| 排序 | serverSeq 顺序的 action | 请求-响应加流式通知 |
| 断线重放 | 内置,带 lastSeenServerSeq 重连 | 协议层未规定 |
一个 Host 可以上面讲 AHP、下面用 ACP 接 Claude Code 这类 Agent。多客户端同时操作时由 Host 仲裁:一个 chat 同时只跑一个 turn;工具调用要审批时任何客户端都能批,但只算第一个 chat/toolCallConfirmed;任何客户端都能取消正在跑的 turn。文档里有个比喻:AHP 是套在 ACP 外面的一把互斥锁。
AHP 明确不管的:Agent 怎么处理提示、怎么管上下文;模型路由(Host 只在 root 状态里列出可用 Agent 和模型);工具注册和 schema;Agent 之间的通信。
想接入,从这几步开始
- 起一个 Host。终端里
code agent host起一个独立版的 VS Code Agent Host;想看编辑器里那个 Host 的端点,用code agent endpoints。 - 选客户端库。Rust(
ahp)、TypeScript(@microsoft/agent-host-protocol)、Kotlin、Swift、.NET、Go 都有官方包;Rust、Swift、Go、.NET 带MultiHostClient,能同时连多个 Host。 - 把自己的 Host 接进官方客户端。Copilot 应用里打开 Experimental > Direct Connections,再到 Environments > Add Agent Host Protocol Host;VS Code 里在 Agents 窗口用 Add Remote Agent Host。
- 参考现成实现。README 列了社区的客户端和服务端,比如终端客户端 ahpc、Web 客户端 ahpw、给 pi 编程 Agent 用的 pi-ahp、把 ACP Agent 包成 AHP Host 的 AHP-ACP Gateway,还有把微信接到本地 Agent Host 聊天的 VS Code 扩展。
GitHub 博客提到,作者桌上有个小键盘实时显示 Agent 状态,也有人做了手表应用和看板式任务工具。VS Code 那一侧怎么用 Agents 窗口和后台会话,见站内 VS Code 1.146 Inbox 教程。
常见坑
- 把 AHP 当成 Agent 框架。它只同步会话状态,Agent 的推理、工具、上下文管理还得靠你选的 harness。
- 订阅不认识的 scheme。规范要求客户端不得订阅自己不理解的 URI scheme;遇到不认识的快照格式要忽略而不是报错,新版本会加新 channel。
- 以为通知会重放。普通投递下,
root/sessionAdded这类协议通知断线后不补发,重连后要靠 channel 状态或listSessions拿最新数据。 - 终端输出把客户端冲垮。产出很快的 channel(比如终端)用 windowed delivery,按 credit 收,别一股脑接。
完成标准
- 能说出 root、session、chat 三个必选 channel 各装什么。
- 客户端处理了乐观应用、按
serverSeq对账和断线重连三件事。 - 自己的 Host 能被 VS Code 或 Copilot 应用作为远程 Agent Host 连上。
最后
先在终端跑一次 code agent endpoints,用 TypeScript 包连上编辑器自带的 Host,订阅 ahp-root:// 把快照打印出来,看清状态树的样子再决定要做客户端还是自己的 Host。