# Migrate from v1 to v2

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

## Overview [#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](/reference/v1/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 [#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 [#migration-steps]

<Steps>
<Step>
### Update v1 hook imports [#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 [#before]

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

#### After [#after]

```tsx
import { CopilotKit, useAgentContext, useFrontendTool } from "@copilotkit/react-core/v2";
```

#### Hook mapping from v1 to 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](/llamaindex/custom-look-and-feel/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](/llamaindex/custom-look-and-feel/slots) for how the v2 slot system replaces the
v1 component-override props.

</Step>
<Step>
### Replace React UI imports [#replace-react-ui-imports]

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

#### Before [#before-1]

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

#### After [#after-1]

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

</Step>
<Step>
### Update Runtime imports [#update-runtime-imports]

Import the v2 runtime from the same package's `/v2` subpath. Review the
[`CopilotRuntime` v2 setup](/llamaindex/runtime-server-adapter) because v2 uses AG-UI
runtime handlers rather than the v1 GraphQL adapter setup.

#### Before [#before-2]

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

#### After [#after-2]

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

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

</Step>
<Step>
### If you use Vue, update Vue imports [#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 [#before-3]

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

#### After [#after-3]

```ts
import { CopilotKitProvider, useFrontendTool } from "@copilotkit/vue/v2";
```

</Step>
<Step>
### Update your styles import [#update-your-styles-import]

#### Before [#before-4]

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

#### After [#after-4]

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

</Step>
<Step>
### Upgrade AG-UI client if using it directly [#upgrade-ag-ui-client-if-using-it-directly]

If you import from `@ag-ui/client` directly, install the version that `@copilotkit/runtime` depends on:

```bash
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.

</Step>
</Steps>

## Gotchas [#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 [#full-example]

### Before [#before-5]

```tsx
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 [#after-5]

```tsx
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.
