프레임워크

CopilotKit: AG-UI 프로토콜로 Agent를 Web·Slack·Teams까지 연결하는 오픈소스 미들웨어

GitHub에서 36.8K star를 받은 CopilotKit은 단순한 React 채팅 UI가 아니라 AG-UI 프로토콜 기반의 통신 계층이다. Agent·웹·모바일·Slack·Teams를 하나의 표준으로 묶어 프런트엔드 통합 비용을 크게 줄여준다.

글자 크기

이게 왜 필요한가

Agent 백엔드 프레임워크는 지난 2년 새 격차가 무서울 정도로 벌어졌다. LangGraph, AutoGen, LlamaIndex, CrewAI 중 무엇을 고를지부터 고민이고, 프런트엔드 쪽은 아예 방치돼 있다. Agent가 내뱉는 token stream은 어떻게 렌더하지? Agent가 사용자 확인을 요청할 때는? Agent가 폼을 띄우거나 차트를 바꿔야 한다면 UI 쪽은 어떻게 반응해야 할까?

이런 질문만 10번은 받았다. 다들 LangGraph agent까지는 잘 돌리는데, 웹에 붙이는 순간 멘붕이 온다. SSE를 손으로 처리하고, tool_call을 파싱하고, 중간 상태를 React state에 밀어넣는 등 300줄짜리 접착 코드부터 깔고, 정작业务 로직은 아직 한 줄도 못 짜는 상황이 반복된다.

CopilotKit은 Agent와 사용자 사이의 중간 계층을 노린다. 동일한 Agent 하나로 React 웹앱을驱动하고, Slack·Microsoft Teams·iMessage에서도 돌리고, Human-in-the-loop 승인 흐름까지 처리한다. Agent 프레임워크의 영역을 침범하지 않고 "마지막 1마일"만 책임진다. Agent 출력을 받아내고, UI 피드백을 다시 전달하는 일만 한다.

분석 시점 기준 저장소 star 36,880, MIT 라이선스, 주력 언어 TypeScript, Python Runtime도 함께 제공한다.

사용법

다음 한 줄이면 스캐폴드가 생성된다.

npx copilotkit@latest create

OpenAI 또는 Anthropic 키만 넣으면 바로 실행된다. 코드 측면에서 가장 작은 예시는 다음과 같다.

import { CopilotKit } from "@copilotkit/react-core";
import { CopilotChat } from "@copilotkit/react-ui";

function App() {
  return (
    
      
    
  );
}

Python 백엔드는 FastAPI에 Runtime을 마운트한다.

from copilotkit import CopilotKitSDK, LangGraphAgent
from fastapi import FastAPI

app = FastAPI()
sdk = CopilotKitSDK(
    agents=[
        LangGraphAgent(
            name="order_agent",
            graph=my_langgraph,
            # 关键:声明前端可调用的 tool
            frontend_tools=["update_order_status", "render_invoice"],
        )
    ]
)
app.mount("/api/copilotkit", sdk)

Agent는 백엔드 tool만 호출하는 게 아니라 "프런트엔드 tool"도 호출할 수 있다. 예를 들어 update_order_status를 부르면 UI 쪽 표에서 변경된 행이 실시간으로 하이라이트된다. WebSocket으로 이벤트를 밀어넣고 사용자가 직접 파싱하는 방식이 아니라, CopilotKit이 상태 동기화를 알아서 처리한다.

동작 방식

아키텍처는 세 계층이다.

① AG-UI 프로토콜 계층 — SSE 기반 이벤트 스트림 프로토콜로, Agent와 프런트엔드 사이의 16가지 이벤트 타입을 정의한다. 메시지, tool 호출, 상태 동기화, 사람 개입 요청 등을 모두 커버한다. AG-UI는 CopilotKit 팀이 올해 7월 기부한 개방형 프로토콜이며, Google, LangChain, AWS, Microsoft, Mastra, PydanticAI가 채택했다. 오픈소스가主導한 Agent 통신 표준이라 드문 사례다.

② CopilotKit Runtime — Node 또는 Python 백엔드로, 사용자의 Agent 프레임워크와 브릿지 역할을 한다. LangGraph, AutoGen, 직접 짠 ReAct 어떤 것을 쓰든 LangGraphAgent나 AutogenAgent로 한 번 감싸면 Runtime이 출력을 AG-UI 이벤트로 변환해준다.

③ 프런트엔드 SDK — React, Angular, Vue, React Native, Slack, Microsoft Teams용 어댑터 계층이다. 핵심 패키지인 @copilotkit/react-core는 npm 공용 registry에 배포되며, 프로토콜 이벤트를 렌더링 가능한 UI 컴포넌트로 번역한다.

이 아키텍처에서 가장 가치가 크다고 느낀 부분은 AG-UI 자체가 아니라 Shared State다. Agent와 프런트엔드가 동일한 상태 객체를 공유한다. Agent는 UI 상태(예: "사용자가 현재 어느 주문을 보고 있다")를 읽을 수 있고, UI는 Agent의 상태 변화(예: "Agent가 주문을 배송중으로 변경했다")에 반응한다. 양방향 동기화가 손으로 짜는 reconcile 없이 동작한다.

장점과 단점

좋은 점:

  • AG-UI는 오픈소스가主导한 몇 안 되는 Agent 통신 표준이다. Google·AWS·Microsoft가 동시에 동의한 사례로, Agent 생태계에서는 매우 드물다.
  • 다중 플랫폼 통합이 실제痛点다. Web, Slack, Teams, iMessage에서 동일한 Agent를 돌리는데 재활용되는 것은 백엔드 로직이지 UI 코드가 아니다.
  • Generative UI(Agent가 동적으로 어떤 컴포넌트를 띄울지 결정) 기능이 Vercel AI SDK보다 깊다. Vercel의 streamUI가 주로 "token 스트림 렌더링"을 해결하는 반면, CopilotKit은 Agent가 완전한 폼·차트·승인 카드를主动 생성하게 할 수 있다.

아쉬운 점:

  • 한글/中文 문서가 얇다. 공식 docs는 영어 우선이고, 커뮤니티 번역은 들쑥날쑥하다.
  • Angular, Vue, React Native 지원은 React보다 눈에 띄게 약하다. React가 first-class이고, 다른 플랫폼도 쓸 수는 있지만 API가 완전히 갖춰지지 않았다.
  • 36.8K star 중 상당 부분이 AG-UI 프로토콜의 후광 효과이고, 실제 SDK 사용 난이도는 LangChain보다 높다. LangChain은 개념이 단순한 편이지만, CopilotKit은 Runtime·Agent·Tool·State 네 계층을 이해해야 해서 초보자 진입 곡선이 가파르다.
  • 핵심 패키지 @copilotkit/react-core의 gzip 후 크기는 약 80KB다. SDK 용량에 민감한 소규모 프로젝트에서는 부담될 수 있다.

직접 써봤다

공식 create 스캐폴드로 React + Python FastAPI 백엔드 demo를 5분 만에 띄웠다. LangGraph Agent를 붙여 update_order_status 프런트엔드 tool을 호출하게 했더니, UI 쪽 표에서 변경된 행이 실시간으로 하이라이트됐다.

Shared State 동기화 지연은 육안으로 거의 보이지 않았다. console에서 타임스탬프를 찍어봤는데, Agent가 tool을 호출한 시점부터 React 컴포넌트가 state 업데이트를 받기까지 간격이 50ms 이내였다.

이전에 순수 LangGraph로 SSE 스트림 처리를 직접 짜던 것과 비교하면 접착 코드가 약 200줄 줄었다. 주로 tool_call 파싱, 중간 상태 누적, 에러 재시도 세 블록이었다.

예상 밖 발견도 있었다. CopilotKit의 Generative UI는 단순히 "token 렌더링"에 그치지 않고, Agent가 <form>, <button>, <chart> 같은 완전한 컴포넌트를主动 생성하게 할 수 있다. human-in-the-loop 이벤트 타입과 결합하면, Agent가 중간에 멈춰 "제출하시겠습니까?"라고 묻고, UI에서 확인 창을 띄운 뒤 사용자가 클릭하면 Agent가 다시 이어서 진행한다. 이런 승인 흐름을 상태머신으로 직접 짤 필요가 없다.

이런 팀에 권한다

적합한 경우:

  • ToB SaaS에 AI 어시스턴트를 붙이되, Web·Slack·Teams 같은 각 플랫폼마다 다시 짜고 싶지 않은 팀. CopilotKit의 킬러 시나리오다.
  • Generative UI(Agent가 어떤 폼/차트를 띄울지 스스로 결정)를 구현하고 싶은 경우.
  • LangGraph/AutoGen은 쓰고 싶은데 프런트엔드 통합이 막막한 경우. Runtime이 이미 어댑터를 제공해준다.

맞지 않는 경우:

  • 단순히 채팅창 하나만 필요한 경우. Vercel AI SDK의 useChat가 더 가볍고 의존성도 적다.
  • SDK 용량에 민감한 소규모 프로젝트(핵심 패키지 gzip 80KB).
  • 멀티 플랫폼을 전혀 고려하지 않는 순수 CLI/순수 백엔드 Agent. CopilotKit의 가치는 프런트엔드 계층에 있으니, 그 부분을 못 쓰면 의미가 없다.

출처

출처: https://github.com/CopilotKit/CopilotKit