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（新しいフック名、コンポーネント名、ランタイム設定）とともに、同じパッケージ名（/v2 サブパス配下）を通じて公開されます。基盤となる @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 を特定する

置き換える主なフックとコンポーネントは次のとおりです。

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	削除済み -- 標準のテキストエリアと useFrontendTool を使用

3. v2 の対応 API に置き換える

コードの変更前後の詳しい例については、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 のパターン（エージェント + 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" });

正式な Hono エンドポイントファクトリーとして、@copilotkit/runtime/v2 からの createCopilotHonoHandler を使用してください。createCopilotEndpoint はその非推奨のエイリアスです。新しいコードでは使用しないでください。Express の場合は、@copilotkit/runtime/v2/express から createCopilotExpressHandler を使用してください（createCopilotEndpointExpress はその非推奨のエイリアスです）。

6. プロバイダーの更新

プロバイダーコンポーネントの名前は CopilotKit のままです。変更されるのはインポートパスのみです。パッケージルート（@copilotkit/react-core）は従来の v1 プロバイダーであり、/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 のプロパティを受け付けます。

7. 検証

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

クイックリファレンス

概念	v1	v2
パッケージスコープ	@copilotkit/*	@copilotkit/*（同じスコープ、API を更新）
プロトコル	GraphQL	AG-UI（SSE）
プロバイダーコンポーネント	CopilotKit（@copilotkit/react-core から）	CopilotKit（@copilotkit/react-core/v2 から）
フロントエンドツールの定義	useCopilotAction	useFrontendTool
アプリの状態の共有	useCopilotReadable	useAgentContext
エージェントとのインタラクション	useCoAgent	useAgent
中断の処理	useLangGraphInterrupt	useInterrupt
ツール呼び出しのレンダリング	useCopilotAction({ render })	useFrontendTool({ render }) または useRenderTool（レンダリング専用）
チャットの提案	useCopilotChatSuggestions	useConfigureSuggestions
ランタイムクラス	CopilotRuntime（アダプター）	CopilotRuntime（エージェント、@copilotkit/runtime/v2 から）
エンドポイントの設定	copilotRuntimeNextJSAppRouterEndpoint()	createCopilotHonoHandler()（createCopilotEndpoint は非推奨のエイリアスです）
エージェントの定義	LangGraphAgent エンドポイント	AbstractAgent / BuiltInAgent（@copilotkit/runtime/v2 から）
チャットコンポーネント	CopilotChat、CopilotPopup、CopilotSidebar	CopilotChat、CopilotPopup、CopilotSidebar（@copilotkit/react-core/v2 から）