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:
| Before | After |
|---|---|
v1 hooks from @copilotkit/react-core | v2 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 hook | v2 hook |
|---|---|
useCopilotAction | useFrontendTool |
useCopilotReadable | useAgentContext |
useCopilotAdditionalInstructions | useAgentContext |
useCoAgent | useAgent |
useCopilotChat | useAgent (custom chat UI: Headless UI) |
Chat-UI customization props were also renamed in v2:
| v1 (component prop) | v2 (slot / prop) |
|---|---|
AssistantMessage | assistantMessage slot (under messageView) |
markdownTagRenderers | markdownRenderer 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.2A 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
useRenderToolCallregistration hook with v2useRenderTool. V2's hook nameduseRenderToolCallis a different low-level consumer API. - Schemas changed. V2 tool and interaction hooks use Standard Schema
objects such as
z.object(...), not the v1Parameter[]shape. - Names can move packages. React UI components move from
@copilotkit/react-uito@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?