CopilotKit — In-App AI Copilots for React

Overview

CopilotKit connects a React frontend to an AI agent. The frontend gets prebuilt chat components (CopilotSidebar, CopilotPopup, CopilotChat) and hooks that share app state with the agent and let it call functions in the browser. The backend is the Copilot Runtime, an endpoint in your own server that hosts either the built-in agent (it calls an LLM directly) or agents from LangGraph, Mastra, CrewAI, Google ADK and other frameworks over the AG-UI protocol.

The v1 SDK is deprecated. Everything current is imported from the /v2 subpaths — @copilotkit/react-core/v2 and @copilotkit/runtime/v2. Code that imports useCopilotAction, useCopilotReadable, OpenAIAdapter or anything from @copilotkit/react-ui is v1; see the migration table below.

Instructions

Install

npm install @copilotkit/react-core @copilotkit/runtime zod

The chat components and the stylesheet ship in @copilotkit/react-core/v2, so @copilotkit/react-ui is not needed. Put the provider key in .env (OPENAI_API_KEY, ANTHROPIC_API_KEY or GOOGLE_API_KEY). For a new project, npx copilotkit@latest create scaffolds a starter in its own directory; it does not modify an existing app.

Runtime endpoint

// app/api/copilotkit/[[...slug]]/route.ts
import { BuiltInAgent, CopilotRuntime, createCopilotRuntimeHandler, defineTool } from "@copilotkit/runtime/v2";
import { z } from "zod";

// Server tool: runs on the backend, can use secrets and the database
const findOverdueTasks = defineTool({
  name: "findOverdueTasks",
  description: "List tasks in a project that are past their due date",
  parameters: z.object({ projectId: z.string().describe("Project identifier") }),
  execute: async ({ projectId }) => {
    return { projectId, overdue: [{ title: "Renew TLS certificate", dueDate: "2026-09-28" }] };
  },
});

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini", // or "anthropic:claude-sonnet-4-6", "google:gemini-2.5-pro"
  prompt: "You help the team manage tasks in the project dashboard.",
  tools: [findOverdueTasks],
  maxSteps: 5, // allow tool call → answer chains; the default is a single step
});

const runtime = new CopilotRuntime({ agents: { default: agent } });
const handler = createCopilotRuntimeHandler({ runtime, basePath: "/api/copilotkit" });

export const GET = handler;
export const POST = handler;
export const PATCH = handler;
export const DELETE = handler;

The v2 handler serves several routes under the base path, which is why the folder is the catch-all [[...slug]]. Express uses createCopilotExpressHandler from @copilotkit/runtime/v2/express.

Provider and chat UI

// app/providers.tsx
"use client";

import { CopilotKitProvider, CopilotSidebar } from "@copilotkit/react-core/v2";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      {children}
      <CopilotSidebar defaultOpen={false} labels={{ modalHeaderTitle: "Project Assistant" }} />
    </CopilotKitProvider>
  );
}

// app/layout.tsx — a server component, so it renders the client Providers file
import { Providers } from "./providers";
import "@copilotkit/react-core/v2/styles.css";

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

A relative runtimeUrl works because Next.js serves the app and the runtime from one origin. A client-only app (Vite) needs a standalone runtime server and an absolute URL.

Share app state and expose tools

// app/components/ProjectDashboard.tsx
"use client";

import { useState } from "react";
import { useAgentContext, useFrontendTool } from "@copilotkit/react-core/v2";
import { z } from "zod";

type Task = { id: string; title: string; status: "todo" | "doing" | "done"; assignee?: string };

export function ProjectDashboard({ projectName, initialTasks }: { projectName: string; initialTasks: Task[] }) {
  const [tasks, setTasks] = useState(initialTasks);

  // Shared with the agent; updates whenever `tasks` changes
  useAgentContext({
    description: "The project the user is viewing and its tasks",
    value: { projectName, tasks },
  });

  // A tool the agent can call; the handler runs in the browser
  useFrontendTool(
    {
      name: "createTask",
      description: "Create a new task in the current project",
      parameters: z.object({
        title: z.string().describe("Task title"),
        assignee: z.string().optional().describe("Who the task is assigned to"),
      }),
      handler: async ({ title, assignee }) => {
        setTasks((prev) => [...prev, { id: crypto.randomUUID(), title, status: "todo", assignee }]);
        return `Created task: ${title}`;
      },
    },
    [],
  );

  return (
    <ul>
      {tasks.map((t) => (
        <li key={t.id}>{t.title} — {t.status}</li>
      ))}
    </ul>
  );
}

Connect an existing agent

Register an agent you already run instead of BuiltInAgent. The URL is the agent's own server, not /api/copilotkit. To import @ag-ui/client directly, install the exact version @copilotkit/runtime depends on (npm install @ag-ui/client@1.0.1 for 1.76.0); npm ls @ag-ui/client must show a single copy:

import { HttpAgent } from "@ag-ui/client";
import { CopilotRuntime } from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: {
    support_agent: new HttpAgent({ url: process.env.SUPPORT_AGENT_URL ?? "http://localhost:8000/" }),
  },
});

The frontend addresses an agent by its key in the agents map: <CopilotSidebar agentId="support_agent" /> or useAgent({ agentId: "support_agent" }). The key default is used when no agentId is given. LangGraph deployments use LangGraphAgent from @copilotkit/runtime/langgraph.

Migrating from v1

v1	v2
useCopilotAction (parameter arrays)	useFrontendTool (Zod schema)
useCopilotReadable, useCopilotAdditionalInstructions	useAgentContext
useCoAgent, useCopilotChat	useAgent
renderAndWaitForResponse	useHumanInTheLoop
@copilotkit/react-ui components and styles.css	same names from @copilotkit/react-core/v2
new OpenAIAdapter() + copilotRuntimeNextJSAppRouterEndpoint	BuiltInAgent + createCopilotRuntimeHandler
CopilotTextarea (@copilotkit/react-textarea)	no replacement; its autosuggestions stopped reaching a backend in 1.50.0

Examples

Example 1: Assistant that sees the page and creates tasks

User request: "Add an AI sidebar to our Next.js project dashboard. It should know which tasks are on screen and be able to add new ones."

Create the route, providers.tsx, layout.tsx and ProjectDashboard.tsx from the Instructions, then check the wiring before opening the browser:

npm run build && npm run start
curl -s http://localhost:3000/api/copilotkit/info

{"version":"1.76.0","agents":{"default":{"name":"default","description":"","capabilities":{"tools":{"supported":true,"clientProvided":true}}}},"mode":"sse"}

(Output shortened.) The agent is listed under the key default, so the sidebar finds it without an agentId. In the chat, "Add a task for Priya to update the pricing page" makes the agent call createTask; the handler appends the row to the list and the tool result goes back to the model.

Example 2: Ask before a bulk action

User request: "The assistant must not archive anything until the user confirms."

// app/components/ArchiveConfirmation.tsx — render <ArchiveConfirmation /> anywhere inside the provider
"use client";

import { ToolCallStatus, useHumanInTheLoop } from "@copilotkit/react-core/v2";
import { z } from "zod";

export function ArchiveConfirmation() {
  useHumanInTheLoop(
    {
      name: "confirmArchive",
      description: "Ask the user to confirm before archiving completed tasks",
      parameters: z.object({ count: z.number().describe("How many tasks would be archived") }),
      render: ({ args, status, respond }) =>
        status === ToolCallStatus.Executing && respond ? (
          <div>
            <p>Archive {args.count} completed tasks?</p>
            <button onClick={() => respond({ confirmed: true })}>Archive</button>
            <button onClick={() => respond({ confirmed: false })}>Cancel</button>
          </div>
        ) : null,
    },
    [],
  );
  return null;
}

Result: when the model calls confirmArchive, the run pauses and the two buttons appear in the chat. The clicked value ({"confirmed":true}) is returned to the agent as the tool result and the run continues.

Guidelines

1. Schemas are validators, not arrays — parameters takes a Standard Schema validator such as z.object(...). The v1 [{ name, type }] array shape no longer applies. A plain JSON Schema object is not accepted either: defineTool does not check it, and the run fails later when the runtime converts the tool.
2. Validate inside handlers — frontend tool arguments are typed from the schema but not validated at run time, and the handler runs in the user's browser. Re-check anything that matters on the server; never rely on a frontend tool for authorization.
3. Keep keys on the server — provider keys belong to the runtime route's environment. Do not expose them through NEXT_PUBLIC_ variables or pass them to the provider component.
4. Set maxSteps — the built-in agent does one step by default, so a tool call would not be followed by an answer.
5. Agent names are map keys — a name the runtime did not register raises CopilotKitAgentDiscoveryError. GET /api/copilotkit/info lists the real keys.
6. One run per agent instance — a BuiltInAgent created at module scope refuses a second concurrent run ("Agent is already running"). On a multi-user server, construct the agent per request.
7. Tool name collisions — a server tool wins over a frontend tool with the same name, so the frontend handler never fires. Use distinct names.
8. Context is sent as JSON text — useAgentContext stringifies non-string values; an agent you host yourself has to parse them. The built-in agent needs no extra work.
9. Telemetry — the runtime reports anonymous usage; set COPILOTKIT_TELEMETRY_DISABLED=true to turn it off.
10. When not to use it — for one-off completions with no chat UI, shared state or tools, calling the provider SDK directly is simpler. Angular and Vue have their own CopilotKit packages; this skill covers React.