API Reference

The v2 React API (@copilotkit/react-core/v2) is the next-generation interface for building copilot-powered applications. It provides a streamlined set of hooks and components built on top of the AG-UI agent protocol.

Provider Setup

Wrap your application with <CopilotKitProvider> to configure the v2 runtime connection:

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

function App() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit" agentId="default">
      <YourApp />
    </CopilotKitProvider>
  );
}

The <CopilotKit> export is the v1 compatibility wrapper, not an alias for <CopilotKitProvider>. Use agentId on the v2 provider; the compatibility wrapper uses agent and retains the v1 error-handler contract.

Import Surfaces

Use the main v2 entry when your app renders CopilotKit's web UI components or A2UI surfaces:

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

Use the headless entry when you build a fully custom chat surface and only need platform-agnostic hooks. This avoids the built-in chat rendering stack and its CSS:

import {
  useAgent,
  useCopilotKit,
  useFrontendTool,
  useRenderToolCall,
} from "@copilotkit/react-core/v2/headless";

The headless entry exports the provider context, chat configuration provider, useAgent, tool hooks, suggestions, threads, capabilities, and shared types. It does not export CopilotKitProvider, CopilotKit, CopilotChat, CopilotPopup, CopilotSidebar, useDefaultRenderTool, or A2UI render helpers.

Styling

When using v2 UI components, import the stylesheet once at your app boundary:

import "@copilotkit/react-core/v2/styles.css";

API Reference