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 的变更通过相同的包名（位于其 /v2 子路径下）暴露，并带有更新的 API（新的 hook 名称、组件名称、运行时配置）。底层的 @ag-ui/* 包是通过 @copilotkit/react-core/v2 重新导出的内部实现细节，因此用户无需直接安装它们。

迁移工作流

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

需要查找并替换的关键 hook 和组件：

v1 API	v2 替代方案
useCopilotAction	useFrontendTool
useCopilotReadable	useAgentContext
useCopilotChat	useAgent
useCoAgent	useAgent
useCoAgentStateRender	useRenderTool / useRenderActivityMessage
useCopilotContext	useCopilotKit（来自 @copilotkit/react-core/v2/context）
useLangGraphInterrupt	useInterrupt
useCopilotChatSuggestions	useConfigureSuggestions + useSuggestions
useCopilotAdditionalInstructions	useAgentContext
useMakeCopilotDocumentReadable	useAgentContext
CopilotKit（根导入）	CopilotKit（来自 @copilotkit/react-core/v2）
CopilotTextarea	已移除——使用标准 textarea + useFrontendTool

3. 映射到 v2 等价项

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

4. 更新包依赖

@copilotkit/* 包名保持不变。v2 不会引入新的包名——v2 API 从现有包的 /v2 子路径发布（@copilotkit/react-core/v2、@copilotkit/runtime/v2）。没有 @copilotkit/react 或 @copilotkit/agent 包。更新到最新的 v2 版本：

@copilotkit/react-core         -> @copilotkit/react-core (v2 symbols under the /v2 subpath)
@copilotkit/react-ui           -> chat components move to @copilotkit/react-core/v2; react-ui contributes only styles in v2
@copilotkit/react-textarea     -> removed (no v2 equivalent)
@copilotkit/runtime            -> @copilotkit/runtime (v2 symbols under the /v2 subpath)
@copilotkit/runtime-client-gql -> removed (replaced by AG-UI protocol; @ag-ui/client types are re-exported from @copilotkit/react-core/v2)
@copilotkit/shared             -> @copilotkit/shared (same package)
@copilotkit/sdk-js             -> removed (BuiltInAgent now ships from @copilotkit/runtime/v2)

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 framework handlers like copilotRuntimeNextJSAppRouterEndpoint() (Next.js), etc.

v2 模式（agents + Hono 端点）：

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

使用 createCopilotHonoHandler（来自 @copilotkit/runtime/v2）作为规范的 Hono 端点工厂。createCopilotEndpoint 是它的已弃用别名——在新代码中避免使用它。对于 Express，请使用 @copilotkit/runtime/v2/express 中的 createCopilotExpressHandler（createCopilotEndpointExpress 是其已弃用的别名）。

6. 更新 Provider

Provider 组件保持名称 CopilotKit -- 只有导入路径发生变化。包根路径（@copilotkit/react-core）是旧版 v1 provider；/v2 子路径是迁移目标。

v1（根路径导入）：

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

v2（/v2 导入）：

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

注意： @copilotkit/react-core/v2 也导出一个 CopilotKitProvider 组件。请不要迁移到它 -- 它是 CopilotKit 的功能子集，而 CopilotKit 是跨越 v1 和 v2 的兼容桥接，接受所有 CopilotKitProvider prop。

7. 验证

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

快速参考

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