CopilotKit

• CopilotKit은 풀스택 에이전트 애플리케이션을 위한 React 기반 프론트엔드 SDK
• AG-UI 프로토콜의 창시자이자 1st Party 클라이언트 — AG-UI를 직접 만든 회사
• Chat UI, Generative UI, Shared State, HITL 워크플로를 React 훅/컴포넌트로 추상화하여 제공
• LangGraph, CrewAI, Google ADK, AWS Strands 등 모든 AG-UI 호환 백엔드와 연결 가능한 MIT 오픈소스

CopilotKit이 해결하려는 문제

에이전트 백엔드는 있는데 프론트엔드에서 이를 “제대로” 보여주고 제어하는 것은 여전히 복잡하다:

• 스트리밍 채팅 UI, 도구 호출 시각화, 상태 동기화를 매번 직접 구현해야 함
• 에이전트가 생성한 결과를 React 컴포넌트로 렌더링하는 표준 패턴이 없음
• 에이전트 실행 중 사용자 승인/편집이 필요한 HITL 워크플로가 프론트엔드에서 까다로움
• 백엔드 프레임워크마다 연결 방식이 달라 프론트엔드 코드를 재작성해야 함

CopilotKit은 이 문제를 AG-UI 프로토콜 위에 React SDK를 제공하는 방식으로 해결한다.

해당 개념이 필요한 이유

• AG-UI가 프로토콜(이벤트 표준)이라면, CopilotKit은 그 프로토콜 위에 구축된 구현체(React SDK + Runtime)
• AG-UI만으로는 프론트엔드를 밑바닥부터 만들어야 하지만, CopilotKit은 즉시 사용 가능한 UI 컴포넌트와 훅을 제공
• 프로토콜과 구현체의 관계를 이해해야 에이전트 앱 설계 시 올바른 레이어를 선택할 수 있음

AS-IS: AG-UI 프로토콜만으로 직접 구현

sequenceDiagram
    autonumber
    participant Dev as 개발자
    participant FE as React Frontend
    participant AGUI as AG-UI Client
    participant Agent as AI Agent

    Dev->>FE: 채팅 UI 직접 구현
    Dev->>FE: 스트리밍 파싱 로직 구현
    Dev->>FE: 상태 동기화 로직 구현
    Dev->>FE: 도구 호출 렌더링 구현
    Dev->>FE: HITL 승인 UI 구현
    FE->>AGUI: HttpAgent 직접 연결
    AGUI->>Agent: runAgent(input)
    Agent-->>AGUI: BaseEvent stream
    AGUI-->>FE: 이벤트 수동 처리
    Note over Dev,FE: 모든 UI/로직을<br/>밑바닥부터 구현

TO-BE: CopilotKit SDK 사용

sequenceDiagram
    autonumber
    participant Dev as 개발자
    participant CK as CopilotKit
    participant RT as Copilot Runtime
    participant Agent as AI Agent

    Dev->>CK: CopilotSidebar + useAgent
    Note over Dev,CK: 3줄로 채팅 UI 완성
    CK->>RT: AG-UI 이벤트 (자동)
    RT->>Agent: 라우팅 + 인증 + 미들웨어
    Agent-->>RT: 네이티브 이벤트
    RT-->>CK: AG-UI 표준 이벤트
    CK-->>CK: 자동 스트리밍 렌더링
    CK-->>CK: Generative UI 자동 마운트
    CK-->>CK: Shared State 동기화
    Note over Dev,CK: UI/상태/인증을<br/>SDK가 처리

아키텍처

graph TB
    subgraph "Frontend - React"
        A["CopilotKit Provider"]
        B["CopilotSidebar / CopilotPopup"]
        C["useAgent / useCoAgent"]
        D["useCopilotAction (Frontend Tools)"]
        E["Generative UI Components"]
    end

    subgraph "Backend"
        F["Copilot Runtime"]
        G["AG-UI Middleware"]
        H["Agent Router"]
    end

    subgraph "Agent Backends"
        I["LangGraph"]
        J["CrewAI"]
        K["Google ADK"]
        L["Built-in Agent"]
    end

    A --> B
    A --> C
    A --> D
    A --> E
    B --> F
    C --> F
    F --> G
    G --> H
    H --> I
    H --> J
    H --> K
    H --> L

핵심 구성 요소

레이어	구성 요소	역할
Provider	<CopilotKit>	최상위 컨텍스트. runtimeUrl로 Runtime 연결
Prebuilt UI	<CopilotSidebar>, <CopilotPopup>	즉시 사용 가능한 채팅 컴포넌트
Hooks	useAgent, useCoAgent	에이전트 상태 접근·제어. AG-UI 위에 직접 위치
Frontend Tools	useCopilotAction	에이전트 → 프론트엔드 액션 핸드오프
Generative UI	Tool Rendering, State Rendering	에이전트 출력을 React 컴포넌트로 렌더링
Runtime	CopilotRuntime	서버사이드 엔드포인트. 인증, 라우팅, 미들웨어

주요 기능

1. Chat UI (프리빌트 컴포넌트)

import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-core/v2";
import "@copilotkit/react-ui/v2/styles.css";
 
export default function App() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit">
      <YourApp />
      <CopilotSidebar />
    </CopilotKit>
  );
}

스트리밍, 도구 호출, 에이전트 응답을 자동으로 처리하는 완성형 채팅 UI.

1-1. Headless UI 모드

프리빌트 컴포넌트(<CopilotSidebar>)가 제공하는 UI 대신 로직(에이전트 통신, 메시지 관리, 스트리밍)만 훅으로 받아서 UI를 100% 직접 구현하는 방식이다. 레이아웃이 완전히 다르거나, 기존 UI에 채팅을 임베드하거나, 채팅이 아닌 인터페이스를 만들 때 사용한다.

import { useAgent, useCopilotKit } from "@copilotkit/react-core/v2";
 
export function CustomChat() {
  const { agent } = useAgent();
  const { copilotkit } = useCopilotKit();
 
  const sendMessage = async (content: string) => {
    agent.addMessage({ id: crypto.randomUUID(), role: "user", content });
    await copilotkit.runAgent({ agent });
  };
 
  return (
    <MyCustomLayout>
      {agent.messages.map(msg => (
        <MyBubble key={msg.id}>{msg.content}</MyBubble>
      ))}
      <MyInput onSubmit={sendMessage} />
    </MyCustomLayout>
  );
}

방식	CopilotKit이 제공	개발자가 구현
Prebuilt (<CopilotSidebar>)	로직 + 완성된 UI	없음
Headless (useAgent 훅)	로직만 (메시지, 스트리밍, 에이전트 통신)	UI 전체

2. useAgent 훅

const { agent } = useAgent({ agentId: "my_agent" });
 
// 에이전트 상태 읽기/쓰기
return (
  <div>
    <h1>{agent.state.city}</h1>
    <button onClick={() => agent.setState({ city: "NYC" })}>
      Set City
    </button>
  </div>
);

useCoAgent의 상위 호환. AG-UI 위에 직접 위치하여 에이전트 연결을 프로그래밍 방식으로 제어.

3. Generative UI

에이전트가 대화 맥락에 따라 어떤 React 컴포넌트를 언제 보여줄지 동적으로 결정하는 패턴이다. 개발자는 컴포넌트를 “도구(tool)“로 등록만 해두고, 에이전트가 필요할 때 호출하여 채팅에 렌더링한다.

// 개발자: WeatherCard 컴포넌트를 "도구"로 등록만 해둠
useComponent({
  name: "showWeatherCard",
  description: "날씨 카드를 채팅에 표시",
  parameters: z.object({ city: z.string() }),
  render: WeatherCard,
});
// → 에이전트가 "서울 날씨를 보여줘야겠다"고 판단하면
//   showWeatherCard({ city: "서울" })를 호출
//   → WeatherCard가 채팅에 렌더링됨

Headless UI와 Generative UI 비교 — “누가 UI를 결정하는가”

두 방식 모두 개발자가 React 컴포넌트를 작성한다. 차이는 **“그 컴포넌트가 화면에 나타나는 시점과 조건을 누가 결정하느냐”**이다:

	Headless UI	Generative UI
UI를 누가 결정?	개발자 (코드에 하드코딩)	AI 에이전트 (대화 맥락에 따라 동적으로)
CopilotKit이 주는 것	로직만 (훅)	컴포넌트를 호출하는 도구(tool) 시스템
사용 시점	완전히 커스텀한 레이아웃이 필요할 때	에이전트가 상황에 맞는 UI를 동적 생성할 때

← 개발자 제어권 높음                        AI 제어권 높음 →

  Headless UI          Prebuilt UI          Generative UI
  ──────────────────────────────────────────────────────────
  개발자가 UI 전체      CopilotKit이          에이전트가 어떤
  직접 구현             완성된 UI 제공         컴포넌트를 언제
                                             보여줄지 결정

훅 의존 관계 (코드 레벨 검증)

소스 코드 분석으로 확인한 실제 관계:

useComponent (v2)                          ← UI 렌더링 특화 (handler 없음)
    │  내부에서 useFrontendTool 호출
    ↓
useFrontendTool (v2)                       ← 기반 구현 (handler + render)
    └─→ copilotkit.addTool() 직접 호출

useCopilotAction (v1, legacy)              ← 하위 호환용
    └─→ useFrontendTool (v1 브릿지)
            └─→ useFrontendTool (v2)       ← 동일한 기반 구현으로 위임

• useComponent는 useFrontendTool의 기능을 줄인 편의 래퍼 — handler를 빼고 render만 남김
• useFrontendTool (v2)가 독립적인 기반 구현 — copilotkit.addTool()을 직접 호출
• useCopilotAction (v1)은 deprecated는 아니지만 **“legacy for backwards compatibility”**로 명시 — 내부에서 v2 useFrontendTool로 위임

훅	버전	handler (액션)	render (UI)	용도
useFrontendTool	v2	✅ 필수	✅ 선택적	액션 실행 + UI (범용)
useComponent	v2	❌ 없음	✅ 필수	UI 렌더링만 (Generative UI)
useCopilotAction	v1	✅	✅ 선택적	legacy — v2에서는 useFrontendTool 사용

// useFrontendTool — 액션 실행 + UI 표시 (둘 다 가능)
useFrontendTool({
  name: "addToCart",
  parameters: z.object({ productId: z.string() }),
  handler: async ({ productId }) => {     // ← 액션 실행
    await api.addToCart(productId);
    return "추가 완료";
  },
  render: ({ status, args }) => (          // ← UI 표시 (선택적)
    <CartConfirmation status={status} product={args.productId} />
  ),
});
 
// useComponent — UI 표시만 (handler 없음)
useComponent({
  name: "showWeatherCard",
  parameters: z.object({ city: z.string() }),
  render: WeatherCard,                     // ← 이것만
});

UI 모드와 훅의 연결

UI 모드	사용하는 훅	개발자의 역할	에이전트의 역할
Headless	useAgent, useCopilotKit	레이아웃 + 컴포넌트 전부 구현	로직만 (메시지, 상태)
Prebuilt	<CopilotSidebar> 등	없음 (바로 사용)	채팅에 텍스트 응답
Generative	useFrontendTool, useComponent	컴포넌트를 도구로 등록	어떤 컴포넌트를 언제 보여줄지 결정

Generative UI 3가지 타입

타입	설명	프로토콜
Static	앱이 제어하는 안정적 컴포넌트 렌더링	AG-UI
Declarative	에이전트가 UI 트리 제안, 앱이 검증·마운트	A2UI
Open-Ended	MCP Apps, Open JSON UI	MCP

4. Copilot Runtime

서버사이드 백엔드 레이어:

• 인증/보안: API 키를 서버에 보관, 클라이언트 노출 방지
• Agent Routing: 복수 에이전트 자동 탐색·라우팅 ("default" 에이전트 지원)
• AG-UI Middleware: 로깅, 가드레일, 요청 변환을 서버에서 실행
• Built-in Middleware: A2UI, MCP Apps를 설정 한 줄로 활성화

const runtime = new CopilotRuntime({
  agents: {
    "default": new HttpAgent({ url: "https://my-agent.example.com" }),
  },
  a2ui: {},         // A2UI 자동 활성화
  mcpApps: {        // MCP 서버 연결
    servers: [
      { type: "http", url: "http://localhost:3108/mcp", serverId: "my-server" },
    ],
  },
});

AG-UI와의 관계

AG-UI Protocol (표준)
  └── CopilotKit (구현체, 1st Party Client)
        ├── React SDK (프론트엔드 훅/컴포넌트)
        ├── Copilot Runtime (백엔드 미들웨어/라우팅)
        └── Copilot Cloud (프리미엄: observability, threads)

• AG-UI는 프로토콜 스펙 — 이벤트 타입, 흐름 패턴, 전송 규격을 정의
• CopilotKit은 AG-UI 위의 SDK — 프로토콜을 React 컴포넌트와 서버 런타임으로 구현
• AG-UI 프로토콜 자체를 직접 사용할 수도 있지만(HttpAgent 직접 연결), CopilotKit 없이는 인증, 라우팅, UI 컴포넌트를 모두 직접 구현해야 함

지원 프레임워크

프레임워크	상태
Built-in Agent	✅ (프레임워크 불필요)
LangGraph	✅
Google ADK	✅
Microsoft Agent Framework	✅
AWS Strands	✅
Mastra	✅
Pydantic AI	✅
CrewAI Flows	✅
Agno, AG2, LlamaIndex	✅

참고 문서

• CopilotKit GitHub
• CopilotKit Documentation
• Copilot Runtime 설정
• AG-UI Protocol
• Generative UI
• useAgent API Reference
• Headless UI
• useComponent Hook