Back to Details

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 APIv2 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 APIv2 替代方案
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):
ts
import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/runtime";
const runtime = new CopilotRuntime({ actions: [...] });
// used with copilotKitEndpoint() for Next.js, Express, etc.
v2 pattern (agents + Hono endpoint):
ts
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 写法（服务适配器 + 端点）：
ts
import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/runtime";
const runtime = new CopilotRuntime({ actions: [...] });
// used with copilotKitEndpoint() for Next.js, Express, etc.
v2 写法（Agent + Hono端点）：
ts
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

快速参考

Conceptv1v2
Package scope
@copilotkit/*
@copilotkit/*
(same scope, updated APIs)
ProtocolGraphQLAG-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
)
概念v1v2
包作用域
@copilotkit/*
@copilotkit/*
（相同作用域，更新后的API）
协议GraphQLAG-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
）