copilotkit-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CopilotKit v1 to v2 Migration Skill

CopilotKit v1 到 v2 迁移技能

Live Documentation (MCP)

在线文档（MCP）

This plugin includes an MCP server (

copilotkit-docs

) that provides

search-docs

and

search-code

tools for querying live CopilotKit documentation and source code. Useful for looking up current v2 API signatures during migration.

Claude Code: Auto-configured by the plugin's
```
.mcp.json
```
-- no setup needed.
Codex: Requires manual configuration. See the copilotkit-debug skill for setup instructions.

此插件包含一个MCP服务器（

copilotkit-docs

），提供

search-docs

和

search-code

工具，可用于查询实时CopilotKit文档和源代码。在迁移过程中查找当前v2 API签名时非常实用。

Claude Code： 由插件的
```
.mcp.json
```
自动配置，无需额外设置。
Codex： 需要手动配置。请参考copilotkit-debug skill查看配置说明。

Overview

概述

CopilotKit v2 is a ground-up rewrite built on the AG-UI protocol (

@ag-ui/client

@ag-ui/core

). Users continue to install and import

@copilotkit/*

packages -- the v2 changes are exposed through the same package names with updated APIs (new hook names, component names, runtime configuration). The

@copilotkit/*

namespace is an internal implementation detail that users never interact with.

CopilotKit v2是基于AG-UI协议（

@ag-ui/client

@ag-ui/core

）完全重写的版本。用户仍可安装和导入

@copilotkit/*

系列包——v2的变更通过相同的包名暴露，仅API有所更新（新的钩子名称、组件名称、运行时配置）。

@copilotkit/*

命名空间属于内部实现细节，用户无需直接交互。

Migration Workflow

迁移工作流

1. Audit Current Usage

1. 审计当前使用情况

Scan the codebase for all v1 imports and API usage:

@copilotkit/react-core    -> hooks, CopilotKit provider, types
@copilotkit/react-ui      -> CopilotChat, CopilotPopup, CopilotSidebar
@copilotkit/react-textarea -> CopilotTextarea (removed in v2)
@copilotkit/runtime       -> CopilotRuntime, service adapters, framework integrations
@copilotkit/runtime-client-gql -> GraphQL client, message types
@copilotkit/shared         -> utility types, constants
@copilotkit/sdk-js         -> LangGraph/LangChain SDK

扫描代码库中所有v1版本的导入和API使用：

@copilotkit/react-core    -> hooks, CopilotKit provider, types
@copilotkit/react-ui      -> CopilotChat, CopilotPopup, CopilotSidebar
@copilotkit/react-textarea -> CopilotTextarea (removed in v2)
@copilotkit/runtime       -> CopilotRuntime, service adapters, framework integrations
@copilotkit/runtime-client-gql -> GraphQL client, message types
@copilotkit/shared         -> utility types, constants
@copilotkit/sdk-js         -> LangGraph/LangChain SDK

2. Identify Deprecated APIs

2. 识别已弃用的API

Key hooks and components to find and replace:

v1 API	v2 Replacement
`useCopilotAction`	`useFrontendTool`
`useCopilotReadable`	`useAgentContext`
`useCopilotChat`	`useAgent` + `useSuggestions`
`useCoAgent`	`useAgent`
`useCoAgentStateRender`	`useRenderToolCall` / `useRenderActivityMessage`
`useLangGraphInterrupt`	`useInterrupt`
`useCopilotChatSuggestions`	`useConfigureSuggestions` + `useSuggestions`
`useCopilotAdditionalInstructions`	`useAgentContext`
`useMakeCopilotDocumentReadable`	`useAgentContext`
`CopilotKit` (provider)	`CopilotKitProvider`
`CopilotTextarea`	Removed -- use standard textarea + `useFrontendTool`

需要查找并替换的核心钩子和组件：

v1 API	v2 替代方案
`useCopilotAction`	`useFrontendTool`
`useCopilotReadable`	`useAgentContext`
`useCopilotChat`	`useAgent` + `useSuggestions`
`useCoAgent`	`useAgent`
`useCoAgentStateRender`	`useRenderToolCall` / `useRenderActivityMessage`
`useLangGraphInterrupt`	`useInterrupt`
`useCopilotChatSuggestions`	`useConfigureSuggestions` + `useSuggestions`
`useCopilotAdditionalInstructions`	`useAgentContext`
`useMakeCopilotDocumentReadable`	`useAgentContext`
`CopilotKit` (provider)	`CopilotKitProvider`
`CopilotTextarea`	已移除 -- 使用标准textarea + `useFrontendTool`

3. Map to v2 Equivalents

3. 映射到v2等效API

Refer to

references/v1-to-v2-migration.md

for detailed before/after code examples.

请参考

references/v1-to-v2-migration.md

查看详细的代码前后对比示例。

4. Update Package Dependencies

4. 更新包依赖

The

@copilotkit/*

package names stay the same. Update to the latest v2 versions:

@copilotkit/react-core        -> @copilotkit/react (consolidated into one package)
@copilotkit/react-ui           -> @copilotkit/react (consolidated into one package)
@copilotkit/react-textarea     -> removed (no v2 equivalent)
@copilotkit/runtime            -> @copilotkit/runtime (same package, new agent-based API)
@copilotkit/runtime-client-gql -> removed (replaced by AG-UI protocol, re-exported from @copilotkit/react)
@copilotkit/shared             -> @copilotkit/shared (same package)
@copilotkit/sdk-js             -> @copilotkit/agent (new package for agent definitions)

@copilotkit/*

包名保持不变，请升级到最新的v2版本：

@copilotkit/react-core        -> @copilotkit/react (consolidated into one package)
@copilotkit/react-ui           -> @copilotkit/react (consolidated into one package)
@copilotkit/react-textarea     -> removed (no v2 equivalent)
@copilotkit/runtime            -> @copilotkit/runtime (same package, new agent-based API)
@copilotkit/runtime-client-gql -> removed (replaced by AG-UI protocol, re-exported from @copilotkit/react)
@copilotkit/shared             -> @copilotkit/shared (same package)
@copilotkit/sdk-js             -> @copilotkit/agent (new package for agent definitions)

5. Update Runtime Configuration

5. 更新运行时配置

The v1

CopilotRuntime

accepted service adapters (OpenAI, Anthropic, LangChain, etc.) and endpoint definitions. The v2

CopilotRuntime

accepts AG-UI

AbstractAgent

instances directly.

v1 pattern (service adapter + endpoints):

import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/runtime";
const runtime = new CopilotRuntime({ actions: [...] });
// used with copilotKitEndpoint() for Next.js, Express, etc.

v2 pattern (agents + Hono endpoint):

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
const runtime = new CopilotRuntime({
  agents: { myAgent: new BuiltInAgent({ model: "openai:gpt-4o" }) },
});
const app = createCopilotEndpoint({ runtime, basePath: "/api/copilotkit" });

v1版本的

CopilotRuntime

接受服务适配器（OpenAI、Anthropic、LangChain等）和端点定义。v2版本的

CopilotRuntime

直接接受AG-UI

AbstractAgent

实例。

v1 写法（服务适配器 + 端点）：

import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/runtime";
const runtime = new CopilotRuntime({ actions: [...] });
// used with copilotKitEndpoint() for Next.js, Express, etc.

v2 写法（Agent + Hono端点）：

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
const runtime = new CopilotRuntime({
  agents: { myAgent: new BuiltInAgent({ model: "openai:gpt-4o" }) },
});
const app = createCopilotEndpoint({ runtime, basePath: "/api/copilotkit" });

6. Update Provider

6. 更新Provider

v1:

tsx

import { CopilotKit } from "@copilotkit/react-core";
<CopilotKit runtimeUrl="/api/copilotkit">
  {children}
</CopilotKit>

v2:

tsx

import { CopilotKitProvider } from "@copilotkit/react";
<CopilotKitProvider runtimeUrl="/api/copilotkit">
  {children}
</CopilotKitProvider>

v1：

tsx

import { CopilotKit } from "@copilotkit/react-core";
<CopilotKit runtimeUrl="/api/copilotkit">
  {children}
</CopilotKit>

v2：

tsx

import { CopilotKitProvider } from "@copilotkit/react";
<CopilotKitProvider runtimeUrl="/api/copilotkit">
  {children}
</CopilotKitProvider>

7. Verify

7. 验证

Run the application and check for runtime errors
Verify all agent interactions work (chat, tool calls, interrupts)
Check that tool renderers display correctly
Confirm suggestions load and display

运行应用并检查运行时错误
验证所有Agent交互正常运行（聊天、工具调用、中断）
检查工具渲染器显示是否正确
确认建议内容可正常加载和显示

Quick Reference

快速参考

Concept	v1	v2
Package scope	`@copilotkit/*`	`@copilotkit/*` (same scope, updated APIs)
Protocol	GraphQL	AG-UI (SSE)
Provider component	`CopilotKit`	`CopilotKitProvider`
Define frontend tool	`useCopilotAction`	`useFrontendTool`
Share app state	`useCopilotReadable`	`useAgentContext`
Agent interaction	`useCoAgent`	`useAgent`
Handle interrupts	`useLangGraphInterrupt`	`useInterrupt`
Render tool calls	`useCopilotAction({ render })`	`useRenderToolCall`
Chat suggestions	`useCopilotChatSuggestions`	`useConfigureSuggestions`
Runtime class	`CopilotRuntime` (adapters)	`CopilotRuntime` (agents)
Endpoint setup	`copilotKitEndpoint()`	`createCopilotEndpoint()`
Agent definition	`LangGraphAgent` endpoint	`AbstractAgent` / `BuiltInAgent`
Chat components	`CopilotChat` , `CopilotPopup` , `CopilotSidebar`	`CopilotChat` , `CopilotPopup` , `CopilotSidebar` (from `@copilotkit/react` )

概念	v1	v2
包作用域	`@copilotkit/*`	`@copilotkit/*` （相同作用域，更新后的API）
协议	GraphQL	AG-UI (SSE)
Provider组件	`CopilotKit`	`CopilotKitProvider`
定义前端工具	`useCopilotAction`	`useFrontendTool`
共享应用状态	`useCopilotReadable`	`useAgentContext`
Agent交互	`useCoAgent`	`useAgent`
处理中断	`useLangGraphInterrupt`	`useInterrupt`
渲染工具调用	`useCopilotAction({ render })`	`useRenderToolCall`
聊天建议	`useCopilotChatSuggestions`	`useConfigureSuggestions`
运行时类	`CopilotRuntime` （适配器模式）	`CopilotRuntime` （Agent模式）
端点配置	`copilotKitEndpoint()`	`createCopilotEndpoint()`
Agent定义	`LangGraphAgent` 端点	`AbstractAgent` / `BuiltInAgent`
聊天组件	`CopilotChat` , `CopilotPopup` , `CopilotSidebar`	`CopilotChat` , `CopilotPopup` , `CopilotSidebar` （来自 `@copilotkit/react` ）