copilotkit-upgrade

CopilotKit v1 から v2 への移行スキル

ライブドキュメント（MCP）

このプラグインには、ライブの CopilotKit ドキュメントとソースコードを検索するための search-docs ツールと search-code ツールを提供する MCP サーバー（copilotkit-docs）が含まれています。移行中に最新の 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 のパターン（エージェント + 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. 検証する

• アプリケーションを実行し、ランタイムエラーがないか確認します
• エージェントとのやり取り（チャット、ツール呼び出し、中断）がすべて機能することを確認します
• ツールレンダラーが正しく表示されることを確認します
• 提案が読み込まれて表示されることを確認します

クイックリファレンス

概念	v1	v2
パッケージスコープ	@copilotkit/*	@copilotkit/*（同じスコープ、更新された API）
プロトコル	GraphQL	AG-UI（SSE）
プロバイダーコンポーネント	CopilotKit	CopilotKitProvider
フロントエンドツールの定義	useCopilotAction	useFrontendTool
アプリの状態を共有	useCopilotReadable	useAgentContext
エージェントとのやり取り	useCoAgent	useAgent
中断の処理	useLangGraphInterrupt	useInterrupt
ツール呼び出しのレンダリング	useCopilotAction({ render })	useRenderToolCall
チャットの提案	useCopilotChatSuggestions	useConfigureSuggestions
ランタイムクラス	CopilotRuntime（アダプター）	CopilotRuntime（エージェント）
エンドポイントの設定	copilotKitEndpoint()	createCopilotEndpoint()
エージェントの定義	LangGraphAgent エンドポイント	AbstractAgent / BuiltInAgent
チャットコンポーネント	CopilotChat、CopilotPopup、CopilotSidebar	@copilotkit/react の CopilotChat、CopilotPopup、CopilotSidebar