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.

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 (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