教程2026-11-18 · 智涌AI

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

Agent Host Protocol 教程头图:左侧大字「Agent Host Protocol」与钩子「一个 Agent 会话,编辑器、手机、云端同步看」,三张数据卡为规范最新版 v1.1.0、6 种官方客户端库、MIT 开源许可;右侧终端面板演示 code agent endpoints、订阅 ahp-root、收到快照、派发 chat/turnStarted、收到带 serverSeq 的 action

在 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 等),几个概念:

概念含义
ChannelURI 标识、可订阅的资源,每个有一棵不可变状态树。服务端必须实现 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 是通信层」:

关注点AHPACP
多客户端核心目的,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 之间的通信。

想接入,从这几步开始

  1. 起一个 Host。终端里 code agent host 起一个独立版的 VS Code Agent Host;想看编辑器里那个 Host 的端点,用 code agent endpoints。
  2. 选客户端库。Rust(ahp)、TypeScript(@microsoft/agent-host-protocol)、Kotlin、Swift、.NET、Go 都有官方包;Rust、Swift、Go、.NET 带 MultiHostClient,能同时连多个 Host。
  3. 把自己的 Host 接进官方客户端。Copilot 应用里打开 Experimental > Direct Connections,再到 Environments > Add Agent Host Protocol Host;VS Code 里在 Agents 窗口用 Add Remote Agent Host。
  4. 参考现成实现。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 教程。

常见坑

完成标准

最后

先在终端跑一次 code agent endpoints,用 TypeScript 包连上编辑器自带的 Host,订阅 ahp-root:// 把快照打印出来,看清状态树的样子再决定要做客户端还是自己的 Host。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。