AG-UI 프로토콜과 TanStack AI로 만드는 AI 채팅 앱 - Vercel 네이티브 데스크톱 데모

핵심 메시지

• AG-UI는 클라이언트와 서버가 채팅 메시지를 주고받는 방식을 표준화한 스펙으로, TanStack AI가 기본으로 지원한다.
• 표준 프로토콜을 쓰면 Node 백엔드와 Zig로 만든 프런트엔드처럼 서로 다른 기술 스택도 깔끔하게 통신할 수 있다.
• 서버는 Anthropic·OpenAI·Gemini·Ollama 등 여러 어댑터를 두고, 사용 가능한 환경변수 키에 따라 LLM을 선택한다.
• 웹 클라이언트는 useChat 훅으로 SSE(server-sent event)로 온 AG-UI 포맷 메시지를 받아 화면에 렌더링한다.
• Vercel의 새 네이티브 SDK는 Zig와 XML 기반으로 데스크톱 앱을 빠르고 가볍게 만들 수 있는 선택지를 제시한다.

쉽게 이해하기

잭 헤링턴은 화면 왼쪽의 네이티브 데스크톱 채팅 앱과 오른쪽의 웹 앱이 똑같이 동작하는 데모로 이야기를 연다. 두 앱 모두 로컬 3000번 포트에서 돌아가는 TanStack AI 서버에 연결되어 있으며, "기타를 추천해줘" 같은 요청에 동일한 답과 UI 콜아웃을 보여준다. 왼쪽 데스크톱 앱은 Vercel의 새 네이티브 SDK로 만들어졌고, 이는 Zig와 XML을 토대로 한 데스크톱 빌드 방식이다.

이 모든 것을 잇는 비결은 AG-UI 프로토콜이다. AG-UI는 클라이언트와 서버 사이에서 채팅 메시지를 어떻게 주고받을지 표준화한 스펙이며, TanStack AI는 이를 기본 수준에서 지원한다. 발표자는 LLM에게 Vercel 네이티브 앱을 만들 때 "AG-UI 스펙을 쓰라"고 지시하는 것만으로 별도 작업 없이 동작했다고 설명한다.

서버 측 코드는 TanStack AI 채팅 서버로, 여러 어댑터를 불러와 Anthropic·OpenAI·Gemini·Ollama 등과 대화할 수 있다. 환경변수에 어떤 키가 있는지 확인해 사용할 어댑터를 정하고, 핵심인 chat 함수가 에이전트형 채팅을 구동한다. 그 스트림을 SSE(server-sent event) 응답 스트림으로 변환하면 서버 쪽 설정은 끝난다.

웹 클라이언트는 useChat 훅(예제에서는 useGuitarRecommendationChat으로 감싼 형태)을 사용한다. 이 훅이 서버에서 SSE로 보내온 AG-UI 형식 메시지를 화면에 렌더링할 구조로 바꿔준다. 브라우저 네트워크 탭을 열면 각 데이터 패킷의 키와 값이 AG-UI 스펙에 따라 구조화되어 있음을 확인할 수 있다.

데스크톱 쪽 Zig 구현에서는 main.zig가 XML로 정의된 UI(열·행·스크롤 영역·상태바·입력 필드 등)를 불러온다. JSX와 달리 이 XML은 선언적 if·else와 for 반복으로 채팅 메시지를 표시한다. AG-UI 모듈은 SSE로 받은 텍스트를 Zig 내장 JSON 파서로 해석해, 토큰 단위의 텍스트 메시지 콘텐츠와 도구 호출 종료(tool call end) 같은 중요한 정보를 찾아 기타 추천 UI에 매핑한다.

주요 인사이트

• 표준 프로토콜의 힘: AG-UI 같은 공통 스펙을 채택하면 클라이언트와 서버를 서로 다른 언어·프레임워크로 만들어도 부담 없이 교체·연결할 수 있다.
• 어댑터 패턴으로 LLM 공급자를 유연하게: 환경변수 키에 따라 Anthropic·OpenAI·Gemini·Ollama 중 하나를 고르는 구조는 특정 공급자에 종속되지 않는 설계를 보여준다.
• SSE는 여전히 스트리밍 채팅의 실용적 토대다. 서버가 토큰을 SSE로 흘려보내고 클라이언트 훅이 이를 렌더링 구조로 바꾸는 흐름이 핵심이다.
• Zig+XML 기반의 Vercel 네이티브는 Electron·React Native의 대안으로, 가볍고 빠른 데스크톱 앱을 노리는 개발자에게 새로운 선택지가 될 수 있다.

자주 묻는 질문

관련 AI 소식