copilotkit-upgrade

CopilotKit v1 到 v2 迁移技能

实时文档（MCP）

此插件包含一个 MCP 服务（copilotkit-docs），提供 search-docs 和 search-code 工具，用于查询实时 CopilotKit 文档和源代码。迁移时可用于查找当前的 v2 API 签名。

• **Claude Code：**由插件的 .mcp.json 自动配置，无需设置。
• **Codex：**需要手动配置。请参阅 copilotkit-debug 技能中的设置说明。

概述

CopilotKit v2 是基于 AG-UI 协议（@ag-ui/client / @ag-ui/core）从头重写的版本。用户仍然安装并导入 @copilotkit/* 包——v2 的变更通过相同的包名提供，API 则已更新（包括新的钩子名称、组件名称和运行时配置）。@copilotkit/* 命名空间是一个用户不会接触的内部实现细节。

迁移工作流

1. 审核当前用法

扫描代码库，查找所有 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. 找出已弃用的 API

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

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（提供程序）	CopilotKitProvider
CopilotTextarea	已移除——请使用标准 textarea + useFrontendTool

3. 映射到 v2 等效项

详细的迁移前后代码示例，请参阅 references/v1-to-v2-migration.md。

4. 更新包依赖项

@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. 更新运行时配置

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. 更新提供程序

v1：

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

v2：

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

7. 验证

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

快速参考

概念	v1	v2
包范围	@copilotkit/*	@copilotkit/*（范围相同，API 已更新）
协议	GraphQL	AG-UI（SSE）
提供程序组件	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）