CopilotKit

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

Why v1 is deprecated. Use v2 instead#

V2 is the current CopilotKit SDK surface. Keeping overlapping v1 and v2 names available without strong migration signals causes developers and coding agents to select stale examples and combine incompatible API shapes. Deprecating every v1 export makes the correct v2 import and documentation visible at the point of use while preserving existing applications during migration.

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, 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 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: {} });

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, 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.

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

On this page

OverviewWhy v1 is deprecated. Use v2 insteadMinimum version and coexistenceMigration StepsUpdate v1 hook importsReplace React UI importsUpdate Runtime importsUpdate Vue importsUpdate your styles importUpgrade AG-UI client if using it directlyGotchasFull ExampleBeforeAfter