💻 개발
[기술부채] AG-UI와 CopilotKit - 1
서론
현재 개발 중인 서비스에서는 사용자가 페이지를 구성하는 요소와 레이아웃을 직접 커스텀할 수 있는 템플릿 편집 기능을 제공하고 있다. 최근 여기에 AI 에이전트를 도입하여 사용자의 입력을 기반으로 템플릿을 추천하고 자동으로 생성해주는 기능을 추가하게 되었다.
해당 기능의 요구사항은 완성된 결과를 한 번에 반환하는 방식이 아니라, AI가 템플릿을 생성하는 과정을 점진적으로 클라이언트 UI로 보여주고, 생성 도중 사용자의 승인 혹은 피드백을 반영할 수 있는 방식이어야 했다.
이러한 요구사항을 구현하는 과정에서, AG-UI(Agent-User Interaction Protocol) 개념을 접하게 되었고, 이를 바탕으로 기능을 구현하게 되었다.
오늘은 AG-UI 프로토콜에 대해 알아보고, 다음 포스트에선 AG-UI에 기반하여 에이전트와의 상호작용을 쉽게 구현할 수 있도록 지원하는 라이브러리 CopilotKit에 대해 알아보기로 한다.
AG-UI 프로토콜
등장 배경
최근 LLM을 기반으로 한 AI 에이전트 시스템이 등장하면서, 기존 웹 애플리케이션의 요청/응답 중심의 인터페이스만으로는 에이전트의 동작을 시각적으로 표현하기 어렵다는 문제가 제기되었다.
AI 에이전트는 단순히 하나의 결과를 반환하지 않고, 추론 과정, 도구 호출, 중간 상태 변화, 상호자와의 상호작용을 포함한 실시간성을 가진 복합적인 실행흐름을 가진다. 이러한 특성으로 기존 REST 기반 API 패턴은 다음과 같은 한계를 가진다.
- 실행 과정의 중간 상태를 전달하기 어렵다.
- 스트리밍 출력을 자연스럽게 표현하기 어렵다.
- 도구 호출 및 결과를 UI와 동기화하기 어렵다.
- 사용자 개입(human-in-the-loop)를 구조적으로 지원하기 어렵다.
또한 기존의 AI 에이전트 시스템은 대부분 백엔드를 중심으로 설계되어 왔으며, 이로 인해 프론트엔드와의 연동 방식이 표준화되지 않는 문제가 있었다.
대표적으로, 에이전트 프레임워크(LangChain, AutoGen 등)마다 이벤트 구조, 스트리밍 방식, 상태 표현 방식이 서로 다르기 때문에, 프론트엔드는 각 시스템에 맞는 방식으로 개별적인 연동을 구현해야 한다.
이러한 차이는 UI가 특정 백엔드 구현에 강하게 결합되도록 만들며, 프레임워크를 변경하거나 확장할 때 UI 레이어의 재사용성을 크게 저해한다.
이러한 문제를 해결하기 위해 제안된 것이 AG-UI(Agent-User Interaction Protocol)이다. AG-UI는 AI 에이전트와 사용자 인터페이스 사이의 상호작용을 표준화하는 이벤트 기반 통신 프로토콜이다.
개념 정의
AI 에이전트의 실행 과정에서 발생하는 상태 변화와 이벤트를 프론트엔드 UI에 실시간으로 전달하기 위한 프로토콜
AG-UI 프로토콜은 다음과 같은 목적으로 사용된다.
- 에이전트의 실행 상태를 실시간으로 클라이언트에게 전달한다.
- 토큰 단위로 텍스트를 스트리밍한다.
- 도구 호출 과정을 시각적으로 전달한다.
- 사용자 개입이 가능한 인터랙션 모델을 제공한다.
- 동적 UI 생성(Generative UI)을 지원한다.
즉, AG-UI는 에이전트의 내부 상태를 사용자 인터페이스와 동기화하는 역할을 수행한다.
시스템 구조(Architecture)
기존의 REST API 기반 AI 애플리케이션은 다음과 같은 구조를 따른다.
flowchart LR UI[User Interface] -->|HTTP Request| Backend Backend --> LLM LLM --> Backend Backend -->|Response| UI
⇒ 백엔드가 최종 결과만 반환하는 단일 요청 → 단일 응답 방식
AG-UI는 이러한 구조를 이벤트 스트림 기반 구조로 확장한다.
flowchart LR UI[User Interface] <-->|Event Stream| AgentBackend AgentBackend --> LLM AgentBackend --> Tools
⇒ 에이전트의 실행 과정 전체가 이벤트 스트림 형태로 클라이언트에게 전달되는 방식. 각 이벤트는 에이전트 내부에서 발생한 상태 변화를 구조화한 것
즉, AG-UI는 다음과 같은 흐름으로 정리할 수 있다.
에이전트 내부의 상태가 변화하면 그 변화가 이벤트로 변환되어 스트림을 통해 전달되고 프론트엔드는 이를 수신하여 UI 상태를 갱신한다.
이러한 구조는 단순 데이터 전달이 아니라
Agent State → Event → UI state라는 일종의 상태 변환 파이프라인으로 볼 수 있다. 이 구조는 특히 장시간 실행되는 작업, 점진적으로 생성되는 결과 혹은 외부 시스템과의 상호작용이 포함된 경우 효과적이다.예를 들어 ChatGPT를 대입해보겠다.
LLM이 생성한 응답 텍스트는 토큰 단위로 스트리밍되어 마치 한 단어씩 순차적으로 출력되는 것과 같은 UI로 표현될 수 있다.
PDF 파일 생성을 위한 외부 툴이 호출될 경우 ’분석 중’이라는 문구를 띄우는 식으로 표현될 수 있다.
(직관적인 이해를 위한 비유일 뿐이고, 실제 ChatGPT의 내부 동작은 다를 수도 있다.)
이렇듯 AG-UI는 에이전트의 실행 과정에서 발생하는 상태 변화를 이벤트 형태로 클라이언트에게 노출하고, 이를 기반으로 클라이언트 UI와 상태를 실시간으로 동기화하는 이벤트 기반 상호작용 프로토콜로 이해할 수 있다.

앞서 설명했듯 AG-UI는 이벤트 기반 구조(event-driven architecture)를 기반으로 한다. 에이전트 실행 과정에서 다양한 이벤트가 발생하고, 프론트엔드는 이를 기반으로 UI 업데이트와 같은 동작을 수행한다.
AG-UI에서 대표적으로 사용되는 이벤트 유형은 다음과 같다.
이벤트 | 설명 |
RUN_STARTED | 에이전트의 실행이 시작되었음을 나타낸다. |
MESSAGE_DELTA | 텍스트가 토큰 단위로 점진적으로 생성되는 스트리밍 이벤트이다. |
TOOL_CALL_START | 에이전트가 외부 도구를 호출하기 시작했음을 의미한다. |
TOOL_RESULT | 외부 도구의 실행 결과가 반환되었음을 나타낸다. |
STATE_PATCH | 에이전트 내부 상태의 일부가 갱신되었음을 나타낸다. |
RUN_COMPLETED | 에이전트의 실행이 종료되었음을 나타낸다. |
이러한 이벤트들은 에이전트의 실행 상태를 클라이언트에게 전달하는 최소 단위로 이해할 수 있으며, 실제 구현에서는 이름이나 구조가 다소 변형될 수 있으나 의미적으로는 유사한 역할을 수행한다.
기술적 구현
AG-UI는 특정 전송 프로토콜에 종속되지 않으며, 일반적으로 SSE, WebSocket, HTTP Streaming과 같은 스트리밍 기술 위에서 구현된다.
데이터 형식은 보통 JSON 기반 이벤트 메시지로 표현되며, 이러한 이벤트 메시지는 프론트엔드 애플리케이션에서 파싱되어 UI 상태 변경에 사용된다.
{ "type": "message.delta", "content": "Hello" }
Ex) PDF 문서를 분석하고 유저의 승인을 받아 분석 결과를 DB에 저장하는 워크플로우
AG-UI의 동작 메커니즘을 보다 구체적으로 이해하기 위해 한 가지 예시 시나리오를 가져왔다.
이 시나리오에서 사용자는 PDF 문서를 업로드하고, 에이전트는 이를 분석하여 핵심 정보를 요약한 요약본을 생성한 뒤, 사용자에게 최종 승인 여부를 요청한다. 사용자의 승인에 따라 에이전트는 요약본을 DB에 저장하거나 폐기한다.
sequenceDiagram autonumber participant User participant UI participant Agent participant Tool %% --- User Action --- rect rgb(235, 245, 255) User->>UI: PDF 업로드 UI->>Agent: Run 요청 end %% --- Run Lifecycle --- rect rgb(240, 240, 240) Agent->>UI: RUN_STARTED end %% --- Tool: PDF Parsing --- rect rgb(255, 245, 235) Agent->>UI: TOOL_CALL_START (parsePDF) Agent->>Tool: parsePDF() Tool-->>Agent: parsed text Agent->>UI: TOOL_RESULT end %% --- Streaming Response --- rect rgb(235, 255, 240) Agent->>UI: MESSAGE_DELTA (요약 생성 중...) Agent->>UI: MESSAGE_DELTA (요약 텍스트 스트리밍) end %% --- State Sync --- rect rgb(255, 255, 235) Agent->>UI: STATE_PATCH (핵심 정보 추출) end %% --- Human Interaction --- rect rgb(245, 235, 255) Agent->>UI: MESSAGE (승인 요청) UI->>User: 승인/거절 버튼 표시 User->>UI: 승인 클릭 UI->>Agent: 사용자 응답 전달 end %% --- Tool: Save --- rect rgb(255, 245, 235) Agent->>UI: TOOL_CALL_START (saveToDB) Agent->>Tool: saveToDB() Tool-->>Agent: success Agent->>UI: TOOL_RESULT end %% --- Completion --- rect rgb(240, 240, 240) Agent->>UI: RUN_COMPLETED end
- 사용자 입력 및 Run 생성 단계
- User → UI: 사용자 입력 발생
- UI → Agent: Run 요청
시나리오는 사용자(User)의 입력으로부터 시작된다. 사용자가 PDF 파일을 업로드하면, UI는 이를 Agent에 전달하여 새로운 실행 단위(run)를 생성한다.
- 실행 초기화 단계 (
RUN_STARTED) - Agent → UI:
RUN_STARTED
Agent는 Run이 생성되었음을 나타내기 위해
RUN_STARTED 이벤트를 UI에 전달한다.이는 이벤트 스트림의 시작을 의미하며, 이후 발생하는 모든 이벤트는 해당 Run 컨텍스트에 종속된다.
UI는 이를 수신하여 초기 상태를 설정하고, 로딩 상태로 전환한다.
- 도구 호출 단계 (Tool Invocation)
TOOL_CALL_START: 도구 호출 시작TOOL_RESULT: 도구 실행 결과 반환
Agent는 작업 수행을 위해 외부 도구를 호출하며, 이 과정은 두 개의 이벤트로 분리되어 표현된다.
sequenceDiagram participant UI participant Agent participant Tool Agent->>UI: TOOL_CALL_START Agent->>Tool: parsePDF() Tool-->>Agent: parsed text Agent->>UI: TOOL_RESULT
시나리오에서는 PDF 파싱과 데이터 저장 두 번의 도구 호출이 나타난다.
UI는
TOOL_CALL_START 이벤트를 통해 작업 진행 상태를 사용자에게 시각적으로 표현할 수 있다.- 스트리밍 출력 단계 (
MESSAGE_DELTA) - Agent → UI:
MESSAGE_DELTA(반복)
Agent는 텍스트 생성 결과를 한 번에 반환하지 않고,
MESSAGE_DELTA 이벤트를 통해 점진적으로 전달한다.sequenceDiagram participant UI participant Agent Agent->>UI: "Hel" Agent->>UI: "Hello" Agent->>UI: "Hello World"
이는 UI가 결과를 기다리지 않고 실시간으로 렌더링을 수행할 수 있도록 한다.
때문에 출력은 “완성된 결과”가 아니라 시간에 따라 누적되는 것처럼 표현된다.
- 상태 동기화 단계 (
STATE_PATCH) - Agent → UI:
STATE_PATCH - 텍스트 스트림 (
MESSAGE_DELTA) - 상태 스트림 (
STATE_PATCH)
텍스트 출력과 별도로, Agent는 구조화된 데이터를
STATE_PATCH 이벤트를 통해 전달한다.flowchart RL Agent -->|UI Spec JSON| UI UI --> RenderedComponent[Dynamic Component] %% 스타일 정의 classDef highlight fill:#f8fafc,stroke:#6366f1,stroke-width:2px,color:#111827,rx:12,ry:12; %% 특정 노드에 스타일 적용 class RenderedComponent highlight;
이 이벤트는 Agent의 내부 상태 일부를 외부로 노출하는 역할을 하며, UI는 이를 기반으로 추가적인 컴포넌트(예: 사이드 패널)를 렌더링할 수 있다.
따라서 AG-UI는 다음 두 가지 스트림을 동시에 처리한다.
- 사용자 개입 단계 (Human-in-the-loop)
- Agent → UI:
MESSAGE(승인 요청) - UI → User: 인터랙션 UI 생성
- User → UI: 입력
- UI → Agent: 사용자 응답 전달
- AI in the Loop: 시스템 내에 AI가 하나의 구성 요소로 포함되어, 인간의 의사결정 또는 작업 수행을 보조하는 구조
- Human-on-the-loop: 시스템은 자율적으로 동작하고, 인간이 이를 지속적으로 감시하며 필요 시 개입하는 구조
- Human-out-of-the-loop: 인간의 개입 없이 시스템이 전 과정을 자동으로 수행하는 완전 자동화 구조
Agent는 특정 시점에서 사용자 판단이 필요할 경우, 메시지를 통해 사용자에게 요청을 전달한다.
sequenceDiagram participant User participant UI participant Agent Agent->>UI: MESSAGE: "요약 결과를 저장하시겠습니까?" UI->>User: (승인/거절 버튼 표시) User->>UI: (승인 버튼 클릭) UI->>Agent: (사용자 응답 전달)
이 단계에서 시스템은 단방향 이벤트 흐름을 벗어나, 사용자를 포함한 양방향 인터랙션 구조로 전환된다.
Human-in-the-loop
AI가 업무를 수행하는 과정에서 인간이 한 번은 개입해야 한다는 원칙
시스템이 스스로 모든 결정을 내리지 않고, 특정 단계에서 인간의 입력을 필수적으로 포함하는 설계 패턴을 의미한다.
이와 비교되는 개념들은 다음과 같다.
- 실행 종료 단계 (RUN_COMPLETED)
- Agent → UI:
RUN_COMPLETED
모든 작업이 완료되면 Agent는
RUN_COMPLETED 이벤트를 전송한다.이는 이벤트 스트림의 종료를 의미하며, UI는 이를 기반으로 최종 상태를 확정한다.
마무리
이처럼 AG-UI는 에이전트와 UI 간의 상호작용을 이벤트 스트림으로 추상화한 개념적 모델이다. 하지만 실제 애플리케이션에서 이러한 이벤트 처리, 상태 동기화, 인터랙션 관리 등을 모두 직접 구현하는 것은 꽤나 복잡하고 까다롭다.
이러한 부담을 줄이기 위해 AG-UI 패턴을 프레임워크 수준에서 추상화한 도구들이 등장했는데, 대표적으로 CopilotKit이 있다.
이 CopilotKit에 대해서는 다음 포스트에서 다루어보도록 하겠다.
📚 기술 부채30 / 31
- 1편[기술부채] 우테코 5기 레벨1 - 6주차: 블랙잭 미션, RDD와 try-with-resources2023년 3월 20일
- 2편[기술부채] 우테코 5기 레벨1 - 7주차: 체스 미션, 방어적 복사와 커맨드 패턴2023년 3월 27일
- 3편[기술부채] 우테코 5기 레벨1 - 8주차: 체스 미션, 테스트 더블과 커넥션 풀2023년 4월 14일
- 4편[기술부채] 우테코 5기 레벨2 - 1주차: 웹 자동차 경주, 스프링 MVC 매핑과 DI2023년 4월 16일
- 5편[기술부채] 우테코 5기 레벨2 - 2주차: @Valid와 Dirty Checking2023년 5월 1일
- 6편[기술부채] 우테코 5기 레벨2 - 3주차: 장바구니 미션, MockMvc vs RestAssured와 PRG 패턴2023년 5월 3일
- 7편[기술부채] 우테코 5기 레벨2 - 5주차: Mockito와 동적 쿼리2023년 5월 14일
- 8편[기술부채] 우테코 5기 레벨2 - 6주차: 지하철 미션, Profile과 JPA 연관관계2023년 5월 23일
- 9편[기술부채] 우테코 5기 레벨2 - 9주차: CORS Preflight와 멱등성, 필드 주입2023년 6월 12일
- 10편[기술부채] 우테코 5기 레벨2 - 8주차: 장바구니 협업 미션, LocalDateTime 직렬화와 시맨틱 버저닝2023년 6월 12일
- 11편[기술부채] 우테코 5기 레벨2 - 7주차: OSIV와 영속성 컨텍스트, CORS 인증2023년 6월 30일
- 12편[기술부채] 우테코 5기 레벨3 - 3주차: 오프셋·커서 페이지네이션과 @ElementCollection2023년 7월 18일
- 13편[기술부채] 우테코 5기 레벨3 - 7주차: Batch Insert와 @EventListener2023년 8월 12일
- 14편[기술부채] 우테코 5기 레벨3 - 8주차: JPQL Distinct와 MultipleBagFetchException2023년 8월 31일
- 15편[기술부채] 우테코 5기 레벨3 - 6주차: 동시성 이슈와 @Transient2023년 8월 31일
- 16편[기술부채] 우테코 5기 레벨3 - 1주차: 무결성과 정합성, Elastic Beanstalk2023년 8월 31일
- 17편[기술부채] 우테코 5기 레벨4 - 1주차: @TransactionalEventListener와 트랜잭션 전파2023년 9월 10일
- 18편[기술부채] 우테코 5기 레벨4 - 2주차: 톰캣 만들기와 Location 헤더2023년 9월 11일
- 19편[기술부채] 우테코 5기 레벨4 - 3주차: 로드밸런서, CQRS와 커버링 인덱스2023년 9월 18일
- 20편[기술부채] 우테코 5기 레벨4 - 4주차: @MVC 구현하기 미션2023년 9월 24일
- 21편[기술부채] 우테코 5기 레벨4 - 5주차: @MVC 구현하기 3단계와 JSON 응답2023년 10월 2일
- 22편[기술부채] 우테코 5기 레벨4 - 6주차: JDBC 라이브러리 구현하기 1~3단계2023년 10월 9일
- 23편[기술부채] 우테코 5기 레벨4 - 7주차: JDBC 라이브러리 구현하기 3단계2023년 10월 16일
- 24편[Spring] Spring DTO의 데이터 바인딩과 직렬화2023년 12월 5일
- 25편[기술부채] 클라이언트 사이드 라우팅2026년 2월 5일
- 26편[기술부채] 왜 리액트는 클래스를 버리고 함수를 선택했을까(feat. React Hooks)2026년 2월 12일
- 27편[기술부채] iframe과 postMessage2026년 2월 20일
- 28편[기술부채] Service Worker(서비스 워커)2026년 2월 24일
- 29편[기술부채] 커링의 어원과 함수형 프로그래밍2026년 3월 12일
- 30편[기술부채] AG-UI와 CopilotKit - 12026년 3월 27일
- 31편[기술부채] AG-UI와 CopilotKit - 22026년 3월 29일