Copilotkit Develop

CopilotKit v2 Development Skill

Live Documentation (MCP)

This plugin includes an MCP server (copilotkit-docs) that provides search-docs and search-code tools for querying live CopilotKit documentation and source code.

• Claude Code: Auto-configured by the plugin's .mcp.json -- no setup needed.
• Codex: Requires manual configuration. See the [copilotkit-debug skill](../copilotkit-debug/SKILL.md#mcp-setup) for setup instructions.

Architecture Overview

CopilotKit v2 is built on the AG-UI protocol (@ag-ui/client / @ag-ui/core). The stack has three layers:

1. Runtime (@copilotkit/runtime) -- Server-side. Hosts agents, handles SSE/Intelligence transport, middleware, transcription.
2. Core (@copilotkit/core) -- Shared state management, tool registry, suggestion engine. Not imported directly by apps.
3. React (@copilotkit/react) -- Provider, chat components, hooks. Re-exports everything from @ag-ui/client so apps need only one import.

Workflow

1. Set Up the Runtime (Server)

Create a CopilotRuntime (or the explicit CopilotSseRuntime / CopilotIntelligenceRuntime) and expose it via createCopilotEndpoint (Hono) or createCopilotEndpointExpress (Express).

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { LangGraphAgent } from "@ag-ui/langgraph";

const runtime = new CopilotRuntime({
  agents: {
    myAgent: new LangGraphAgent({ /* ... */ }),
  },
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

2. Wrap Your App with the Provider (Client)

import { CopilotKitProvider } from "@copilotkit/react";

function App() {
  return (
    
      
    
  );
}

3. Add a Chat UI

Use `, , or `:

import { CopilotChat } from "@copilotkit/react";

function ChatPage() {
  return ;
}

4. Register Frontend Tools

Let the agent call functions in the browser:

import { useFrontendTool } from "@copilotkit/react";
import { z } from "zod";

useFrontendTool({
  name: "highlightCell",
  description: "Highlight a spreadsheet cell",
  parameters: z.object({ row: z.number(), col: z.number() }),
  handler: async ({ row, col }) => {
    highlightCell(row, col);
    return "done";
  },
});

5. Share Application Context

Provide runtime data to the agent:

import { useAgentContext } from "@copilotkit/react";

useAgentContext({
  description: "The user's current shopping cart",
  value: cart, // any JSON-serializable value
});

6. Handle Agent Interrupts

When an agent pauses for human input:

import { useInterrupt } from "@copilotkit/react";

useInterrupt({
  render: ({ event, resolve }) => (
    
      {event.value.question}
       resolve({ approved: true })}>Approve
    
  ),
});

7. Render Tool Calls in Chat

Show custom UI when tools execute:

import { useRenderTool } from "@copilotkit/react";
import { z } from "zod";

useRenderTool({
  name: "searchDocs",
  parameters: z.object({ query: z.string() }),
  render: ({ status, parameters, result }) => {
    if (status === "executing") return Searching {parameters.query}...;
    if (status === "complete") return ;
    return Preparing...;
  },
}, []);

Quick Reference: Hooks

| Hook | Purpose | |------|---------| | useFrontendTool | Register a tool the agent can call in the browser | | useComponent | Register a React component as a chat-rendered tool (convenience wrapper around useFrontendTool) | | useAgentContext | Share JSON-serializable application state with the agent | | useAgent | Get the AbstractAgent instance for an agent ID; subscribe to message/state/run-status changes | | useInterrupt | Handle on_interrupt events from agents with render + optional handler/filter | | useHumanInTheLoop | Register a tool that pauses execution until the user responds via a rendered UI | | useRenderTool | Register a renderer for tool calls (by name or wildcard "*") | | useDefaultRenderTool | Register a wildcard "*" renderer using the built-in expandable card UI | | useRenderToolCall | Internal hook returning a function to resolve the correct renderer for a given tool call | | useRenderActivityMessage | Internal hook for rendering activity messages by type | | useRenderCustomMessages | Internal hook for rendering custom message decorators | | useSuggestions | Read the current suggestion list and control reload/clear | | useConfigureSuggestions | Register static or dynamic (LLM-generated) suggestion configs | | useThreads | List, rename, archive, and delete Intelligence platform threads |

Quick Reference: Components

| Component | Purpose | |-----------|---------| | CopilotKitProvider | Root provider -- configures runtime URL, headers, agents, error handler | | CopilotChat | Full chat interface connected to an agent (inline layout) | | CopilotPopup | Chat in a floating popup with toggle button | | CopilotSidebar | Chat in a collapsible sidebar with toggle button | | CopilotChatView | Headless chat view with slots for message view, input, scroll, suggestions | | CopilotChatInput | Chat input textarea with send/stop/transcribe controls | | CopilotChatMessageView | Renders the message list | | CopilotChatSuggestionView | Renders suggestion pills |

Quick Reference: Runtime

| Export | Purpose | |--------|---------| | CopilotRuntime | Auto-detecting runtime (delegates to SSE or Intelligence) | | CopilotSseRuntime | Explicit SSE-mode runtime | | CopilotIntelligenceRuntime | Intelligence-mode runtime with durable threads | | createCopilotEndpoint | Create a Hono app with all CopilotKit routes | | createCopilotEndpointExpress | Create an Express router with all CopilotKit routes | | CopilotKitIntelligence | Intelligence platform client configuration |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CopilotKit
• Source: CopilotKit/skills
• License: MIT

Install and usage instructions live in the source repository linked above.