01 / DEFINITION

AG-UI가 정의하는 통신 경계

일반적인 채팅 서비스에서는 서버가 답변을 완성한 뒤 클라이언트에 반환하거나, 텍스트 일부를 순차적으로 전송한다. 에이전트 기반 애플리케이션에서는 텍스트 이외의 정보도 필요하다. 하나의 요청 안에서 검색 도구를 호출하고, 문서를 검토하고, 사용자의 승인을 기다린 뒤 작업을 재개할 수 있기 때문이다.

AG-UI는 이러한 과정을 사용자 화면에 전달할 수 있도록 공통 이벤트 유형과 입력 구조를 정의한다. 특정 모델, 에이전트 프레임워크 또는 화면 라이브러리를 강제하지 않으며, 서로 다른 구현이 동일한 상호작용 형식을 이해하도록 하는 데 목적이 있다.

여기서 ‘양방향’이란 서버가 이벤트를 전달하는 흐름과 사용자가 새로운 입력·상태를 보내는 흐름이 모두 존재한다는 의미다. 반드시 하나의 양방향 소켓을 사용해야 한다는 뜻은 아니다.

02 / ARCHITECTURE

에이전트와 화면을 연결하는 아키텍처

AG-UI의 기본 구조는 사용자 애플리케이션, AG-UI 통신 계층, 에이전트 실행 환경으로 나뉜다. 화면은 사용자 메시지와 현재 대화·상태 정보를 입력으로 전달한다. 에이전트 실행 환경은 작업을 수행하며 발생하는 사건을 AG-UI 이벤트로 변환해 내보낸다. 클라이언트는 이벤트를 수신한 순서에 따라 메시지와 상태를 갱신한다.

대표적인 HTTP 구현에서는 사용자 입력을 HTTP 요청으로 보내고 서버가 SSE(Server-Sent Events, 서버 전송 이벤트) 스트림으로 실행 이벤트를 반환한다. 다만 SSE는 전송 방식이고 AG-UI는 그 위에서 교환할 이벤트의 의미와 형식을 정의하는 규격이다. 구현 환경에 따라 WebSocket 등 다른 전송 수단도 사용할 수 있다.

03 / EVENT STREAMING

이벤트 스트리밍과 도구 호출

AG-UI의 핵심 단위는 이벤트다. 클라이언트는 개별 이벤트를 해석하는 동시에 동일한 메시지나 도구 호출에 속한 이벤트를 식별자로 연결한다. 이벤트를 받았다는 사실과 실제 도구 실행이 성공했다는 사실은 구분해야 한다.

텍스트는 시작 이벤트 이후 여러 콘텐츠 이벤트로 나뉘어 전송되며 종료 이벤트로 마무리된다. 도구 호출도 시작, 인수 전달, 호출 정보 종료 등의 이벤트로 표현할 수 있다. 도구 실행 결과는 별도 결과 이벤트 또는 실행 환경이 생성하는 후속 메시지로 전달될 수 있으므로, 호출 정보의 종료와 실제 작업 완료를 동일하게 취급하면 안 된다.

04 / SHARED STATE

상태 동기화와 사용자 개입

상태(State)는 에이전트와 사용자 화면이 공유해야 하는 구조화된 데이터다. 예를 들어 작성 중인 문서의 제목, 선택된 자료, 승인 여부를 상태로 관리할 수 있다. AG-UI는 상태 전체를 전달하는 스냅샷(State Snapshot)과 변경된 부분만 전달하는 델타(State Delta)를 구분한다.

STATE_SNAPSHOT을 받은 화면은 이를 새로운 기준 상태로 삼는다. 이후 STATE_DELTA에 포함된 JSON Patch 연산을 순서대로 적용해 상태를 갱신한다. JSON Patch는 RFC 6902에 정의된 형식으로, add, remove, replace 등의 연산을 사용한다.

{
  "type": "STATE_SNAPSHOT",
  "snapshot": {"document": {"status": "draft"}}
}

{
  "type": "STATE_DELTA",
  "delta": [
    {"op": "replace", "path": "/document/status", "value": "review"}
  ]
}

위 예시는 최초 상태가 ‘초안’이고 후속 이벤트가 문서 상태를 ‘검토 중’으로 변경하는 상황이다. 변경 이벤트만 수신하고 기준 상태를 갖고 있지 않으면 올바르게 반영하기 어렵다. 연결이 끊기거나 상태가 불일치하는 경우에는 새로운 스냅샷으로 다시 동기화하는 절차가 필요하다.

사용자 개입(Human-in-the-Loop)은 이러한 공유 상태와 입력 흐름을 활용해 구성할 수 있다. 예를 들어 에이전트가 메일 발송안을 작성하고 사용자에게 승인 화면을 표시한 뒤, 승인 또는 수정된 내용을 새로운 입력으로 받아 작업을 이어갈 수 있다. 다만 승인 요청의 화면 구성, 실행 중단과 재개, 권한 검사는 AG-UI 이벤트만으로 자동 완성되는 기능이 아니라 에이전트 실행 환경과 애플리케이션에서 함께 구현해야 한다.

05 / PROTOCOL RELATIONSHIP

MCP·A2A와의 관계

AG-UI, MCP(Model Context Protocol), A2A(Agent2Agent Protocol)는 모두 에이전트 기반 시스템의 상호운용성을 다루지만 연결하는 대상이 다르다. 서로 대체하는 규격이라기보다 하나의 애플리케이션에서 함께 사용될 수 있는 별도의 통신 경계에 가깝다.

가령 사용자가 화면에서 여행 계획을 요청하면 AG-UI는 화면과 주 에이전트 사이의 진행 상황을 전달할 수 있다. 주 에이전트는 MCP를 통해 검색 도구를 호출하고, A2A를 통해 다른 전문 에이전트에 일부 작업을 위임할 수 있다. 각 기술의 실제 사용 여부는 애플리케이션 설계에 따라 달라진다.

비슷한 이름의 A2UI는 선언형 사용자 인터페이스를 표현하는 규격으로, 에이전트와 화면 사이의 이벤트 통신을 정의하는 AG-UI와 구별된다. 애플리케이션은 AG-UI를 통해 구조화된 UI 데이터를 전달하고 별도 렌더러로 화면을 구성할 수도 있다.

06 / IMPLEMENTATION

구현 예시와 기술적 고려사항

AG-UI를 도입할 때는 먼저 어떤 사건을 사용자에게 표시할지 결정해야 한다. 메시지 스트리밍만 필요하다면 텍스트 이벤트 중심으로 시작할 수 있다. 도구 호출 과정을 표시하거나 사용자가 중간에 작업을 수정해야 한다면 도구·상태 이벤트와 사용자 입력 처리가 추가된다.

실제 서비스에서는 이벤트 규격과 별도로 인증·인가, 민감정보 제거, 이벤트 데이터 검증, 오류 처리, 연결 재설정, 영구 저장 및 작업 재개 정책이 필요하다. 특히 도구 호출 이벤트는 화면에 전달되는 실행 정보이지, 클라이언트가 임의의 도구를 실행하도록 허가하는 보안 권한이 아니다. 실행 권한은 서버에서 독립적으로 검증해야 한다.

이벤트의 수신 순서와 식별자 관리도 중요하다. 같은 메시지의 텍스트 조각은 올바른 순서로 합쳐야 하며, 중간 상태를 놓친 경우에는 불완전한 델타를 무조건 적용하기보다 신뢰할 수 있는 기준 상태를 다시 받아야 한다. AG-UI가 공통 언어를 제공하더라도 이러한 운영 정책은 개별 서비스의 책임으로 남는다.

REFERENCE / GLOSSARY

REFERENCE / PRIMARY SOURCES