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
```bash
npx copilotkit@latest create -f next
```

### Existing project
```bash
npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime
```

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

### Backend API route (`app/api/copilotkit/route.ts`)
```typescript
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`)
```typescript
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`)
```typescript
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
```typescript
useCopilotReadable({
  description: "Current user profile and preferences",
  value: { name: user.name, role: user.role, preferences },
});
```

### `useCopilotAction` -- Define executable actions
```typescript
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
```typescript
const { appendMessage, stopGeneration, reset, reloadMessages } = useCopilotChat();
```

### `useCopilotAdditionalInstructions` -- Dynamic context-aware prompts
```typescript
useCopilotAdditionalInstructions({
  instructions: "User is on the settings page. Help them configure preferences.",
});
```

### `useCopilotChatSuggestions` -- Auto-generate suggestions from app state
```typescript
useCopilotChatSuggestions({
  instructions: "Suggest actions based on the current app state.",
});
```

### `useAgent` -- v2 agent state sync (superset of useCoAgent)
```typescript
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
```typescript
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](references/generative-ui.md)
- **Shared State & CoAgents** (useCoAgent, useAgent, bidirectional sync, LangGraph): See [references/coagents-shared-state.md](references/coagents-shared-state.md)
- **Human-in-the-Loop** (buildtime/runtime HITL, approval flows, agent steering): See [references/human-in-the-loop.md](references/human-in-the-loop.md)
- **Runtime & Adapters** (all LLM adapters, framework endpoints, backend actions): See [references/runtime-adapters.md](references/runtime-adapters.md)
- **Python SDK** (LangGraphAgent, FastAPI, actions, state, events): See [references/python-sdk.md](references/python-sdk.md)
- **Styling & Customization** (CSS, custom components, headless mode): See [references/styling-customization.md](references/styling-customization.md)
- **Troubleshooting** (common issues, CORS, env vars, Docker): See [references/troubleshooting.md](references/troubleshooting.md)
- **AG-UI Protocol** (events, architecture, CLI scaffolding): See [references/ag-ui-protocol.md](references/ag-ui-protocol.md)

## UI Components

| Component | Import | Use case |
|-----------|--------|----------|
| `CopilotChat` | `@copilotkit/react-ui` | Embedded inline chat panel |
| `CopilotSidebar` | `@copilotkit/react-ui` | Collapsible sidebar chat |
| `CopilotPopup` | `@copilotkit/react-ui` | Floating popup chat |
| `CopilotTextarea` | `@copilotkit/react-ui` | AI-powered textarea drop-in |

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

## CopilotKit Provider Props

| Prop | Type | Purpose |
|------|------|---------|
| `runtimeUrl` | `string` | Self-hosted runtime endpoint |
| `publicApiKey` | `string` | Copilot Cloud API key |
| `headers` | `object` | Custom auth headers |
| `credentials` | `string` | Cookie handling (`"include"` for cross-origin) |
| `agent` | `string` | Default agent name |
| `properties` | `object` | Thread metadata, authorization |
| `onError` | `function` | Error handler callback |
| `showDevConsole` | `boolean` | Dev error banners |
| `enableInspector` | `boolean` | Debugging inspector tool |
| `renderActivityMessages` | `array` | Custom renderers (A2UI, etc.) |

## Agent Protocols

| Protocol | Purpose | Package |
|----------|---------|---------|
| **AG-UI** | Agent <-> User interaction, event streaming | `@ag-ui/core`, `@ag-ui/client` |
| **MCP** | Agent <-> External tools | MCP server integration |
| **A2A** | Agent <-> Agent communication | A2A protocol support |

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

| Package | Purpose |
|---------|---------|
| `@copilotkit/react-core` | Provider + all hooks |
| `@copilotkit/react-ui` | Chat UI components + styles |
| `@copilotkit/runtime` | Backend runtime + LLM adapters + framework endpoints |
| `copilotkit` (Python) | Python SDK for LangGraph/CrewAI agents |
| `@copilotkitnext/angular` | Angular SDK (Angular 18+19) |
| `@ag-ui/core` | AG-UI protocol types/events |
| `@ag-ui/client` | AG-UI client implementation |

## Error Handling

### Frontend `onError` callback

```typescript
<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:

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

### Python SDK exception types

| Exception | Meaning |
|-----------|---------|
| `ActionNotFoundException` | Requested action not registered |
| `AgentNotFoundException` | Requested agent not found in endpoint |

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

| Don't | Do Instead |
|-------|-----------|
| Put API keys in client-side code | Use server-side env vars + runtime endpoint |
| Create a new CopilotRuntime per request | Instantiate once, reuse across requests |
| Skip `status` checks in render functions | Always handle "inProgress", "complete", "failed" |
| Use `useCoAgent` for new projects | Prefer `useAgent` (v2 superset with time travel) |
| Hardcode instructions in every component | Use `useCopilotAdditionalInstructions` for page-specific context |
| Forget to import styles | Add `import "@copilotkit/react-ui/styles.css"` in layout |
| Mix `runtimeUrl` and `publicApiKey` without reason | Pick one deployment mode unless you need hybrid |
| Put heavy computation in action handlers | Return data from handlers, compute in render |

## Common Patterns Cheat Sheet

| Want to... | Use |
|-----------|-----|
| Show a chat bubble | `<CopilotPopup>` |
| Give LLM app context | `useCopilotReadable()` |
| Let LLM call functions | `useCopilotAction()` |
| Render UI from tool calls | `useFrontendTool()` or `useRenderToolCall()` |
| Default fallback tool renderer | `useDefaultTool()` |
| Sync state bidirectionally | `useCoAgent()` |
| Use v2 agent state sync | `useAgent()` (superset of useCoAgent) |
| Show agent progress | `useCoAgentStateRender()` |
| Ask user for approval | `useHumanInTheLoop()` |
| Handle LangGraph interrupts | `useLangGraphInterrupt()` |
| Control chat programmatically | `useCopilotChat()` |
| Run one-off tasks | `CopilotTask` |
| Connect Python agent | `CopilotKitRemoteEndpoint` + `LangGraphAgent` |
| Scaffold AG-UI app | `npx create-ag-ui-app` |
| Persist conversations | Thread model + StorageRunners |