Agent Host Protocol(AHP) 아키텍처 해부: URI 기반 상태 채널·Write-Ahead Reconciliation·ACP 브리지("Mutex over ACP")와 1.1.0 Windowed Delivery 경계 점검하기
2026년 11월 17일 GitHub과 Microsoft가 오픈소스(MIT)로 공개한 Agent Host Protocol(microsoft/agent-host-protocol, v1.0.0·v1.1.0)의 내부 아키텍처를 분석한다. 에디터 창에 묶인 1:1 에이전트 세션을 독립 호스트 서버로 분리하는 이유, 12종 URI 채널과 (method, params.channel) 라우팅 불변식, 순수 리듀서 기반 Write-Ahead Reconciliation 및 reconnect(replay vs snapshot) 복구, ACP·MCP와의 3계층 조합("AHP is a mutex over ACP"), 1.1.0 Windowed Delivery 흐름 제어 및 인증·알림 비재전송 경계와 로컬 Python 6대 검증 스크립트를 정리한다.
단일 에이전트 호스트 코어를 중심으로 IDE·터미널·모바일·웹 클라이언트가 동기화되고 하위 에이전트 런타임과 연결되는 개념 추상 아트워크
2026년 11월 17일 GitHub과 Microsoft가 공식 블로그(Building the Agent Host Protocol for sessions that continue across devices)를 통해 오픈소스(MIT) 표준 프로토콜 Agent Host Protocol(AHP)(github.com/microsoft/agent-host-protocol)을 공개했다. 그동안 코딩 에이전트 세션은 특정 IDE 창이나 단일 CLI 프로세스 수명에 묶여 있어 창을 닫거나 기기를 바꾸면 진행 중인 작업 맥락이 끊기는 한계가 있었는데, AHP는 에이전트 세션을 독립적인 Agent Host 서버로 분리해 데스크톱 IDE·모바일·웹·터미널(ahpc) 등 여러 클라이언트가 하나의 세션을 동시에 실시간 관측·제어할 수 있도록 설계되었다.
핵심 아키텍처와 실무 도입 기준을 먼저 요약하면, AHP는 JSON-RPC 2.0(주로 WebSocket 텍스트 프레임) 위에서 동작하는 상태 우선(State-first)·호스트 권위(Host-authoritative) 다중 클라이언트 동기화 프로토콜이다. 모든 구독과 명령은 12종의 URI 식별 채널(ahp-root://, ahp-session:/<uuid>, ahp-chat:/<cid>, ahp-terminal:/<id> 등)을 단위로 격리되며, 모든 요청·알림의 params 최상위에 channel URI를 포함시켜 프록시·서버가 역직렬화 없이 (method, params.channel)만으로 라우팅한다. 클라이언트는 confirmedState 위에 미확인 액션(pendingActions[])을 순수 리듀서((state, action) -> newState)로 낙관적 적용(optimisticState)하고, 서버가 부여한 serverSeq 에코 또는 rejectionReason을 받아 Write-Ahead Reconciliation으로 수렴한다. 다만 AHP는 도구 연동 표준인 MCP나 1:1 에이전트-에디터 프로토콜인 ACP를 대체하지 않으며, 에이전트 프롬프트·모델 라우팅·전송 계층 인증(WebSocket 핸드셰이크)은 의도적으로 프로토콜 범위 밖에 둔다. 이 글은 2026년 11월 19일 기준 GitHub 공식 발표 블로그(2026-11-17), microsoft/agent-host-protocol 저장소 README 및 docs, AHP 공식 문서(v1.0.0 · v1.1.0)를 교차 검증해 정리했으며, 실제 다중 디바이스 네트워크 벤치마크 대신 공개 명세 분석과 로컬 Python 6대 프로토콜 검증 스크립트를 기준으로 동작 경계를 설명한다.
1. 왜 Agent Host Protocol(AHP)이 등장했는가
1.1 에디터 종속 에이전트 하네스와 N:M 통합 문제
초기 GitHub Copilot 같은 AI 코딩 에이전트는 VS Code 확장 프로세스 내부에 하네스(Harness)가 함께 묶여 있었다. 이 구조에서는 개발자가 에디터 창을 닫거나, IDE를 업데이트하거나, 원격 서버로 자리를 옮기면 에이전트 프로세스와 세션 상태가 함께 사라졌다. 반대로 독립 데스크톱 앱·모바일 앱(iOS/Android)·웹 대시보드·클라우드 샌드박스마다 각기 다른 에이전트 런타임 연동 코드를 직접 작성하면 N개 클라이언트 × M개 에이전트 백엔드 조합만큼 중복 구현이 폭발하는 N:M 통합 문제에 부딪힌다.
AHP는 세션의 소유권과 실행 수명을 클라이언트 UI에서 떼어내 휴대 가능한 독립 프로세스인 Agent Host로 옮긴다. 클라이언트는 백엔드 에이전트가 Claude인지, Codex인지, pi인지, 내부적으로 어떤 도구를 쓰는지 알 필요 없이, 호스트가 노출하는 표준 상태 트리를 구독해 화면에 그리기만 하면 된다.
1.2 12종 URI 채널과 (method, params.channel) 라우팅 불변식
AHP의 모든 상태와 푸시 메시지는 URI로 식별되는 채널(Channel) 위에 놓인다. 명세서(docs/specification/subscriptions.md)는 12가지 표준 채널 스킴을 정의한다:
ahp-root://(RootState): 사용 가능한 에이전트 목록(AgentInfo), 터미널, 호스트 전역 설정을 담는 루트 카탈로그로 항상 존재한다.
ahp-session:/<uuid>(SessionState): 세션 메타데이터, 라이프사이클, 소속 채팅 목록을 관리한다.
ahp-chat:/<cid>(ChatState): 대화 턴(Turn), 스트리밍 응답(chat/delta), 도구 호출(chat/toolCallStart), 입력 요청, 변경셋을 담는다.
ahp-terminal:/<id>(TerminalState) ·ahp-changeset:/<id>(ChangesetState) ·ahp-annotations:/<uuid>(AnnotationsState): 터미널 출력, 코드 변경분, 파일 인라인 주석을 다룬다.
ahp-automations://·ahp-automation-run:/<id>·ahp-canvas:/<id>·ahp-tcp:/<id>·ahp-resource-watch:/<id>·ahp-otlp:: 자동화 실행, 캔버스(실험적), TCP 터널(실험적), 파일 감시, OpenTelemetry 로그·트레이스·메트릭(EmptyState, 알림 스트림 전용)을 담당한다.
특히 AHP 와이어 프로토콜의 핵심 불변식은 모든 JSON-RPC 요청(BaseParams)과 알림의 params 최상위에 반드시 channel: URI 필드가 들어간다는 점이다. 연결 수준의 명령(initialize, ping, reconnect, authenticate, listSessions, 양방향 resourceRead/resourceWrite 파일시스템 RPC 등)은 항상 리터럴 'ahp-root://'를 channel로 사용한다. 덕분에 중간 프록시나 게이트웨이는 메시지 본문을 메서드별로 역직렬화하지 않고 (method, params.channel) 쌍만 읽어 즉시 목적지 핸들러로 라우팅할 수 있으며, TypeScript 정의의 types/version/message-checks.ts가 이를 컴파일 타임에 강제한다.
1.3 순수 리듀서와 Write-Ahead Reconciliation
AHP는 이벤트 소싱의 파편화된 UI 재구성 부담을 없애기 위해 Redux와 유사한 불변 상태 트리 + 순수 리듀서((state, action) -> newState) 모델을 채택한다. 클라이언트는 채널을 subscribe할 때 초기 스냅샷(snapshot: { resource, state, fromSeq })을 받은 뒤, 이후 도착하는 ActionEnvelope를 순수 리듀서에 통과시켜 호스트와 동일한 상태로 수렴한다.
네트워크 지연을 숨기면서도 다중 클라이언트 일관성을 깨뜨리지 않기 위해 클라이언트는 구독마다 세 가지를 유지한다:
confirmedState: 서버(serverSeq)가 최종 확정한 마지막 상태
pendingActions[]: 클라이언트가dispatchAction으로 보냈으나 아직 서버 에코를 받지 못한 낙관적 액션 큐
optimisticState:confirmedState위에pendingActions[]를 순서대로 재생해 계산한 화면 렌더링용 상태
서버로부터 ActionEnvelope가 도착하면 클라이언트는 origin.clientId와 origin.clientSeq를 대조해 ① 내 액션의 정상 에코면 pendingActions[0]을 꺼내 confirmedState에 반영하고, ② 타 클라이언트 또는 서버가 만든 외부 액션이면 confirmedState를 갱신한 뒤 남은 pendingActions[]를 재적용(Rebase)하며, ③ rejectionReason이 붙어 거절 에코가 오면 pendingActions에서 제거해 낙관적 효과를 롤백한다.
2. 혼동하기 쉬운 5가지 프로토콜 경계와 MCP·ACP 비교 표
AHP 문서를 처음 접하는 팀이 설계 단계에서 가장 자주 혼동하는 다섯 가지 경계를 짚어 두어야 한다.
- "AHP가 나오면 Anthropic MCP나 Zed/JetBrains의 ACP는 이제 쓰지 않는 걸까?" — 서로 다른 계층을 담당하며 함께 쌓아 올리는 구조다: 공식 가이드(
docs/guide/ahp-and-acp.md)는 이를 명확히 구분한다. MCP(Model Context Protocol)는 에이전트와 외부 도구·DB·리소스를 연결하고, ACP(Agent Client Protocol)는 단일 에디터(1:1stdioJSON-RPC)와 코딩 에이전트 사이의 프롬프트·스트리밍을 정의한다. 반면 AHP는 그 위에서 여러 클라이언트가 하나의 에이전트 세션을 공유·재접속할 수 있게 상태 동기화를 맡는다. 즉, 호스트는 상향(Upstream)으로 클라이언트들과 AHP로 대화하고 하향(Downstream)으로 ACP 에이전트를 구동하는 "ACP 위의 뮤텍스(Mutex over ACP)" 브리지로 동작한다.
- "클라이언트가 재접속(
reconnect)하면 놓친 알림도 전부 다시 받을 수 있을까?" — 액션 상태만 재생되며 알림(Notification)은 재생되지 않는다: 연결이 끊겼다가reconnect요청에lastSeenServerSeq를 담아 보내면, 리플레이 버퍼 범위 안일 때는 누락된ActionEnvelope목록(type: "replay")을 받고 버퍼를 넘겼을 때는 최신 스냅샷(type: "snapshot")으로 폴백한다. 하지만root/sessionAdded,root/sessionRemoved,otlp/*같은 프로토콜 알림은 재생되지 않으므로, 재접속 직후 클라이언트는 반드시listSessions를 다시 호출해야 한다.
- "WebSocket 인증이나 API 토큰 관리도 AHP 프로토콜이 알아서 해 줄까?" — 전송 계층 인증은 AHP 범위 밖이다: 호스트 엔드포인트 자체에 대한 접근 제어(WebSocket 업그레이드 헤더, 쿼리 토큰, mTLS 등)는
initialize이전에 전송 계층에서 직접 처리해야 한다. AHP가 제공하는authenticate명령과-32007(AuthRequired) 에러 코드는 연결이 성립된 뒤 특정 에이전트(AgentInfo.protectedResources)나 백엔드 MCP 리소스에 필요한 Bearer 토큰을 전달하기 위한 용도다.
- "Windowed Delivery(v1.1.0)를 켜면 대용량 파일 읽기나 전체 메모리 사용량까지 제한될까?" — 구독 푸시 프레임의 미확인 바이트(
windowBytes)만 제어한다: AHP 1.1.0에 도입된 Windowed Delivery(subscribe시flowControl협상,channel/frame분할,channel/credit반환)는 터미널 출력 같은 고대역폭 구독 스트림이 느린 클라이언트를 압도하지 않도록 배압(Backpressure)을 거는 장치다.resourceRead같은 요청 응답이나initialize스냅샷 크기, 연결 전체 메모리 상한은 제한하지 않는다.
- "표준 채널 외에 사내 전용 채널이나 액션을 추가할 수 있을까?" — 반드시
x-접두사를 써야 하며 미지원 스킴 구독은 금지된다: AHP 명세는x-접두사를 구현체 확장용으로 예약하며, 공식 표준 채널·메서드·액션 이름은 절대x-로 시작하지 않는다. 또한 클라이언트는 자신이 이해하지 못하는 URI 스킴의 채널에 절대subscribe해서는 안 되며, 인식할 수 없는 스냅샷 상태는 오류를 내지 말고 무시해야 한다.
| 비교 항목 | MCP (Model Context Protocol) | ACP (Agent Client Protocol) | AHP (Agent Host Protocol) |
| 연결 계층 및 역할 | 에이전트 ↔ 도구 · 데이터 소스 | 단일 에디터 ↔ 코딩 에이전트 | N개 클라이언트 ↔ 독립 Agent Host |
| 다중 클라이언트 동기화 | 비대상 (도구 서버 제공) | 미지원 (1:1 stdio 세션 가정) | 핵심 목적 (N개 클라이언트 동시 관측·제어) |
| 상태 권위 및 전파 모델 | 요청-응답 기반 리소스/도구 호출 | 에이전트 상태 보유 + session/update 스트림 | 호스트 권위 불변 상태 트리 • 순수 리듀서 + serverSeq |
| 재접속 및 충돌 해결 | 세션별 전송 구현에 의존 | 프로토콜 수준 미정의 | 내장 ( reconnect replay/snapshot + Write-Ahead Reconciliation) |
| 에이전트 추상화 범위 | 도구 스키마·프롬프트 표준화 | 에이전트 인터페이스 직접 정의 | 에이전트 비종속 (프롬프트·모델·도구 내부 은닉) |
| 대표 전송 및 스택 위치 | stdio / Streamable HTTP (하위 도구 계층) | stdio JSON-RPC (에이전트 런타임 브리지) | WebSocket JSON-RPC 2.0 (최상위 세션 동기화 계층) |
3. 아키텍처 흐름과 Write-Ahead Reconciliation · 1.1.0 Windowed Delivery
Agent Host Protocol(AHP)의 다중 클라이언트 동기화 계층, 호스트 권위 채널 라우터·중재기 및 ACP/MCP 백엔드 브리지 구조
3.1 "AHP is a mutex over ACP" — 동시 승인 충돌과 브리지 흐름
여러 클라이언트(예: 데스크톱 VS Code와 모바일 웹)가 동시에 같은 채팅 채널(ahp-chat:/<cid>)에 붙어 있을 때, 에이전트가 민감한 도구 실행 승인을 요청하면 두 클라이언트가 거의 동시에 승인 액션을 보낼 수 있다. AHP 호스트는 serverSeq 직렬화를 통해 이 경쟁 조건을 결정적으로 해결한다:
- 단일 턴 소유권 및 도구 승인 뮤텍스: 호스트가 클라이언트 A의
chat/toolCallConfirmed를 먼저 수신하면 이를serverSeq=3으로 확정해 모든 클라이언트에 브로드캐스트하고, 하향 ACP 에이전트에 진행 신호를 넘긴다.
- 후속 충돌 요청 거절(
rejectionReason): 직후 도착한 클라이언트 B의 중복 승인은 호스트가rejectionReason을 달아 에코하며, 클라이언트 B는 자신의pendingActions[]에서 해당 낙관적 액션을 제거하고 클라이언트 A의 확정 상태로 깔끔히 수렴한다.
- 하향 ACP 매핑(Agent Event Mapper): 호스트 내부의 이벤트 매퍼는 ACP 에이전트가 내보내는
session/update알림을 에이전트 비종속적인 AHP 액션(chat/delta,chat/toolCallStart,chat/toolCallReady등)으로 변환해 클라이언트에 전파한다.
3.2 reconnect 복구와 AHP 1.1.0 Windowed Delivery
문서 버전(docs/.vitepress/versions.ts) 기준 현재 안정 명세는 1.0.0과 1.1.0이 공개되어 있다. 모바일 환경에서 통신이 잠시 끊겼다가 복구될 때 클라이언트는 reconnect 요청을 보낸다:
서버는 응답(result) 안에 누락된 ActionEnvelope 배열(type: "replay") 또는 버퍼 초과 시 최신 스냅샷(type: "snapshot")을 담아 반환하고, 이미 폐기되었거나 권한이 회수된 채널은 missing 배열로 알려준다.
한편 1.1.0에 정식 포함된 Windowed Delivery는 ahp-terminal:/<id>나 ahp-tcp:/<id>처럼 대량의 바이트가 쏟아지는 구독을 보호하기 위해 subscribe 단계에서 flowControl: { receive: { windowBytes, maxFrameBytes } }를 협상한다. 크기가 큰 데이터 메시지는 maxFrameBytes 이하의 여러 channel/frame 알림으로 쪼개져 다른 구독과 번갈아 전송되며, 송신 측은 미반환 바이트가 windowBytes에 도달하면 수신 측이 channel/credit 제어 메시지를 보낼 때까지 전송을 늦춘다. 단, channel/credit·unsubscribe·tcp/reset 같은 제어 메시지는 윈도우를 소모하지 않으며, 재접속 시 윈도우 카운터는 0으로 초기화하되 각 윈도우 구독은 전역 lastSeenServerSeq 대신 자신의 lastAppliedServerSeq를 기준으로 복구한다.
3.3 6개 언어 공식 SDK 및 오픈소스 생태계
microsoft/agent-host-protocol 저장소는 단일 언어에 종속되지 않도록 6개 언어의 공식 클라이언트 SDK와 MultiHostClient 패턴을 함께 제공한다:
- TypeScript:
@microsoft/agent-host-protocol(와이어 타입·리듀서·/client·/ws)
- Rust:
ahp·ahp-types·ahp-ws(crates.io)
- Go · Kotlin · Swift · .NET:
github.com/microsoft/agent-host-protocol/clients/go,com.microsoft.agenthostprotocol:agent-host-protocol, SwiftPM,Microsoft.VisualStudioCode.AgentHostProtocol(Rust/Swift/Go/.NET SDK는 여러 호스트에 동시 연결하는MultiHostClient내장)
- 클라이언트 & 서버 생태계: VS Code 내장 Agent Sessions / Agent Host(
src/vs/platform/agentHost/node/), 터미널 클라이언트·TUI·MCP 서버 겸용ahpc, 플러그인 기반 서버ahpd및 웹 UIahpw,pi-ahp,hydra-ahp, 범용 ACP 브리지ahp-acp-gateway, 메신저 연동AgentConnect등이 공개되어 있다.
4. 로컬 Python 6대 프로토콜·상태 수렴 검증 스크립트
아래 verify_agent_host_protocol.py 스크립트는 외부 의존성 없이 Python 표준 라이브러리만으로 ① 12종 표준 채널 URI 스킴 및 (method, params.channel) 라우팅 불변식(ahp-root:// 전용 명령 강제·x- 확장·미지원 스킴 거부), ② 순수 불변 리듀서 기반 Write-Ahead Reconciliation 및 두 클라이언트의 동시 도구 승인 충돌(rejectionReason 롤백) 수렴, ③ reconnect 시 리플레이 버퍼 vs 스냅샷 폴백·missing 채널 정리·listSessions 재조회 플래그, ④ AHP 1.1.0 Windowed Delivery의 channel/frame 분할·windowBytes 백프레셔·제어 메시지 우회·재접속 카운터 리셋, ⑤ 전송 핸드셰이크 인증 vs 에이전트별 protectedResources -32007 AuthRequired 이중 인증 게이트, ⑥ MCP vs ACP vs AHP(+ACP 브리지) 스택 선택 경계를 검증한다.
로컬 실행 결과:
5. 실무 도입 및 호스트·클라이언트 설계 체크리스트
전송 계층 보안 게이트와 프로토콜 내부 인증(authenticate) 분리: WebSocket 업그레이드 단계에서 HTTP 헤더·토큰 검증으로 호스트 접속 자체를 먼저 차단하고, 개별 에이전트나 MCP 서버 권한은 AgentInfo.protectedResources 및 -32007 (AuthRequired) 흐름으로 분리 구현한다.
재접속 복구 시 listSessions 재조회 및 pendingActions 초기화 확인: 네트워크 단절 후 reconnect 응답으로 replay 또는 snapshot을 수신하면 미확정 큐를 비워 confirmedState 기준으로 재정렬하고, 재생되지 않는 세션 생성·삭제 알림을 보완하기 위해 listSessions를 반드시 재호출한다.
고대역폭 터미널·TCP 채널에는 1.1.0 Windowed Delivery 협상 적용: ahp-terminal:/<id>처럼 대용량 스트림이 흐르는 구독은 subscribe 시 flowControl을 협상해 느린 모바일·원격 클라이언트가 전체 WebSocket 연결을 막지 않게 방어한다(단, 생성된 스키마 타입만으로는 흐름 제어가 자동 동작하지 않으므로 카운터·스케줄링을 직접 구현해야 한다).
기존 ACP 에이전트 연동 시 Event Mapper와 단일 턴 뮤텍스 검증: ahp-acp-gateway나 자체 호스트를 구축할 때 두 클라이언트가 동시에 턴 시작·도구 승인·취소(chat/turnCancelled)를 보낼 경우 첫 요청만 확정하고 나머지는 rejectionReason으로 거절하는 호스트 직렬화 테스트를 통과시킨다.
자체 확장 기능에는 x- 접두사 격리 및 미지원 URI 구독 금지 준수: 사내 전용 채널 스킴이나 액션에는 반드시 x- 접두사를 붙이고, 향후 버전 호환성을 위해 클라이언트가 모르는 스킴을 구독하거나 미지의 스냅샷 필드에 예외를 던지지 않도록 방어 코드를 넣는다.
6. 참고 자료 및 공식 출처 (2026-11-19 확인)
확인 기준일: November 19, 2026