CopilotKit — 에이전트가 UI를 직접 제어하는 풀스택 SDK의 구조

AI 채팅창 말고, 에이전트가 화면을 바꾸는 앱

에이전트를 앱에 붙이면 대부분 채팅창 하나가 생깁니다. 사용자가 물어보고, 에이전트가 텍스트로 답합니다. 그게 전부입니다. CopilotKit은 다른 질문에서 출발합니다. 에이전트가 앱의 상태를 직접 읽고, 쓰고, UI 컴포넌트를 런타임에 생성할 수 있다면 어떨까요?

---

이 SDK가 푸는 문제

에이전트 앱을 만들 때 가장 답답한 지점은 에이전트와 UI 사이의 단절입니다. 에이전트는 내부에서 상태를 바꿨는데, 화면은 그걸 모릅니다. 따로 API 레이어를 만들고, 상태 동기화 로직을 쓰고, 에이전트가 멈춰야 할 타이밍을 수동으로 처리해야 합니다.

CopilotKit은 이 단절을 세 가지로 해결합니다.

1. Shared State — 에이전트와 UI 컴포넌트가 같은 상태 레이어를 읽고 씁니다. 에이전트가 city를 바꾸면 화면의 <h1>이 즉시 업데이트됩니다.
2. Generative UI — 에이전트가 워크플로 안에서 UI 컴포넌트를 동적으로 생성합니다. 텍스트 응답이 아니라 실제 렌더링된 컴포넌트입니다.
3. Human-in-the-Loop — 에이전트가 실행 중간에 사용자 입력, 확인, 수정을 요청하고 멈출 수 있습니다.

---

핵심 동작 원리

CopilotKit의 중심은 AG-UI Protocol입니다. Google, LangChain, AWS, Microsoft, Mastra, PydanticAI가 채택한 에이전트-UI 상호작용 프로토콜로, CopilotKit이 이 프로토콜을 주도합니다.

연결 구조는 단순합니다. UI → 에이전트 → 도구(Tool) → UI 렌더링이 하나의 루프로 묶입니다.

useAgent 훅이 이 루프의 진입점입니다.

const { agent } = useAgent({ agentId: 'my_agent' });

return (
  <div>
    <h1>{agent.state.city}</h1>
    <button onClick={() => agent.setState({ city: 'NYC' })}>
      Set City
    </button>
  </div>
);

useAgent는 useCoAgent의 상위 집합(superset)으로, AG-UI 위에 직접 올라갑니다. 에이전트 상태를 읽고, 업데이트하고, 에이전트 실행을 프로그래매틱하게 제어할 수 있습니다.

---

설치 및 시작

새 프로젝트를 시작할 때:

npx copilotkit@latest create -f <framework>

기존 프로젝트에 붙일 때:

npx copilotkit@latest init

init 하나로 다음이 세팅됩니다.

• 핵심 패키지 설치 완료
• Context, State, Hook 사용 준비
• 에이전트-UI 연결 완료 (에이전트가 즉시 액션 스트림 및 UI 렌더링 가능)
• 배포 준비 상태

---

실전 예시: LangGraph 에이전트와 연결

LangGraph 에이전트가 여행 도시를 추천하고, UI가 즉시 그 상태를 반영하는 시나리오입니다.

# LangGraph 에이전트 노드 예시
def recommend_city(state):
    # 에이전트 로직
    state["city"] = "Tokyo"
    return state

// React UI에서 에이전트 상태를 구독
const { agent } = useAgent({ agentId: 'travel_agent' });

return <h1>추천 도시: {agent.state.city}</h1>;

에이전트가 city를 업데이트하는 순간 화면이 바뀝니다. 별도 WebSocket 설정이나 폴링 로직 없이 공유 상태 레이어가 처리합니다.

---

언제 쓰면 안 되는가

CopilotKit은 React 기반 풀스택 앱에서 에이전트와 UI를 타이트하게 통합할 때 강점이 있습니다. 반대로 다음 경우에는 맞지 않습니다.

• 에이전트가 백엔드 파이프라인만 처리하고 UI 피드백이 필요 없는 경우
• Vue, Svelte, Angular 등 React가 아닌 프레임워크를 쓰는 경우 (현재 React 중심)
• 단순 챗봇 하나만 붙이면 되는 경우 — 이 경우 오버스펙입니다
• 에이전트 프레임워크를 아직 결정하지 않은 초기 단계 — AG-UI 통합 에이전트가 전제입니다

---

같은 카테고리 대안 비교

도구	특징	한계
Vercel AI SDK	스트리밍 UI, 간단한 채팅 통합	에이전트 상태 공유 레이어 없음
LangChain LCEL	체인 구성, 다양한 모델 지원	UI 레이어 직접 제공 안 함
CopilotKit	에이전트-UI 공유 상태, Generative UI, Human-in-the-Loop	React 생태계 전제

Vercel AI SDK가 채팅 스트리밍에 최적화된 가벼운 선택이라면, CopilotKit은 에이전트가 앱 UI를 제어해야 하는 더 복잡한 워크플로에 맞습니다.

---

마무리

CopilotKit은 'AI 채팅을 앱에 추가하는 도구'가 아닙니다. 에이전트가 앱의 상태와 UI를 직접 제어하는 루프를 만드는 SDK입니다. AG-UI Protocol 위에서 LangGraph, CrewAI, PydanticAI 등과 1st-party 통합을 지원하기 때문에, 에이전트 프레임워크를 이미 쓰고 있는 팀이라면 연결 비용이 낮습니다.

Generative UI와 Human-in-the-Loop까지 함께 쓰면, 에이전트가 단순 응답기가 아니라 앱의 실제 협업자로 동작하는 구조를 만들 수 있습니다. LangGraph 에이전트 앱을 React 프론트엔드와 연결하려는 팀이면 npx copilotkit@latest init부터 구조를 먼저 확인해볼 만합니다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: AI 인사이트
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독