copilotkit

CopilotKit

Full-stack open-source framework (MIT, v1.51.3, Python SDK v0.1.78) for building agentic applications with AI copilots embedded directly in React and Angular UIs. Angular support via @copilotkitnext/​angular (Angular 18+19). 28k+ GitHub stars.

When to Use This Skill

• User wants to add an AI copilot, assistant, or chatbot to a React/​Next.js app
• User is working with CopilotKit hooks, components, or runtime
• User asks about AI-powered text areas or form completion
• User needs to connect a Python agent (LangGraph/​CrewAI) to a React frontend
• User is implementing human-in-the-loop or generative UI patterns
• User asks about AG-UI protocol or MCP Apps
• User wants to sync state between a UI and an AI agent

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   F R O N T E N D    @copilotkit/​react-core + react-ui          │
│                                                                 │
│   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐ │
│   │  <CopilotPopup>  │  │ <CopilotSidebar> │  │ <CopilotChat>│ │
│   │  <CopilotTextarea>│  │   Headless UI    │  │  Custom UI   │ │
│   └────────┬─────────┘  └────────┬─────────┘  └──────┬───────┘ │
│            └──────────────┬──────┘                    │         │
│                           ▼                           │         │
│   ┌───────────────────────────────────────────────────┘         │
│   │  React Hooks                                                │
│   │  ├─ useCopilotAction()       → Define callable tools        │
│   │  ├─ useCopilotReadable()     → Expose app state to LLM     │
│   │  ├─ useAgent()               → Bidirectional state (v2)    │
│   │  ├─ useFrontendTool()        → Generative UI rendering     │
│   │  ├─ useCopilotChat()         → Headless chat control       │
│   │  └─ useLangGraphInterrupt()  → Human-in-the-loop           │
│   └─────────────────────────┬───────────────────────────────────│
│                             │                                   │
└─────────────────────────────┼───────────────────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │    AG-UI Protocol  │
                    │  (HTTP event stream│
                    │   17 event types)  │
                    └─────────┬─────────┘
                              │
┌─────────────────────────────┼───────────────────────────────────┐
│                             │                                   │
│   B A C K E N D    @copilotkit/​runtime                          │
│                             ▼                                   │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │  CopilotRuntime                                         │   │
│   │  ┌──────────────┐ ┌───────────────┐ ┌────────────────┐ │   │
│   │  │ LLM Adapters │ │ Backend       │ │ Thread         │ │   │
│   │  │ OpenAI       │ │ Actions       │ │ Persistence    │ │   │
│   │  │ Anthropic    │ │ (server-side  │ │ InMemory /     │ │   │
│   │  │ Google       │ │  tools)       │ │ SQLite         │ │   │
│   │  │ Groq         │ │               │ │                │ │   │
│   │  └──────────────┘ └───────────────┘ └────────────────┘ │   │
│   │  ┌──────────────────────────────────────────────────┐   │   │
│   │  │ Agent Router                                     │   │   │
│   │  │ ├─ BuiltInAgent   (direct LLM + middleware)      │   │   │
│   │  │ ├─ BasicAgent     (lightweight, no middleware)    │   │   │
│   │  │ └─ CustomHttpAgent (remote Python/​JS agents) ────┼───┼─┐ │
│   │  └──────────────────────────────────────────────────┘   │ │ │
│   └─────────────────────────────────────────────────────────┘ │ │
│                                                               │ │
└───────────────────────────────────────────────────────────────┼─┘
                                                                │
                    ┌───────────────────┐                       │
                    │    AG-UI / HTTP    │◄──────────────────────┘
                    └─────────┬─────────┘
                              │
┌─────────────────────────────┼───────────────────────────────────┐
│                             ▼                                   │
│   A G E N T   L A Y E R   (optional, any AG-UI framework)      │
│                                                                 │
│   Python: copilotkit SDK v0.1.78 + FastAPI / Flask              │
│                                                                 │
│   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐  │
│   │ LangGraph  │ │  CrewAI    │ │ Google ADK │ │ AWS Strands│  │
│   └────────────┘ └────────────┘ └────────────┘ └────────────┘  │
│   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐  │
│   │  Mastra    │ │ PydanticAI │ │    AG2     │ │ LlamaIndex │  │
│   └────────────┘ └────────────┘ └────────────┘ └────────────┘  │
│                                                                 │
│   Protocols:  AG-UI (↔ user)  ·  MCP (↔ tools)  ·  A2A (↔ agents)│
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Start

New project

npx copilotkit@latest create -f next

Existing project

npm install @copilotkit/​react-core @copilotkit/​react-ui @copilotkit/​runtime

Environment

# .env.local
OPENAI_API_KEY="sk-..."
# or ANTHROPIC_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY

Backend API route (app/​api/​copilotkit/​route.ts)

import {
  CopilotRuntime,
  OpenAIAdapter, // or AnthropicAdapter, GoogleGenerativeAIAdapter, GroqAdapter, LangChainAdapter
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/​runtime";
import { NextRequest } from "next/​server";

const serviceAdapter = new OpenAIAdapter({ model: "gpt-4o" });
const runtime = new CopilotRuntime();

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/​api/​copilotkit",
  });
  return handleRequest(req);
};

Frontend provider (layout.tsx)

import { CopilotKit } from "@copilotkit/​react-core";
import "@copilotkit/​react-ui/​styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <CopilotKit runtimeUrl="/​api/​copilotkit">
          {children}
        </​CopilotKit>
      </​body>
    </​html>
  );
}

Chat UI (page.tsx)

import { CopilotPopup } from "@copilotkit/​react-ui"; // or CopilotSidebar, CopilotChat

export default function Home() {
  return (
    <>
      <YourApp />
      <CopilotPopup
        instructions="You are an AI assistant for this app."
        labels={{ title: "Assistant", initial: "How can I help?" }}
      />
    </>
  );
}

Core Hooks

useCopilotReadable -- Expose app state to LLM

useCopilotReadable({
  description: "Current user profile and preferences",
  value: { name: user.name, role: user.role, preferences },
});

useCopilotAction -- Define executable actions

useCopilotAction({
  name: "addItem",
  description: "Add a new item to the list",
  parameters: [
    { name: "title", type: "string", required: true },
    { name: "priority", type: "string", description: "low, medium, or high" },
  ],
  handler: async ({ title, priority = "medium" }) => {
    setItems(prev => [...prev, { id: Date.now().toString(), title, priority }]);
    return `Added "${title}" with ${priority} priority`;
  },
});

useCopilotChat -- Programmatic chat control

const { appendMessage, stopGeneration, reset, reloadMessages } = useCopilotChat();

useCopilotAdditionalInstructions -- Dynamic context-aware prompts

useCopilotAdditionalInstructions({
  instructions: "User is on the settings page. Help them configure preferences.",
});

useCopilotChatSuggestions -- Auto-generate suggestions from app state

useCopilotChatSuggestions({
  instructions: "Suggest actions based on the current app state.",
});

useAgent -- v2 agent state sync (superset of useCoAgent)

const { state, setState, run, stop } = useAgent({ name: "my_agent" });

useAgent is the v2 replacement for useCoAgent. It includes all useCoAgent functionality plus time-travel debugging and improved state management. Prefer useAgent for new projects.

CopilotTask -- Run one-off programmatic tasks

import { CopilotTask } from "@copilotkit/​react-core";

const task = new CopilotTask({ instructions: "Summarize the data" });
await task.run(context);

Advanced Patterns

Detailed guides organized by topic -- load only what's needed:

• Generative UI (static AG-UI, declarative A2UI, open-ended MCP Apps): See references/​generative-ui.md
• Shared State & CoAgents (useCoAgent, useAgent, bidirectional sync, LangGraph): See references/​coagents-shared-state.md
• Human-in-the-Loop (buildtime/​runtime HITL, approval flows, agent steering): See references/​human-in-the-loop.md
• Runtime & Adapters (all LLM adapters, framework endpoints, backend actions): See references/​runtime-adapters.md
• Python SDK (LangGraphAgent, FastAPI, actions, state, events): See references/​python-sdk.md
• Styling & Customization (CSS, custom components, headless mode): See references/​styling-customization.md
• Troubleshooting (common issues, CORS, env vars, Docker): See references/​troubleshooting.md
• AG-UI Protocol (events, architecture, CLI scaffolding): See references/​ag-ui-protocol.md

UI Components

All accept instructions, labels, suggestions, custom message/​input components, and observabilityHooks.

CopilotKit Provider Props

Agent Protocols

Supported Agent Frameworks

LangGraph, CrewAI, Google ADK, AWS Strands, Microsoft Agent Framework, Mastra, PydanticAI, AG2, LlamaIndex, Agno, VoltAgent, Blaxel.

LLM Adapters

OpenAIAdapter, AnthropicAdapter, GoogleGenerativeAIAdapter, GroqAdapter, LangChainAdapter, OpenAIAssistantAdapter.

Key Packages

Error Handling

Frontend onError callback

<CopilotKit
  runtimeUrl="/​api/​copilotkit"
  onError={(error) => {
    console.error("CopilotKit error:", error);
    toast.error("AI assistant encountered an error");
  }}
>

Tool render "failed" status

All render functions receive status === "failed" when a tool errors. Always handle this:

render: ({ status, args, result }) => {
  if (status === "failed") return <ErrorCard message="Tool execution failed" />;
  // ...
}

Python SDK exception types

Versioning

Current version: v1.51.3 (Python SDK v0.1.78). The v2 runtime interface is available at the /​v2 path. Next-generation packages use the @copilotkitnext/​* namespace (e.g., @copilotkitnext/​angular).

Common Anti-Patterns

Common Patterns Cheat Sheet