A2UI x AG-UI: CopilotKit과 Strands Agents를 사용하여 A2UI (v0.9)를 지원하는 AI 에이전트 구축하기
요약
CopilotKit, Strands Agents, 그리고 A2UI 사양을 활용하여 텍스트를 넘어 상호작용 가능한 UI를 생성하는 AI 에이전트 구축 방법을 소개합니다. AI가 JSON 형태로 UI를 정의하고 프론트엔드가 이를 렌더링하는 Generative UI의 구현 원리를 다룹니다.
핵심 포인트
- A2UI는 UI를 JSON으로 정의하여 AI가 동적으로 인터페이스를 생성하게 함
- CopilotKit과 Strands Agents를 결합한 에이전트 아키텍처 활용
- 텍스트 답변을 넘어 버튼, 카드 등 상호작용 가능한 Generative UI 구현
원본 기사:
https://qiita.com/Takenoko4594/items/dab65ccac9038fa2ad6b
대부분의 채팅 기반 AI 에이전트는 텍스트로만 답변할 수 있습니다. 하지만 만약 당신의 에이전트가 기술 미트업(tech meetups)을 검색하고, 그 결과를 텍스트의 벽 대신 클릭 가능한 카드 목록으로 보여줄 수 있다면 어떨까요?
그것이 바로 제가 CopilotKit과 AI 에이전트 구축을 위한 AWS의 SDK인 Strands Agents, 그리고 에이전트가 프론트엔드 UI를 제어할 수 있게 해주는 A2UI라는 사양(spec)을 사용하여 구축하려고 시도한 것입니다.
"Generative UI (생성형 UI)"라는 말을 들어봤지만, 에이전트가 실제로 어떻게 화면에 버튼이나 카드를 나타나게 하는지 잘 모르겠다면, 이 포스트가 도움이 될 것입니다.
코드는 여기에 있습니다:
https://github.com/KMiya84377/copilotkit_a2ui_strands_app
A2UI란 무엇인가?
A2UI는 Generative UI (생성형 UI)를 달성하기 위한 하나의 사양입니다
Generative UI (생성형 UI)는 AI가 상황에 따라 텍스트뿐만 아니라 상호작용 가능한 버튼, 카드, 그래프 등을 포함하여 사용자 인터페이스(user interface) 자체를 동적으로 생성할 수 있다는 개념입니다.
Google에서 제공하는 A2UI는 이를 가능하게 하는 사양 중 하나입니다.
A2UI는 UI를 JSON으로 표현합니다
그렇다면 A2UI는 실제로 이를 어떻게 수행할까요?
프론트엔드와 AI 에이전트의 관점에서 생각해 봅시다.
A2UI는 UI를 소스 코드가 아닌 JSON으로 정의합니다.
AI 에이전트는 프론트엔드로부터 프롬프트(prompt)를 받고, 표시할 UI를 JSON으로 반환합니다. 그러면 프론트엔드는 해당 JSON을 기반으로 화면을 렌더링(render)합니다.
이 JSON은 UI를 구축하기 위해 결합된 세 가지 요소로 구성됩니다:
| 요소 (Element) | 설명 (Description) |
|---|---|
| Surface | UI가 그려지는 캔버스(canvas)와 같은 영역 |
| ... |
A2UI는 Surface라고 불리는 빈 캔버스를 준비하고, 그 위에 컴포넌트 (Components)를 배치하며, 데이터 모델 (Data Model)을 통해 표시할 데이터를 해당 컴포넌트들에 바인딩(bind)합니다.
다시 말해, A2UI는 AI가 UI의 JSON "설계도 (blueprint)"를 생성하면, 프론트엔드가 해당 설계도로부터 UI를 렌더링(render)하는 메커니즘입니다.
AI 에이전트는 4가지 유형의 JSON 메시지로 UI를 조립합니다
지금까지 세 가지 구성 요소인 Surface, Component, Data Model에 대해 살펴보았습니다. 하지만 이들이 에이전트와 프론트엔드 사이에서 실제로 어떻게 교환될까요?
AI 에이전트가 프론트엔드로 보내는 JSON 메시지에는 네 가지 유형이 있습니다:
| 유형 (Type) | 설명 (Description) |
|---|---|
createSurface | 프론트엔드에 Surface를 생성하도록 지시 |
| ... |
이 메시지들이 흐르기 시작하고 UI가 구축되는 과정은 다음과 같습니다:
실제로 교환되는 JSON을 파악하는 가장 좋은 방법은 여기의 샘플을 확인하는 것입니다:
https://a2ui.org/introduction/what-is-a2ui/#example
A2UI의 메시지 사양(spec)은 v0.8과 v0.9 사이에 차이가 있습니다. 위의 예시는 v0.9를 가정합니다.
UI 패턴은 카탈로그에서 가져옵니다
updateComponents에서 지정하는 UI 컴포넌트들은 **카탈로그 (catalog)**로 관리됩니다.
카탈로그 (catalog)는 "어떤 컴포넌트가 사용 가능한지"와 "각 컴포넌트가 어떤 속성 (properties)을 갖는지"를 정의합니다.
카탈로그는 크게 두 가지 유형이 있습니다:
| 카탈로그 | 설명 |
|---|---|
| basicCatalog (기본 카탈로그) | A2UI에서 제공하는 표준 UI 컴포넌트 세트 |
| BYOC (사용자 정의 카탈로그) | 사용자가 직접 자신의 컴포넌트를 등록할 수 있는 커스텀 카탈로그 |
https://a2ui.org/concepts/catalogs/
basicCatalog에 포함된 컴포넌트들은 여기서 찾아볼 수 있습니다:
https://a2ui.org/reference/components/
프론트엔드는 A2UI 전용 렌더러 (renderer)로 렌더링됩니다
카탈로그에 정의된 컴포넌트들은 **렌더러 (renderer)**에 의해 프론트엔드에 렌더링됩니다.
렌더러는 A2UI JSON 메시지를 전달받아 프론트엔드에 UI를 그리는 라이브러리입니다.
A2UI는 React, Lit (Web Components), Angular, Flutter를 포함한 여러 플랫폼을 위한 렌더러를 공식적으로 제공합니다.
https://a2ui.org/reference/renderers/
액션 (Actions)
A2UI는 또한 사용자가 렌더링된 UI와 상호작용할 수 있게 해줍니다.
https://a2ui.org/concepts/actions/이는 Human-in-the-Loop (인간 참여형) 흐름과 더욱 인터랙티브한 생성형 UI (Generative UI) 경험으로 가는 문을 열어줍니다. (이 내용은 나중에 다루겠습니다. 금방 복잡해지거든요.)
전체 아키텍처 (overall architecture)
제가 구축한 앱의 전체 아키텍처는 다음과 같습니다.
지금까지 A2UI의 기초를 살펴보았습니다. 이제부터는 이를 CopilotKit 및 Strands Agents와 결합했을 때 어떤 일이 일어나는지 이야기해 보겠습니다.
참고로, AWS에서 이미 CopilotKit과 생성형 UI (Generative UI)를 결합한 샘플을 제공하고 있으며, 저는 이를 참고 자료로 사용했습니다:
https://github.com/aws-samples/sample-FAST-applications/tree/main/samples/copilotkit-generative-ui
CopilotKit을 사용하여 AG-UI 준수 에이전트 구축하기
CopilotKit은 AI 에이전트(AI agents)를 구축하기 위한 프레임워크입니다. 이를 사용하면 A2UI와 같은 기술로 구동되는 그래픽 UI를 갖춘 에이전트를 쉽게 구축할 수 있습니다.
CopilotKit은 프론트엔드(frontend)와 AI 에이전트를 연결하는 이벤트 기반 프로토콜인 AG-UI를 통해 에이전트와 통신합니다.
https://github.com/ag-ui-protocol/ag-ui
프론트엔드와 에이전트가 이 공유 프로토콜을 통해 통신하기 때문에, 두 요소는 느슨하게 결합(loosely coupled)된 상태를 유지하며, 프론트엔드를 수정하지 않고도 에이전트 구현을 교체할 수 있습니다.
AG-UI와 Strands Agents 결합하기
Strands Agents는 AI 에이전트를 구축하기 위한 AWS의 SDK입니다.
https://github.com/strands-agents/harness-sdk/tree/main/strands-py
이것은 기본적으로(out of the box) AG-UI를 지원하지 않으므로, AG-UI와 호환되도록 전용 어댑터(adapter)를 추가해야 합니다.
https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/aws-strands/python/src/ag_ui_strands
그 위에 A2UI 추가하기
CopilotKit + AG-UI 설정이 완료되면, 그 위에 A2UI를 계층적으로 쌓을 수 있습니다.
A2UI와 AG-UI는 서로 다른 계층에 위치합니다. AG-UI는 이벤트를 주고받는 전송 계층 (transport) 역할을 하며, A2UI는 해당 전송 계층을 통해 전달되는 메시지의 내용 (content) 역할을 합니다.
이 프로젝트를 위해 저는 다음을 사용하여 AWS에 모든 것을 배포했습니다:
- Frontend: AWS Amplify (Hosting)
- Backend: AWS Lambda + Amazon API Gateway (HTTPS)
- AI Agent: Amazon Bedrock AgentCore
구현 (Implementation)
이제 실제 코드로 들어가 보겠습니다. 제가 구축한 에이전트는 기술 미트업 (tech meetups)을 검색하고, 그 결과를 카드나 리스트 형태로 시각적으로 제안합니다.
프론트엔드 (Frontend)
먼저, 프론트엔드의 A2UI 관련 코드입니다.
스키마 및 컴포넌트 정의
저는 StudyEventCard (미트업 카드) 및 StudyEventList (리스트 뷰)와 같은 컴포넌트를 정의했습니다. 각 컴포넌트의 스키마는 Zod로 정의되며 props로 소비됩니다.
이러한 컴포넌트와 스키마를 바탕으로 카탈로그 (catalog)를 구축했습니다.
includeBasicCatalog: true로 설정하면 A2UI의 기본 컴포넌트 (basicCatalog)를 가져옵니다. false로 설정하면 사용자가 정의한 커스텀 컴포넌트만 사용할 수 있습니다.
다음으로, createA2UIMessageRenderer가 해당 카탈로그로부터 렌더러 (renderer)를 생성합니다.
마지막으로, 카탈로그(catalog)와 렌더러(renderer)를 CopilotKit에 연결합니다.
CopilotKit을 위한 A2UI 렌더러 (A2UI renderer for CopilotKit)
A2UI는 공식 React 렌더러를 배포하지만, CopilotKit은 CopilotKit에 맞게 커스텀된 자체 렌더러를 제공합니다:
https://github.com/CopilotKit/CopilotKit/tree/v1.56.5/packages/a2ui-renderer
백엔드 (Backend)
다음은 백엔드 구현입니다.
CopilotKit 런타임 (Runtime)에서 A2UI 활성화하기
CopilotRuntime 설정에 a2ui: { injectA2UITool: true }를 추가하면 A2UI가 활성화됩니다.
injectA2UITool: true를 설정하면, @ag-ui/a2ui-middleware의 A2UIMiddleware가 요청 처리(request handling)에 자동으로 적용됩니다.
A2UIMiddleware는 AI 에이전트에 render_a2ui 도구(tool)를 주입합니다. 단, 프론트엔드에 카탈로그(catalog)가 등록되어 있는 경우에만 수행됩니다. 또한 에이전트가 해당 도구를 어떻게 사용하는지 알 수 있도록 컨텍스트 (context)에 지침(instructions)을 주입합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기