CopilotKit

Migrate to V2

Migration guide for upgrading to CopilotKit V2 frontend packages

Overview#

CopilotKit V2 consolidates the frontend into a single package. Both hooks and UI components are now exported from @copilotkit/react-core/v2. Your backend does not need any changes.

What's changing:

BeforeAfter
v1 hooks from @copilotkit/react-corev2 hooks from @copilotkit/react-core/v2
@copilotkit/react-ui@copilotkit/react-core/v2
@copilotkit/react-ui/styles.css@copilotkit/react-core/v2/styles.css

What's not changing:

  • Backend packages (@copilotkit/runtime, etc.) do not need changes.
  • Your CopilotRuntime configuration stays the same.
  • Agent definitions and backend setup stay the same.
  • Keep the <CopilotKit> provider name, but import it from @copilotkit/react-core/v2.

Migration Steps#

Update v1 hook imports#

Replace v1 hooks from @copilotkit/react-core with their v2 equivalents from @copilotkit/react-core/v2. Keep the <CopilotKit> provider name, but import it from @copilotkit/react-core/v2.

Before

import { CopilotKit } from "@copilotkit/react-core";
import { useCopilotReadable, useCopilotAction } from "@copilotkit/react-core";

After

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

Hook mapping from v1 to v2

Use this table to find the v2 replacement for each v1 hook:

v1 hookv2 hook
useCopilotActionuseFrontendTool
useCopilotReadableuseAgentContext
useCopilotAdditionalInstructionsuseAgentContext
useCoAgentuseAgent
useCopilotChatuseAgent (low-level headless chat: useCopilotChatHeadless_c)

Chat-UI customization props were also renamed in v2:

v1 (component prop)v2 (slot / prop)
AssistantMessageassistantMessage slot (under messageView)
markdownTagRenderersmarkdownRenderer slot (under assistantMessage)

See Slots for how the v2 slot system replaces the v1 component-override props.

Replace React UI imports#

UI components like CopilotChat, CopilotSidebar, and CopilotPopup are now exported from @copilotkit/react-core/v2.

Before

import { CopilotPopup } from "@copilotkit/react-ui";
import { CopilotSidebar } from "@copilotkit/react-ui";
import { CopilotChat } from "@copilotkit/react-ui";

After

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

Update your styles import#

Before

import "@copilotkit/react-ui/styles.css";

After

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

Upgrade AG-UI client if using it directly#

If you import from @ag-ui/client directly, upgrade to the latest version:

npm install @ag-ui/client@latest

Note: If you only use CopilotKit's React packages, @ag-ui/client types are already re-exported from @copilotkit/react-core/v2 and you don't need a separate install.

Full Example#

Before#

import { CopilotKit } from "@copilotkit/react-core";
import { CopilotPopup } from "@copilotkit/react-ui";
import "@copilotkit/react-ui/styles.css";

export function App() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit">
      <YourApp />
      <CopilotPopup />
    </CopilotKit>
  );
}

After#

import { CopilotKit, CopilotPopup } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export function App() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit">
      <YourApp />
      <CopilotPopup />
    </CopilotKit>
  );
}

On this page

OverviewMigration StepsUpdate v1 hook importsReplace React UI importsUpdate your styles importUpgrade AG-UI client if using it directlyFull ExampleBeforeAfter