Migrate from v1 to v2

Migration guide for replacing deprecated CopilotKit v1 JavaScript and TypeScript imports with v2 APIs

Overview

The CopilotKit v1 SDK is deprecated. Use v2 instead. V2 consolidates React hooks and UI components under @copilotkit/react-core/v2, and the current runtime API is available from @copilotkit/runtime/v2.

This migration is not a global string replacement. Some exports kept their names, some were renamed, and some have no 1:1 replacement because v2 uses a different model. Use the IDE deprecation warning on every v1 import or consult the complete v1 to v2 export map before changing a call site.

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
@copilotkit/runtime@copilotkit/runtime/v2
@copilotkit/vue@copilotkit/vue/v2

Minimum version and coexistence

The exhaustive IDE warnings are available starting in CopilotKit 1.68.2. V1 and v2 continue to coexist in the same packages for backward compatibility for at least two minor releases. Removing v1 would be a separate major-version change with its own notice; this migration does not remove or silently change v1 runtime behavior.

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, useAgentContext, useFrontendTool } 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 (custom chat UI: Headless UI)

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 Runtime imports

Import the v2 runtime from the same package's /v2 subpath. Review the CopilotRuntime v2 setup because v2 uses AG-UI runtime handlers rather than the v1 GraphQL adapter setup.

Before

import { CopilotRuntime } from "@copilotkit/runtime";

After

import { CopilotRuntime } from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({ agents: {} });

If you use Vue, update Vue imports

Vue v2 lives at the same package's /v2 subpath. The v1 CopilotKit component becomes CopilotKitProvider; most exports otherwise retain their public names.

Before

import { CopilotKit, useCopilotAction } from "@copilotkit/vue";

After

import { CopilotKitProvider, useFrontendTool } from "@copilotkit/vue/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, install the version that @copilotkit/runtime depends on:

npm install @ag-ui/client@1.0.2

A different version installs a second copy of the package, with its own HttpAgent class. Run npm ls @ag-ui/client to make sure that only one version is installed.

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.

Gotchas

  • Tool rendering is not frontend tool execution. Replace the v1 useRenderToolCall registration hook with v2 useRenderTool. V2's hook named useRenderToolCall is a different low-level consumer API.
  • Schemas changed. V2 tool and interaction hooks use Standard Schema objects such as z.object(...), not the v1 Parameter[] shape.
  • Names can move packages. React UI components move from @copilotkit/react-ui to @copilotkit/react-core/v2.
  • No-replacement markers are intentional. If an IDE warning or the export map says there is no 1:1 replacement, migrate the surrounding pattern using the linked v2 reference instead of selecting a similarly named symbol.
  • Type exports matter too. Type-only imports carry the same IDE warning and should be migrated with their consuming value API.

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>
  );
}

Run your type check. It must pass. When no import in your IDE shows the v1 deprecation warning, the migration is complete.

How is this guide?