CopilotKit：全栈 AI 에이전트, 생성적 UI 및 채팅 애플리케이션을 구축하기 위한 최고의 SDK
CopilotKit：全栈 AI 에이전트, 생성적 UI 및 채팅 애플리케이션을 구축하기 위한 최고의 SDK
배경 개요
CopilotKit은 AI Copilot 및 에이전트 네이티브 애플리케이션 구축을 위해 설계된 오픈 소스 프레임워크로, GitHub 별표 수가 28.9k를 초과하며 10만 명 이상의 개발자에 의해 사용되고 있습니다. 이 프레임워크의 핵심 가치는 AI 에이전트를 사용자 인터페이스와 깊이 통합하여 에이전트가 실시간으로 UI를 제어하고, 컨텍스트 정보를 전달하며, 생성적 UI를 통해 동적으로 인터페이스 구성 요소를 렌더링할 수 있도록 하는 것입니다.
핵심 발견
1. 아키텍처 설계 및 핵심 기능
CopilotKit은 프론트엔드 컴포넌트 레이어, CopilotRuntime 런타임 레이어 및 에이전트 연결 레이어를 포함하는 3계층 아키텍처 설계를 채택하고 있습니다.
프론트엔드 컴포넌트 레이어는 완전 무헤드(Headless) UI에서 미리 구축된 사용자 정의 가능한 컴포넌트의 전체 스펙트럼을 제공하며, 개발자는 필요에 따라 유연하게 선택할 수 있습니다. CopilotRuntime은 백엔드 오케스트레이션 엔진으로, 프론트엔드 클라이언트로부터의 요청을 처리하고 LLM 호출 및 에이전트 상호작용을 관리합니다. 에이전트 연결 레이어는 AG-UI 프로토콜을 통해 LangGraph, CrewAI, LlamaIndex 등 모든 에이전트 프레임워크와 연결됩니다.
CopilotKit의 핵심 기능에는 생성적 UI(Generative UI)가 포함되어 있어 에이전트가 실행 중에 UI 구성 요소를 동적으로 렌더링할 수 있습니다. 공유 상태(Shared State)는 프론트엔드와 에이전트 간의 양방향 상태 동기화를 구현하며, Human-in-the-Loop(인간 협업)는 에이전트가 실행 과정에서 인간의 입력이나 승인을 요청할 수 있도록 지원합니다. 이러한 기능들은 단순한 질문 응답 시스템이 아닌 진정으로 상호작용하는 AI 애플리케이션을 구축할 수 있게 합니다.
작업 흐름 개요:
2. AG-UI 프로토콜: 생태계의 초석
AG-UI(Agent-User Interaction Protocol)는 CopilotKit 팀이 출시한 개방적이고 경량화된 이벤트 기반 프로토콜 표준으로, AI 에이전트와 사용자 지향 애플리케이션 간의 통신 방식을 표준화하는 것을 목표로 합니다. 이 프로토콜은 Google, Microsoft, AWS, LangChain, Mastra, Pydantic AI 등 주요 업체와 프레임워크에 의해 광범위하게 채택되어 점점 더 커지는 생태계를 형성하고 있습니다.
AG-UI 프로토콜은 전통적인 프론트엔드-백엔드 통신 모델(요청-응답)이 에이전트 애플리케이션의 복잡한 요구를 충족할 수 없다는 핵심 문제를 해결합니다. 에이전트는 실시간으로 상태 업데이트를 스트리밍하고, 중단 및 승인 프로세스를 처리하며, UI와 에이전트 상태를 동기화해야 하며, 이는 더 유연한 통신 메커니즘이 필요합니다. AG-UI는 이벤트 스트리밍을 통해 이러한 기능을 구현하여 실시간 텍스트 스트림, 도구 호출, 상태 동기화 및 사용자 정의 이벤트를 지원합니다.
현재 에이전트 프로토콜 분야는 세 가지 기둥이 공존하는 구조를 보이고 있습니다: AG-UI는 에이전트와 사용자 상호작용 레이어에 집중하고, MCP(Model Context Protocol)는 에이전트와 도구 및 데이터의 연결을 담당하며, A2A(Agent-to-Agent)는 에이전트 간의 조정 통신을 처리합니다. 주목할 점은 AG-UI가 A2A 프로토콜과의 핸드쉐이크 통합을 구현했으며, 생성적 UI 렌더링을 위한 Google의 A2UI 규격을 전면적으로 지원한다는 것입니다.
3. 주요 프레임워크와의 통합
CopilotKit과 LangGraph의 통합은 가장 성숙한 사용 사례 중 하나입니다. 간단한 구성으로 개발자는 LangGraph 에이전트를 CopilotKit 프론트엔드에 연결하여 상태 공유 및 실시간 스트리밍 응답을 구현할 수 있습니다. 통합 과정은 일반적으로 useCoAgent 훅을 사용하여 에이전트를 연결하고, copilotkitemitstate 함수를 통해 에이전트 측에서 상태 업데이트를 발사하며, useCopilotAction을 사용하여 인간-기계 협업 중단점을 정의하는 것을 포함합니다.
CrewAI 개발자에게 CopilotKit은 마찬가지로 즉시 사용할 수 있는 통합 솔루션을 제공합니다. AG-UI 프로토콜을 통해 개발자는 모든 CrewAI 에이전트를 실시간 상호작용을 지원하는 프론트엔드 애플리케이션으로 노출할 수 있습니다. LangGraph와 CrewAI 외에도 AG-UI 프로토콜은 Microsoft Agent Framework, Google ADK, AWS Strands Agents, Mastra, Pydantic AI, Agno, LlamaIndex 등 많은 프레임워크를 지원하여 진정한 다중 프레임워크 상호 운용성을 형성합니다.
4. 유사 프레임워크와의 비교 분석
Vercel AI SDK와 비교할 때, CopilotKit의 포지셔닝은 상당한 차이를 보입니다. Vercel AI SDK는 주로 채팅 인터페이스의 스트리밍 텍스트 전송을 간소화하는 데 집중하며, 뛰어난 useChat 훅과 UI 구성 요소를 제공합니다. 반면 CopilotKit은 깊은 에이전트 통합, 생성적 UI 및 인간-기계 협업 능력을 더 강조합니다.
LangChain과의 관계는 경쟁보다는 상호 보완적입니다. LangChain은 에이전트의 "두뇌"(논리 및 워크플로우)를 구축하는 데 중점을 두고, CopilotKit은 해당 두뇌의 "얼굴, 목소리 및 손"—즉, 애플리케이션과 상호작용하는 인터페이스를 제공합니다. 개발자는 일반적으로 LangChain/LangGraph를 사용하여 에이전트 논리를 정의한 다음, CopilotKit을 통해 사용자 상호작용 레이어를 구축합니다.
5. 전형적인 응용 사례
CopilotKit의 전형적인 사용 사례는 여러 분야를 포괄합니다. SaaS Copilot은 가장 일반적인 응용 사례로, 스마트 어시스턴트가 사용자가 복잡한 작업 흐름을 완료하도록 안내하며, 상황 인식 도움을 제공합니다. 공동 창작 Copilot은 인간-기계 협업을 강조하며, AI와 사용자가 함께 콘텐츠를 생성하여 생산성을 크게 향상시킵니다. 대화형 양식 작성은 복잡한 양식을 자연스러운 대화 상호작용으로 변환하여 사용자가 채팅을 통해 복잡한 데이터 입력을 완료할 수 있도록 합니다. 연구 에이전트 애플리케이션은 공식 시연의 연구 캔버스 애플리케이션과 같이 LangGraph 에이전트를 프론트엔드와 깊이 통합하여 연구 개요 생성, 장 작성 및 인간 승인 과정을 완전하게 보여줍니다.
빠른 시작: 코드 예제
기본 통합 예제
다음은 CopilotKit과 LangGraph 통합을 사용하는 최소 실행 가능한 예제입니다:
프론트엔드(Next.js/React):
// app/page.tsx "use client"; import { CopilotKit } from "@copilotkit/react-core"; import { CopilotPopup } from "@copilotkit/react-ui"; import "@copilotkit/react-ui/styles.css";
export default function Home() { return (
연구 도우미
); }런타임 API 라우트:
// app/api/copilotkit/route.ts import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/runtime"; import { NextRequest } from "next/server";const copilotKit = new CopilotRuntime({ remoteEndpoints: [ { url: process.env.LANGGRAPHURL || "http://localhost:8000" }, ], });
const serviceAdapter = new OpenAIAdapter();
export const POST = async (req: NextRequest) => { const { handleRequest } = copilotKit; return handleRequest(req, { serviceAdapter }); };
공유 상태 예제
// useCoAgent를 사용하여 프론트엔드와 백엔드 상태 동기화 구현 import { useCoAgent } from "@copilotkit/react-core";
function ResearchCanvas() { const { state, setState } = useCoAgent({ name: "researchagent", initialState: { topic: "", outline: [], currentSection: null, }, });
return (
setState({ ...state, topic: e.target.value })} placeholder="연구 주제 입력" />
); }
인간-기계 협업(Human-in-the-Loop) 예제
import { useCopilotAction } from "@copilotkit/react-core";
function DocumentEditor() { useCopilotAction({ name: "publishDocument", description: "문서를 게시하기 전에 사용자의 확인이 필요합니다.", parameters: [ { name: "title", type: "string", description: "문서 제목" }, { name: "content", type: "string", description: "문서 내용" }, ], handler: async ({ title, content }) => { const confirmed = await new Promise((resolve) => { showConfirmDialog({ title, content, onConfirm: resolve }); });
if (confirmed) { await api.publish({ title, content }); return "문서가 성공적으로 게시되었습니다."; } return "게시가 취소되었습니다."; }, });
return ...; }`
전형적인 응용 사례
사례 1: SaaS 스마트 어시스턴트
장면: 기업급 프로젝트 관리 도구로, AI 어시스턴트를 통합하여 사용자가 빠르게 작업을 생성하고, 자원을 할당하며, 보고서를 생성하도록 돕습니다.
구현 요점:
- CopilotKit의 공유 상태 기능을 사용하여 AI가 현재 프로젝트 뷰를 실시간으로 이해하도록 합니다.
- 생성적 UI를 통해 작업 카드, 간트 차트 등의 컴포넌트를 동적으로 렌더링합니다.
- 인간-기계 협업 노드는 중요한 작업(예: 프로젝트 삭제)이 사용자의 확인을 필요로 하도록 보장합니다.### 사례 2: AI 연구 도우미
실현 요점:
- LangGraph 에이전트는 정보 검색 및 논리 추론을 담당합니다.
- CopilotKit 프론트엔드는 연구 개요 및 문헌 목록을 표시합니다.
- 상태 동기화는 연구 진행 상황을 실시간으로 저장하고 표시합니다.
- 승인 노드는 외부 자료를 인용할 때 사용자에게 확인을 요청합니다.
사례 3: 스마트 양식 작성
장면: 복잡한 보험 신청서를 대화형 상호작용으로 변환합니다.
실현 요점:
- 에이전트는 사용자의 답변에 따라 동적으로 다음 질문을 결정합니다.
- 조건 렌더링을 사용하여 문맥에 따라 다른 UI 구성 요소를 표시합니다.
- 부분적으로 완료된 양식을 자동 저장하여 중단된 지점에서 계속 작성할 수 있도록 지원합니다.
- 제출 전에 모든 정보를 요약하여 사용자가 확인할 수 있도록 합니다.
기술적 통찰
CopilotKit의 기술 구현은 현대 웹 스택을 기반으로 합니다. 프론트엔드는 React(Angular도 지원)를 주요 UI 프레임워크로 사용하며, 상태 관리 및 에이전트 상호작용을 위한 useAgent 및 useCoAgent와 같은 훅을 제공합니다. 백엔드는 CopilotRuntime 클래스를 중앙 조정기로 실행하여 요청 검증, LLM 호출 및 응답 스트리밍을 처리합니다. 통신 프로토콜은 Server-Sent Events(SSE)를 사용하여 서버에서 클라이언트로의 실시간 스트림 푸시를 구현하며, HTTP POST를 통해 클라이언트 요청을 처리합니다.
v1.50 버전은 주요 아키텍처 업그레이드를 가져오며, 더 명확한 단일 엔드포인트 아키텍처, 향상된 관측 가능성(원거리 측정 내장) 및 CopilotKit Next와의 깊은 통합을 도입하여 개발 경험을 더욱 간소화합니다.
