# Agent Host Protocol (AHP) The Agent Host Protocol (AHP) is an open protocol from [[Microsoft]] that lets many clients attach to the same AI agent session at once. Tagline: "Synchronized multi-client state for AI agent sessions." It comes from the [[Visual Studio Code (VSCode)]] team (the .NET package is called `Microsoft.VisualStudioCode.AgentHostProtocol`), and VS Code's built-in agent host is the reference server. MIT license. The repository was created on 2026-03-12, has around 385 GitHub stars, and shipped **v1.0.0 on 2026-10-02** after a string of 0.x releases. ## Sessions are stuck where they started That's the project's own one-liner: "An agent session is stuck wherever it started." Start a session in your IDE and the conversation, the turns and the pending tool approvals all live inside that app. Switch to your phone, a browser tab, a CLI or a script, and you can't pick up the same live session. You start over, or you copy context around by hand. AHP moves the session to a host. It lives there once, and any client can drive it. Once agents run for hours, the hard part is knowing where each session lives and which one is waiting for an approval; AHP makes that a protocol concern. [[OpenHarness]] goes after the same problem as a product, with its own daemon and transport. ## One host, many clients, many agents - Clients (IDE, web, CLI, mobile) speak AHP to the host - The host owns the authoritative session state, orders every change and handles reconciliation - Agents sit behind the host: [[GitHub Copilot]], [[Claude Code|Claude]], [[OpenAI Codex|Codex]], or any [[Agent Client Protocol (ACP)|ACP]] agent Clients never see agent-specific details. The host translates whatever the agent emits into generic actions (`chat/delta`, `chat/toolCallStart`, ...), so any client can drive any agent. The docs put it "in the lineage of LSP and DAP", the same Microsoft move as the [[Language Server Protocol (LSP)]] and the Debug Adapter Protocol. Like them, it runs on JSON-RPC 2.0 and doesn't mandate a transport: anything reliable, ordered and bidirectional works. In practice that's [[WebSockets|WebSocket]], which is what VS Code uses. ## How it works Think Redux-style state management, over the network. - **Channels.** Everything lives on a URI-addressed channel: the root catalogue (`ahp-root://`), each session, chat, terminal and changeset. Every message carries its `channel`, so a server, client or proxy can route it without parsing the rest - Each channel holds an immutable state tree. Only actions change it, through a pure reducer `(state, action) → newState` that runs identically on host and client - The host stamps each action with a monotonic sequence number (`serverSeq`) and broadcasts it to every subscribed client. In the docs' words: "Every change is one envelope, totally ordered." That one ordered stream keeps every window in sync - Subscribing to a channel gets you a snapshot of its current state, then the action envelopes that follow. Large content (images, long tool outputs) is stored by reference and fetched lazily - **Write-ahead reconciliation.** A client applies its own action locally right away (optimistic UI), keeps it in a pending list, and drops it when the host echoes it back. It spots its own echo through the `origin` field (client id + client sequence). Foreign actions go onto the confirmed state and pending ones are replayed on top. Rejected actions come back with a `rejectionReason` and get rolled back - Most chat actions are append-only, so rebasing is trivial. When two clients cancel the same turn or approve the same tool call, the host settles it: first one wins, the others are rejected - A reconnecting client sends `lastSeenServerSeq` and gets the missed actions replayed, or a fresh snapshot if the gap is bigger than the host's replay buffer - Clients offer the protocol versions they support, the host picks one, and clients check capabilities before using a feature, so smaller implementations keep working The docs' mental model: **AHP is a mutex over ACP.** One turn runs at a time per chat, everyone sees who holds it, and any client can cancel or approve, exactly once. ## How it differs from ACP, MCP and A2A These four get lumped together as "agent protocols", but each one connects different things. | Protocol | Connects | Question it answers | |---|---|---| | [[Model Context Protocol (MCP)\|MCP]] | Agent ↔ tools and data | What can this agent use? | | [[Agent Client Protocol (ACP)\|ACP]] | One client ↔ one agent | How does an editor talk to an agent? | | [[Agent2Agent Protocol (A2A)\|A2A]] | Agent ↔ agent | How do agents delegate to each other? | | **AHP** | Many clients ↔ one host (which wraps agents) | How do N clients share the same live session? | - **vs ACP.** ACP is point-to-point: one client drives one agent, and the agent holds the session state. AHP sits above it; the host speaks AHP to clients and can speak ACP to agents. From the docs: "AHP is a coordination layer. ACP is a communication layer. They compose naturally." ACP has nothing for multiple clients, replay or reconnection, and AHP builds all three in - **vs MCP.** AHP doesn't redefine MCP. MCP servers show up in AHP state only as display data (name, status, auth needs) so clients can render them; connecting to them stays inside the agent harness - **vs A2A.** Agent-to-agent coordination is an explicit anti-goal. AHP only coordinates clients ## Ecosystem - **Client libraries:** Rust, TypeScript, Kotlin, Go, Swift and .NET. Rust, Swift, Go and .NET ship a `MultiHostClient` to talk to several hosts at once - **Servers:** the VS Code agent host (reference), `pi-ahp` (exposes [[Pi Mono|pi]] sessions over WebSocket) and `ahpd` (plugin-based host with an SDK to build your own) - **Other clients:** VS Code's built-in Agent Sessions view, `ahpx` (CLI + Node client), `ahpc` (terminal client), and a VS Code extension that connects WeChat to a local agent host chat ## My take Microsoft did this before with LSP and DAP: move the heavy logic out of the editor into its own process, define a boring JSON-RPC contract, and let every UI plug in. With LSP it was language intelligence. This time it's the agent session. The design is old-school: one authoritative host, a totally ordered log, pure reducers, optimistic UI with server-wins reconciliation. No CRDTs. Chat is mostly append-only, so they don't need them, and I like that they started simple. The open question is adoption outside VS Code. Today the only serious host is Microsoft's, plus a few community projects. If agent CLIs ([[Claude Code]], [[OpenAI Codex|Codex]]) or tools like [[OpenHarness]] start exposing AHP hosts, "continue this session on my phone" becomes a protocol feature instead of a vendor feature. That would remove one more reason to stay locked into a single agent vendor. ## References - Documentation: https://microsoft.github.io/agent-host-protocol/ - What is AHP: https://microsoft.github.io/agent-host-protocol/guide/what-is-ahp - AHP and ACP: https://microsoft.github.io/agent-host-protocol/guide/ahp-and-acp - Doctrine: https://microsoft.github.io/agent-host-protocol/guide/doctrine - Write-ahead reconciliation: https://microsoft.github.io/agent-host-protocol/guide/reconciliation - Specification: https://microsoft.github.io/agent-host-protocol/specification/overview - GitHub repository: https://github.com/microsoft/agent-host-protocol - v1.0.0 release (2026-10-02): https://github.com/microsoft/agent-host-protocol/releases/tag/v1.0.0 - Repository files read (2026-10-04): `README.md`, `docs/guide/{what-is-ahp,ahp-and-acp,doctrine,reconciliation,mcp}.md`, `docs/specification/{overview,transport}.md`, `docs/.vitepress/theme/components/HomeWalkthrough.vue` (home page walkthrough text) ## Related - [[Agent Client Protocol (ACP)]] - [[Model Context Protocol (MCP)]] - [[Agent2Agent Protocol (A2A)]] - [[Language Server Protocol (LSP)]] - [[Visual Studio Code (VSCode)]] - [[Microsoft]] - [[GitHub Copilot]] - [[Claude Code]] - [[OpenAI Codex]] - [[OpenHarness]] - [[Pi Mono]] - [[AI Agents]] - [[AI Agent Harness]] - [[WebSockets]] - [[Claude Code Remote Control]] - [[Claude Managed Agents Sessions]] - [[Kanbots]]