Specification Overview

This section contains the formal specification of the Agent Host Protocol (AHP). It defines the normative requirements for compliant implementations.

Status

DRAFT

This specification is a working draft and is under active development. Breaking changes to wire types, actions, and state shapes are expected. Do not rely on backward compatibility until the protocol reaches production status.

Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in RFC 2119.

Protocol Version

The current protocol version is 1. The version is a single integer that increments when new features require capability negotiation or behavioral semantics change.

Version history:
  1 — Initial: core session lifecycle, streaming, tools, permissions

See Versioning for the full version strategy.

Base Protocol

AHP uses JSON-RPC 2.0 as its message framing over the transport (WebSocket, MessagePort, etc.).

Message Categories

Direction	Type	Examples
Client → Server (notification)	Fire-and-forget	unsubscribe, dispatchAction
Client → Server (request)	Expects a response	initialize, reconnect, subscribe, createSession, disposeSession, listSessions, fetchTurns, resourceRead, resourceWrite, resourceList, resourceCopy, resourceDelete, resourceMove
Server → Client (notification)	Pushed	action, notification
Server → Client (response)	Correlated by id	Success result or JSON-RPC error

Requests

A JSON-RPC request has an id and a method. The server MUST respond with exactly one response carrying the same id.

{ "jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": { "resource": "agenthost:/root" } }

Responses

A success response:

{ "jsonrpc": "2.0", "id": 1, "result": { "resource": "...", "state": { ... }, "fromSeq": 5 } }

An error response:

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32603, "message": "No agent for provider" } }

Notifications

A JSON-RPC notification has a method but no id. It MUST NOT receive a response.

{ "jsonrpc": "2.0", "method": "action", "params": { "envelope": { ... } } }

Structure

The specification is organized into the following sections:

• Transport — How messages are delivered between client and server.
• Lifecycle — How connections are established and sessions are managed.
• Subscriptions — URI-based state subscription mechanism.
• Versioning — Protocol version negotiation and compatibility.
• State Types — Complete state type definitions.
• Actions — Complete action type definitions.
• Commands — Available RPC commands.
• Messages — Complete list of JSON-RPC methods.
• Notifications — Ephemeral event broadcasts.
• Error Codes — Application-specific error codes.

JSON Schema

Machine-readable JSON Schema (2020-12) definitions are published for all protocol types:

Schema	Description
state.schema.json	State types
actions.schema.json	Action types
commands.schema.json	Command parameters and results
notifications.schema.json	Notification types
errors.schema.json	Error codes

These schemas are generated from the TypeScript type definitions and can be used for validation, code generation, or editor support.