Skip to content
UHPUHPDeveloper Guide
Independent developer guide. Not affiliated with HarnessRouter or the official UHP project.

UHP vs AHP: execution APIs and shared agent-host state

UHP gives a product a common API for complete-harness execution. Microsoft's Agent Host Protocol gives clients a shared, host-authoritative view of agent sessions. Pick the boundary your application must own.

Page reviewed 4 Oct 2026 Source and review policy

Current guidance and dated source history

Recover shared state before issuing new actions

Section titled “Recover shared state before issuing new actions”

The freshly retrieved AHP spec/v1.0.0 release includes token-lifetime information and chat catalog/state changes previously discussed as unreleased below. Its versioned overview defines host-authoritative channels; UHP 2026-09-28 Draft defines execution resources. Review date: 4 October 2026.

Event after a disconnectAHP client responsibilityUHP integration consequence
Host publishes a fresh snapshotRebuild the observed channel state from the authoritative hostDo not infer that an outer Response is newly created
Ordered actions arriveApply host action envelopes in serverSeq orderKeep their ordering separate from UHP event sequence numbers
Authentication expiresRenew through the host’s documented authentication flowDo not widen server/object authorization while reconnecting
Compatibility negotiation succeedsUse the selected version and advertised capabilitiesDo not equate every channel’s maturity with protocol 1.0.0

AHP’s versioned reconnection contract sends clientId, lastSeenServerSeq and subscriptions to reconnect on ahp-root://. The host returns missed actions or fresh snapshots when the replay buffer cannot cover the gap. Drop subscriptions reported as missing; protocol notifications are not replayed, and stateless channels must be re-subscribed for live traffic.

Persist the host channel reference separately from the UHP execution identity. Recovered host state decides what the client displays; the UHP task lifecycle decides the outer outcome. Replaying a visible chat message is not a safe instruction to launch work again.

This recovery scenario is a design illustration. It does not establish a standard AHP↔UHP binding or that all language clients implement every published channel.

Resolve the name and version

Section titled “Resolve the name and version”

Here AHP is Microsoft’s Agent Host Protocol. Its latest published specification is spec/v1.0.0, released 2 October 2026. The comparison below uses UHP 2026-09-28 Draft. AHP’s language clients have independent release tracks; a Go-client tag or Swift-package tag must not be substituted for the specification tag.

Choose by state ownership

Section titled “Choose by state ownership”
Product requirementBetter starting pointWhy
Submit complete harness work from a service and collect resultsUHPIts contract centers on execution, response/session state and artifacts
Keep several clients synchronized on one agent sessionAHPAn authoritative host publishes snapshots and ordered channel actions
Connect an editor directly to a coding agentACPClient-to-agent interaction is its boundary
Combine remote execution with a shared interactive clientExplicit integration designIdentities, cancellation and state ownership need mapping

AHP 1.0.0 uses JSON-RPC over a reliable, ordered, bidirectional stream. Channels identify the resources being observed or acted on; initialization negotiates protocol versions. Its versioned overview distinguishes requests, notifications and host-sequenced actions. UHP’s HTTP resources and streamed execution events have a different object model.

What a composition must decide

Section titled “What a composition must decide”

An AHP host could use an execution backend behind a UHP server, or use ACP to communicate with an agent. Neither arrangement is implied by protocol publication. Before implementing, decide which layer owns workspace state, how a response maps to a chat turn, where approvals occur, and which retained state lets a client recover after disconnect.

Do not map an AHP channel URI directly to a UHP session identifier or present host automation runs as UHP Responses. Consult UHP lifecycle and the exact AHP channel contract, then test the mapping.

The preserved 0.9.0 discussion below records earlier evidence, including then-unreleased authentication changes and channel maturity. Those are historical statuses, not a claim that AHP is still pre-1.0.

Historical source notes — baseline reviewed 11 Sep 2026

The following evidence preserves the earlier review and its links. “Current”, “stable” and “main” inside this section refer to that historical cutoff; they are not new release or compatibility claims. Use the guidance above for the current scope.

The one-sentence difference

Section titled “The one-sentence difference”

UHP standardizes how a client asks a server to run a selected, configured complete harness. AHP standardizes how an authoritative agent host synchronizes shared session state across multiple clients.

That difference matters because the two protocols can both appear near an agent runtime without being substitutes. UHP’s abstraction boundary is client → UHP server → harness. AHP’s abstraction boundary is one or more clients → agent host → shared sessions, with the host free to use ACP or another agent-specific interface below it.

Current AHP status

Section titled “Current AHP status”

Microsoft’s Agent Host Protocol (AHP) repository describes AHP as a synchronized, multi-client state protocol for AI agent sessions. The project publishes a formal normative specification, generated schemas and client libraries for Rust, TypeScript, Kotlin, Go, Swift and .NET; the repository also identifies the VS Code agent host as its reference server implementation.

The latest published AHP specification observed in this review is 0.9.0, released 28 August 2026 under the tag spec/v0.9.0. AHP is still pre-1.0, so its versioning document explicitly allows breaking changes in minor releases. It also assigns stability per channel rather than treating the complete protocol surface as uniformly stable: Root, Session, Chat, Terminal, Telemetry and Resource Watch are currently marked Stable, while Changeset and MCP are Release Candidate, Annotations are Active Development, and Automation Catalogue / Automation Run are Early Development.

Checked AHP main is 0d6d98392b06d1e698e20b538e99e8ed1e304935 at this review cutoff. No later published specification version was found. The post-0.9.0 line includes live TypeScript session conformance for .NET and a material unreleased authentication change from PR #431; later commits through the checked tip are dependency/build maintenance rather than newer protocol semantics.

Post-0.9.0 current main: OAuth token lifetime reaches the host

Section titled “Post-0.9.0 current main: OAuth token lifetime reaches the host”

AHP PR #431 / commit fd0471d4 extends the unreleased current-main authentication surface with optional AuthenticateParams.expiresIn. The field carries the OAuth access token’s remaining lifetime in seconds at the moment the client sends authenticate, corresponding to OAuth 2.0 expires_in. When supplied it must be a positive integer. If the client retained the original token response, it must subtract elapsed time before forwarding the value; if the authorization server did not provide an expiry, or expiry is otherwise unknown, the client omits the field. An empty token still revokes authentication for the resource and should omit expiresIn.

The same change tightens expired-credential handling. When auth/required reports reason: "expired", the client must acquire or renew a credential before authenticating again and must not blindly replay the challenged token. AHP deliberately uses a relative lifetime rather than an absolute expiry timestamp so the client and host do not need synchronized clocks. The change was propagated through generated schemas and language clients.

VS Code now exposes the Agent Host as a concrete AHP runtime boundary

Section titled “VS Code now exposes the Agent Host as a concrete AHP runtime boundary”

By VS Code 1.136.1 (3 Sep 2026), Microsoft’s current product documentation describes the Agent Host as an active VS Code runtime surface rather than only a reference implementation in source. The host runs agent harnesses in a dedicated process, owns sessions independently of the windows that display them and lets an active turn continue while no client is attached, as long as the Agent Host itself remains running.

The implementation makes AHP’s transport and authority split concrete:

  • local VS Code clients use a message port to the Agent Host;
  • remote clients use AHP JSON-RPC over WebSocket;
  • the host is authoritative for session state and replays ordered channel actions or a fresh snapshot after reconnect;
  • a standalone host can be started with code agent host; it binds to localhost with a connection token by default, while --tunnel exposes it through a dev tunnel;
  • client-contributed tools remain possible, but baseline workspace/session capabilities live with the host so the runtime is not tied to one editor window.

Microsoft’s current Agent Host architecture documentation depicts first-party adapters for Copilot, Claude and Codex inside the host. The adapter boundary translates each runtime into the common AHP session model while preserving harness-specific behavior. Microsoft separately documents the Copilot harness as using the GitHub Copilot SDK and the Claude harness as using Anthropic’s Claude Agent SDK. Current VS Code harness documentation still labels Codex on Agent Host as Experimental, so its appearance in the host architecture must not be read as uniform maturity across all three adapters.

This is significant interoperability evidence for AHP itself: a mainstream editor now uses the protocol as the synchronization boundary between multiple clients and a persistent multi-harness host. It does not establish native UHP support for VS Code, Copilot, Claude or Codex, and it does not establish a HarnessRouter AHP backend.

Architectural comparison

Section titled “Architectural comparison”
DimensionUHPAHP
Primary boundaryProduct/client ↔ UHP server ↔ complete harnessMultiple clients ↔ authoritative agent host ↔ shared agent sessions
Main goalMake configured harness execution interchangeable behind one server contractKeep several clients synchronized on one authoritative session/state model
Work abstractionA Response is one task; Responses chain into a SessionChannels expose synchronized state; Chat carries turns, while Automation Run can represent task-level automation execution
State authorityServer owns UHP objects and reports harness-produced progress/resultsHost owns the authoritative state tree and sequences/reconciles client actions
Client multiplicityA client/server execution contract; multi-client shared-state arbitration is not its core abstractionExplicitly designed for N clients observing and participating in shared sessions
Message modelHTTP resources plus SSE event streamingBidirectional JSON-RPC 2.0 commands, responses, notifications and action envelopes
Routing modelResource endpoints and typed object identifiersEvery command/notification carries a top-level channel URI such as ahp-root://, ahp-session: or ahp-chat:
TransportHTTP over TLS; SSE for streamingTransport-agnostic reliable, ordered, bidirectional stream; WebSocket is the common/reference choice
ReconnectionUHP defines replayable task events and session/response continuationAHP sequences actions and provides reconnection/replay around the host’s shared state
Harness / agent boundaryServer-to-harness execution is implementation-definedAgent implementation is out of scope; an AHP host can use ACP or another backend interface
VersioningDate-based immutable protocol versionsSemVer with initialization-time version negotiation plus per-channel stability levels
Current reviewed version2026-08-11 DraftPublished spec 0.9.0 (28 Aug 2026); checked current main also carries unreleased post-0.9 auth semantics

Why AHP is a distinct interoperability layer

Section titled “Why AHP is a distinct interoperability layer”

AHP is not merely another client-to-agent RPC vocabulary. Its distinctive concern is shared state coordination. Every push-style interaction is scoped to a URI-identified channel, and the host sequences mutations against an authoritative state tree. That gives multiple clients a common view of sessions, chats, terminals, changesets, automation runs and other host resources.

The official AHP/ACP guide makes the layering explicit: ACP is a point-to-point communication layer between one client and one agent, while AHP is a coordination layer for multiple clients over shared agent sessions. An AHP host can translate an upstream AHP action into an ACP request, map ACP streaming updates back into AHP actions, assign server sequence numbers and broadcast the resulting shared state to subscribers.

This creates a useful three-way distinction:

  • UHP — product/client drives an interchangeable complete harness through a server.
  • AHP — multiple clients coordinate around host-authoritative shared agent sessions.
  • ACP — one client communicates directly with one agent process through a bidirectional agent interface.

Those boundaries can compose, but composition does not merge their semantics.

AHP 0.9.0 makes the overlap easier to see

Section titled “AHP 0.9.0 makes the overlap easier to see”

AHP 0.9.0 added Automation Catalogue and Automation Run channels. An automation run has its own lifecycle (pending, running, terminal states), durable trigger/manual origin, linked session catalogue and optional primary session. The host records the run before external side effects and records linked session URIs before sending their first message; retrying the automation command with the same request id returns the existing run URI.

That is real task-lifecycle machinery, but it is not the same object model as UHP. In AHP, the automation run coordinates host-managed workflow/session state and linked ahp-session: / ahp-chat: channels remain authoritative for conversation and tool activity. In UHP, a Response itself is one harness task, and continuation creates a server-owned Session chain through previous_response_id.

AHP 0.9.0 also made turn errors durable response parts and added resumable errors through chat/turnResume. These are AHP chat/session semantics; they do not redefine UHP’s failed, incomplete, continuation or response lifecycle.

Where the protocols can coexist

Section titled “Where the protocols can coexist”

A product architecture could use these layers independently or together. For example, an IDE-facing host might use AHP to synchronize several front ends around the same agent session while a separate backend service uses UHP to launch work on configured harnesses. A bridge could also be built between them, but such a bridge would need an explicit mapping for task identity, session ownership, cancellation, streaming, files/artifacts and authority; the protocols do not define that mapping for each other.

No primary source reviewed here establishes a standardized UHP ↔ AHP binding, HarnessRouter support for AHP, or native UHP adoption by Microsoft’s AHP/VS Code implementation. Likewise, AHP’s documented ability to use ACP below the host does not make ACP part of UHP.

What not to infer

Section titled “What not to infer”
Section titled “Related pages”

See UHP architecture, harness composition, UHP vs ACP, UHP vs MCP and UHP vs A2A for the neighboring boundaries.

Primary sources

Section titled “Primary sources”