Skip to content

A2UI

generative UI의 선언형 계층이에요. 에이전트가 여러분이 소유한 컴포넌트 카탈로그에서 화면을 조립해요.

에이전트가 UI를 조립해요

도구 기반 렌더링(tool-based rendering)은 도구 하나를 컴포넌트 하나에 매핑해요. 에이전트가 컴포넌트를 고르면 여러분이 그걸 그리는 방식이죠. A2UI는 generative-UI 스펙트럼에서 선언형 계층이에요. 단일 컴포넌트를 고르는 대신, 에이전트가 여러분이 정의한 카탈로그의 빌딩 블록을 조합해 화면을 조립해요.

컴포넌트의 소유권은 여전히 여러분에게 있어요. 에이전트는 카탈로그에 있는 것만 사용할 수 있으니까, 여러분이 배포하지 않은 건 절대 렌더링하지 못해요. 에이전트가 정하는 건 레이아웃과 데이터예요. 즉 빌딩 블록을 어떻게 묶어 패널로 만들지, 그리고 그 안에 무엇을 넣을지죠.

A2UI는 Flows와 함께 동작해요. 아래 두 가지 모드(동적 모드, 고정 스키마 모드)는 모두 AG-UI로 제공되는 Flow로 실행돼요. 이 섹션의 나머지 부분과 정확히 같아요.

카탈로그 (모든 모드에서 동일)

프런트엔드 연결 방식은 어떤 백엔드 모드를 쓰든 동일해요. <CopilotKit> 프로바이더에 a2ui prop으로 카탈로그를 등록하면 돼요.

import { CopilotKit } from "@copilotkit/react-core";
import { catalog } from "@/a2ui-catalog";

<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
  {/* ... */}
</CopilotKit>

카탈로그는 카탈로그 id 키로 묶인 여러분의 React 컴포넌트 집합이에요. FlightCard, HotelCard, Chart처럼 앱에 필요한 그대로요. 에이전트는 카탈로그 id를 참조하고, CopilotKit은 에이전트가 준 데이터로 여러분의 컴포넌트를 그려줘요.

카탈로그 자체를 만드는 방법 — id 스키마, prop 매핑, 조합 규칙 — 은 이 페이지 범위를 벗어나요. 자세한 저작 레퍼런스는 CopilotKit A2UI 문서를 보세요. 여기서는 두 가지 백엔드 모드와 각각 언제 쓰면 좋은지에 집중할게요.

두 가지 백엔드 모드

A2UI 백엔드는 두 가지 형태로 나와요. 동적(dynamic) 모드에서는 에이전트가 화면을 설계하고, 고정 스키마(fixed-schema) 모드에서는 여러분이 레이아웃을 미리 만들고 에이전트는 데이터만 채워요.

모드 레이아웃 설계 주체 백엔드 예측 가능성
동적 대화에서 에이전트 A2UI 도구 없음 — 자동 주입 새로운 레이아웃, LLM 레이아웃 단계
고정 스키마 미리 여러분 백엔드 도구가 envelope 반환 결정적, 레이아웃 단계 없음

동적 모드

Flow는 A2UI 도구를 연결하지 않아요. 런타임에서 이 에이전트에 A2UI를 켜면 generate_a2ui 도구를 자동으로 얻게 돼요. 서브 에이전트가 대화 내용을 바탕으로 여러분의 카탈로그에 맞춰 화면을 설계하고, 프런트엔드에 점진적으로 스트리밍하며, 검증-후-재시도(validate-then-retry) 복구 과정을 통해 잘못된 출력을 스스로 고쳐요.

...

위와 같아요 — 카탈로그를 a2ui prop으로 전달해요: 

<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
  {/* ... */}
</CopilotKit>
백엔드는 일반적인 agentic-chat Flow예요. A2UI 도구를 직접 정의하지 않아요 — 에이전트에 A2UI가 켜져 있으면 런타임이 generate_a2ui를 주입하고, 서브 에이전트가 대화 내용에서 레이아웃을 만들어내죠. 턴에서 UI가 필요해지면 에이전트가 카탈로그에서 화면을 조립하고, 설계하면서 컴포넌트를 스트리밍하며, 화면에 닿기 전에 잘못된 출력을 수리해요. 여러분이 등록한 컴포넌트가 에이전트가 고른 레이아웃에서 렌더링돼요.

...

고정 스키마 모드

각 도구는 결과로 A2UI 연산 envelope을 반환해요 — createSurface → updateComponents → updateDataModel — 프런트엔드가 이를 그려요. 서브 에이전트도, 생성 과정도, 복구 과정도 없어요. 레이아웃 JSON은 여러분이 만들고, 변하는 건 데이터뿐이에요.

...

from ag_ui_a2ui_toolkit import (
    A2UI_OPERATIONS_KEY,
    create_surface,
    update_components,
    update_data_model,
)
from ag_ui_crewai.sdk import copilotkit_emit_tool_result, copilotkit_stream

도구는 createSurface → updateComponents → updateDataModel 연산을 A2UI_OPERATIONS_KEY로 키가 매겨진 envelope으로 묶은 다음, copilotkit_emit_tool_result(...)로 돌려줘요. 레이아웃이 고정되어 있으니 같은 도구는 항상 같은 형태를 만들어내요 — 호출마다 달라지는 건 값뿐이죠.

언제 어떤 걸 써야 할까

  • 동적: 레이아웃을 미리 알 수 없고, 에이전트가 여러분의 프리미티브로 새로운 화면을 조합하길 원할 때. 유연함을 얻는 대신 LLM 레이아웃 단계 비용을 지불해요.
  • 고정 스키마: 레이아웃이 정해져 있고 데이터만 변할 때. 생성도 복구도 레이아웃 경로의 LLM도 없으니 더 예측 가능하고 결정적이에요.

두 모드 모두 같은 프런트엔드를 공유해요 — 카탈로그 하나를 프로바이더에 한 번만 등록하면 돼요. 화면이 안정적이면 고정 스키마로 시작하고, 예상치 못한 레이아웃을 에이전트가 설계하게 하고 싶을 때 동적 모드를 꺼내 쓰면 좋아요.

관련 자료

  • Generative UI — 전체 스펙트럼. A2UI는 그 선언형 계층이에요.
  • Agentic Generative UI — 에이전트의 실시간 상태를 (제어된 방식으로) 렌더링해요.