# microsoft/agent-host-protocol architecture

> Architecture diagram of the GitHub repository microsoft/agent-host-protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/agent-host-protocol
- Repository: https://github.com/microsoft/agent-host-protocol

## Overview

Agent Host Protocol is a family of client SDKs and shared protocol definitions for synchronizing AI-agent session state between portable servers and multiple clients. The principal workflow is a client connecting to a host, sending protocol commands, and receiving channel state and events; SDKs also support subscriptions, reconnection, and—in several languages—multi-host coordination. The graph highlights the TypeScript and .NET client flows shown in source, plus major protocol-state domains and other documented SDKs. Some language implementations and domain modules are represented from the README or file tree rather than inspected source.

Main entry points: [`types/common/state.ts`](https://github.com/microsoft/agent-host-protocol/blob/main/types/common/state.ts) (Common state), [`types/channels-session/state.ts`](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-session/state.ts) (Session state), [`clients/typescript/src/client/client.ts`](https://github.com/microsoft/agent-host-protocol/blob/main/clients/typescript/src/client/client.ts) (TypeScript client), [`types/channels-root/state.ts`](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-root/state.ts) (Root state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol Model"]
  node_common_commands["Common commands<br/>[commands.ts]"]
  node_common_state["Common state<br/>[state.ts]"]
  node_common_actions["Common actions<br/>[actions.ts]"]
end

subgraph group_client["Client SDKs"]
  node_ts_client["TypeScript client<br/>[client.ts]"]
  node_ts_transport["TypeScript transport<br/>[transport.ts]"]
  node_dotnet_client[".NET client<br/>[AhpClient.cs]"]
  node_dotnet_transport[".NET transport<br/>[ITransport.cs]"]
  node_rust_client["Rust client<br/>[client.rs]"]
  node_go_client["Go client<br/>[client.go]"]
  node_swift_client["Swift client<br/>[AHPClient.swift]"]
  node_kotlin_client["Kotlin client<br/>[Ahp.kt]"]
end

subgraph group_hosts["Host Coordination"]
  node_dotnet_multi[".NET multi-host<br/>[MultiHostClient.cs]"]
  node_swift_multi["Swift multi-host"]
end

subgraph group_domains["State Domains"]
  node_root_state["Root state<br/>[state.ts]"]
  node_session_state["Session state<br/>[state.ts]"]
  node_chat_state["Chat state<br/>[state.ts]"]
  node_changeset_state["Changeset state<br/>[state.ts]"]
  node_automation_state["Automation state<br/>[state.ts]"]
  node_automation_run["Automation runs<br/>[state.ts]"]
  node_terminal_state["Terminal state<br/>[state.ts]"]
end

node_consumer(("Client application"))
node_host["AHP server"]

node_consumer -->|"uses SDK"| node_ts_client
node_ts_client -->|"sends commands"| node_host
node_host -->|"sends updates"| node_ts_client
node_ts_client -->|"decodes frames"| node_ts_transport
node_ts_client -->|"implements protocol"| node_common_commands
node_dotnet_client -->|"sends frames"| node_dotnet_transport
node_dotnet_client -->|"communicates with"| node_host
node_rust_client -->|"communicates with"| node_host
node_go_client -->|"communicates with"| node_host
node_swift_client -->|"communicates with"| node_host
node_kotlin_client -->|"communicates with"| node_host
node_common_commands -->|"references types"| node_common_state
node_common_actions -->|"references types"| node_common_state
node_root_state -->|"uses types"| node_common_state
node_root_state -->|"uses types"| node_session_state
node_root_state -->|"uses types"| node_terminal_state
node_session_state -->|"uses types"| node_common_state
node_session_state -->|"uses types"| node_chat_state
node_session_state -->|"uses types"| node_changeset_state
node_session_state -->|"uses types"| node_automation_state
node_session_state -->|"uses types"| node_automation_run
node_chat_state -->|"uses types"| node_common_state
node_chat_state -->|"uses types"| node_changeset_state
node_changeset_state -->|"uses types"| node_common_state
node_automation_state -->|"uses types"| node_common_state
node_automation_state -->|"uses types"| node_automation_run
node_automation_run -->|"uses types"| node_common_state
node_terminal_state -.->|"uses types"| node_common_state
node_consumer -->|"uses SDK"| node_dotnet_multi
node_consumer -->|"uses SDK"| node_swift_multi
node_dotnet_multi -->|"manages clients"| node_dotnet_client
node_swift_multi -->|"manages clients"| node_swift_client

click node_common_commands "https://github.com/microsoft/agent-host-protocol/blob/main/types/common/commands.ts"
click node_common_state "https://github.com/microsoft/agent-host-protocol/blob/main/types/common/state.ts"
click node_common_actions "https://github.com/microsoft/agent-host-protocol/blob/main/types/common/actions.ts"
click node_root_state "https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-root/state.ts"
click node_session_state "https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-session/state.ts"
click node_chat_state "https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-chat/state.ts"
click node_changeset_state "https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-changeset/state.ts"
click node_automation_state "https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-automation/state.ts"
click node_automation_run "https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-automation-run/state.ts"
click node_terminal_state "https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-terminal/state.ts"
click node_ts_client "https://github.com/microsoft/agent-host-protocol/blob/main/clients/typescript/src/client/client.ts"
click node_ts_transport "https://github.com/microsoft/agent-host-protocol/blob/main/clients/typescript/src/client/transport.ts"
click node_dotnet_client "https://github.com/microsoft/agent-host-protocol/blob/main/clients/dotnet/src/AgentHostProtocol/AhpClient.cs"
click node_dotnet_transport "https://github.com/microsoft/agent-host-protocol/blob/main/clients/dotnet/src/AgentHostProtocol.Abstractions/Transport/ITransport.cs"
click node_rust_client "https://github.com/microsoft/agent-host-protocol/blob/main/clients/rust/crates/ahp/src/client.rs"
click node_go_client "https://github.com/microsoft/agent-host-protocol/blob/main/clients/go/ahp/client.go"
click node_swift_client "https://github.com/microsoft/agent-host-protocol/blob/main/clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/AHPClient.swift"
click node_kotlin_client "https://github.com/microsoft/agent-host-protocol/blob/main/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/Ahp.kt"
click node_dotnet_multi "https://github.com/microsoft/agent-host-protocol/blob/main/clients/dotnet/src/AgentHostProtocol/Hosts/MultiHostClient.cs"
click node_swift_multi "https://github.com/microsoft/agent-host-protocol/blob/main/clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/Hosts/MultiHostClient.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_common_commands,node_common_state,node_common_actions,node_consumer toneBlue
class node_ts_client,node_ts_transport,node_dotnet_client,node_dotnet_transport,node_rust_client,node_go_client,node_swift_client,node_kotlin_client toneAmber
class node_dotnet_multi,node_swift_multi,node_host toneMint
class node_root_state,node_session_state,node_chat_state,node_changeset_state,node_automation_state,node_automation_run,node_terminal_state toneRose
```

## Components

### Protocol Model

- [Common commands](https://github.com/microsoft/agent-host-protocol/blob/main/types/common/commands.ts): `types/common/commands.ts`
- [Common state](https://github.com/microsoft/agent-host-protocol/blob/main/types/common/state.ts): `types/common/state.ts`
- [Common actions](https://github.com/microsoft/agent-host-protocol/blob/main/types/common/actions.ts): `types/common/actions.ts`

### Client SDKs

- [TypeScript client](https://github.com/microsoft/agent-host-protocol/blob/main/clients/typescript/src/client/client.ts): `clients/typescript/src/client/client.ts`
- [TypeScript transport](https://github.com/microsoft/agent-host-protocol/blob/main/clients/typescript/src/client/transport.ts): `clients/typescript/src/client/transport.ts`
- [.NET client](https://github.com/microsoft/agent-host-protocol/blob/main/clients/dotnet/src/AgentHostProtocol/AhpClient.cs): `clients/dotnet/src/AgentHostProtocol/AhpClient.cs`
- [.NET transport](https://github.com/microsoft/agent-host-protocol/blob/main/clients/dotnet/src/AgentHostProtocol.Abstractions/Transport/ITransport.cs): `clients/dotnet/src/AgentHostProtocol.Abstractions/Transport/ITransport.cs`
- [Rust client](https://github.com/microsoft/agent-host-protocol/blob/main/clients/rust/crates/ahp/src/client.rs): `clients/rust/crates/ahp/src/client.rs`
- [Go client](https://github.com/microsoft/agent-host-protocol/blob/main/clients/go/ahp/client.go): `clients/go/ahp/client.go`
- [Swift client](https://github.com/microsoft/agent-host-protocol/blob/main/clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/AHPClient.swift): `clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/AHPClient.swift`
- [Kotlin client](https://github.com/microsoft/agent-host-protocol/blob/main/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/Ahp.kt): `clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/Ahp.kt`

### Host Coordination

- [.NET multi-host](https://github.com/microsoft/agent-host-protocol/blob/main/clients/dotnet/src/AgentHostProtocol/Hosts/MultiHostClient.cs): `clients/dotnet/src/AgentHostProtocol/Hosts/MultiHostClient.cs`
- [Swift multi-host](https://github.com/microsoft/agent-host-protocol/blob/main/clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/Hosts/MultiHostClient.swift): `clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/Hosts/MultiHostClient.swift`

### State Domains

- [Root state](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-root/state.ts): `types/channels-root/state.ts`
- [Session state](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-session/state.ts): `types/channels-session/state.ts`
- [Chat state](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-chat/state.ts): `types/channels-chat/state.ts`
- [Changeset state](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-changeset/state.ts): `types/channels-changeset/state.ts`
- [Automation state](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-automation/state.ts): `types/channels-automation/state.ts`
- [Automation runs](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-automation-run/state.ts): `types/channels-automation-run/state.ts`
- [Terminal state](https://github.com/microsoft/agent-host-protocol/blob/main/types/channels-terminal/state.ts): `types/channels-terminal/state.ts`

### Other components

- **Client application**
- **AHP server**

## Connections

- Client application → TypeScript client: uses SDK (evidence: `README.md`)
- TypeScript client → AHP server: sends commands (evidence: `README.md`)
- AHP server → TypeScript client: sends updates (evidence: `README.md`)
- TypeScript client → TypeScript transport: decodes frames (evidence: `clients/typescript/src/client/client.ts`)
- TypeScript client → Common commands: implements protocol (evidence: `README.md`)
- .NET client → .NET transport: sends frames (evidence: `clients/dotnet/src/AgentHostProtocol/AhpClient.cs`)
- .NET client → AHP server: communicates with (evidence: `README.md`)
- Rust client → AHP server: communicates with (evidence: `README.md`)
- Go client → AHP server: communicates with (evidence: `README.md`)
- Swift client → AHP server: communicates with (evidence: `README.md`)
- Kotlin client → AHP server: communicates with (evidence: `README.md`)
- Common commands → Common state: references types (evidence: `types/common/commands.ts`)
- Common actions → Common state: references types
- Root state → Common state: uses types (evidence: `types/channels-root/state.ts`)
- Root state → Session state: uses types (evidence: `types/channels-root/state.ts`)
- Root state → Terminal state: uses types (evidence: `types/channels-root/state.ts`)
- Session state → Common state: uses types (evidence: `types/channels-session/state.ts`)
- Session state → Chat state: uses types (evidence: `types/channels-session/state.ts`)
- Session state → Changeset state: uses types (evidence: `types/channels-session/state.ts`)
- Session state → Automation state: uses types (evidence: `types/channels-session/state.ts`)
- Session state → Automation runs: uses types (evidence: `types/channels-session/state.ts`)
- Chat state → Common state: uses types (evidence: `types/channels-chat/state.ts`)
- Chat state → Changeset state: uses types (evidence: `types/channels-chat/state.ts`)
- Changeset state → Common state: uses types (evidence: `types/channels-changeset/state.ts`)
- Automation state → Common state: uses types (evidence: `types/channels-automation/state.ts`)
- Automation state → Automation runs: uses types (evidence: `types/channels-automation/state.ts`)
- Automation runs → Common state: uses types (evidence: `types/channels-automation-run/state.ts`)
- Terminal state → Common state: uses types (evidence: `types/channels-terminal/state.ts`)
- Client application → .NET multi-host: uses SDK (evidence: `README.md`)
- Client application → Swift multi-host: uses SDK (evidence: `README.md`)
- .NET multi-host → .NET client: manages clients (evidence: `clients/dotnet/src/AgentHostProtocol/Hosts/MultiHostClient.cs`)
- Swift multi-host → Swift client: manages clients (evidence: `clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/Hosts/MultiHostClient.swift`)
