CopilotKit logo

Skill

copilotkit-develop

build AI features with CopilotKit

Covers CopilotKit AI Context Agents Frontend

Description

Use when building AI-powered features with CopilotKit v2 -- adding chat interfaces, registering frontend tools, sharing application context with agents, handling agent interrupts, and working with the CopilotKit runtime.

SKILL.md

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 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, v2 symbols under @copilotkit/runtime/v2) -- 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-core, v2 symbols under @copilotkit/react-core/v2) -- 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 createCopilotHonoHandler (Hono) or createCopilotExpressHandler (Express).

import {
  CopilotRuntime,
  createCopilotHonoHandler,
} from "@copilotkit/runtime/v2";
import { LangGraphAgent } from "@copilotkit/runtime/langgraph";
import { handle } from "hono/vercel";

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

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

// Multi-route (the default): export every method the runtime serves.
// useThreads needs them all — rename via PATCH, delete via DELETE; archive
// uses the already-exported POST.
export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);

2. Wrap Your App with the Provider (Client)

Use the CopilotKit provider (from @copilotkit/react-core/v2). It is the compatibility bridge across v1 and v2 and a strict superset of the legacy CopilotKitProvider -- all CopilotKitProvider props work on it.

import { CopilotKit } from "@copilotkit/react-core/v2";

function App() {
  return (
    // useSingleEndpoint={false} matches the multi-route backend above. The
    // v1-compat CopilotKit bridge defaults it to true (single transport),
    // which would 404 against a multi-route handler.
    <CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint={false}>
      <YourApp />
    </CopilotKit>
  );
}

3. Add a Chat UI

Use <CopilotChat>, <CopilotPopup>, or <CopilotSidebar>:

import { CopilotChat } from "@copilotkit/react-core/v2";

function ChatPage() {
  return <CopilotChat agentId="myAgent" />;
}

4. Register Frontend Tools

Let the agent call functions in the browser:

import { useFrontendTool } from "@copilotkit/react-core/v2";
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-core/v2";

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-core/v2";

useInterrupt({
  render: ({ event, resolve }) => (
    <div>
      <p>{event.value.question}</p>
      <button onClick={() => resolve({ approved: true })}>Approve</button>
    </div>
  ),
});

7. Render Tool Calls in Chat

Show custom UI when tools execute:

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

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

Quick Reference: Hooks

HookPurpose
useFrontendToolRegister a tool the agent can call in the browser
useComponentRegister a React component as a chat-rendered tool (convenience wrapper around useFrontendTool)
useAgentContextShare JSON-serializable application state with the agent
useAgentGet the AbstractAgent instance for an agent ID; subscribe to message/state/run-status changes
useInterruptHandle on_interrupt events from agents with render + optional handler/enabled predicate
useHumanInTheLoopRegister a tool that pauses execution until the user responds via a rendered UI
useRenderToolRegister a renderer for tool calls (by name or wildcard "*")
useDefaultRenderToolRegister a wildcard "*" renderer using the built-in expandable card UI
useRenderToolCallInternal hook returning a function to resolve the correct renderer for a given tool call
useRenderActivityMessageInternal hook for rendering activity messages by type
useRenderCustomMessagesInternal hook for rendering custom message decorators
useSuggestionsRead the current suggestion list and control reload/clear
useConfigureSuggestionsRegister static or dynamic (LLM-generated) suggestion configs
useThreadsList, rename, archive, and delete Intelligence platform threads

Quick Reference: Components

ComponentPurpose
CopilotKitRoot provider (from @copilotkit/react-core/v2) -- configures runtime URL, headers, agents, error handler
CopilotChatFull chat interface connected to an agent (inline layout)
CopilotPopupChat in a floating popup with toggle button
CopilotSidebarChat in a collapsible sidebar with toggle button
CopilotChatViewHeadless chat view with slots for message view, input, scroll, suggestions
CopilotChatInputChat input textarea with send/stop/transcribe controls
CopilotChatMessageViewRenders the message list
CopilotChatSuggestionViewRenders suggestion pills

Quick Reference: Runtime

All v2 runtime symbols import from @copilotkit/runtime/v2 (createCopilotExpressHandler from @copilotkit/runtime/v2/express).

ExportPurpose
CopilotRuntimeAuto-detecting runtime (delegates to SSE or Intelligence)
CopilotSseRuntimeExplicit SSE-mode runtime
CopilotIntelligenceRuntimeIntelligence-mode runtime with durable threads
createCopilotHonoHandlerCreate a Hono app with all CopilotKit routes
createCopilotExpressHandlerCreate an Express router with all CopilotKit routes
CopilotKitIntelligenceIntelligence platform client configuration

© 2026 YourAI.tools. Every skill from an identity-verified publisher.

Independent catalog. Not affiliated with, endorsed by, or sponsored by Anthropic or any listed publisher. All trademarks belong to their respective owners.