copilotkit-debug

CopilotKit デバッグスキル

使用するタイミング

次の場合にこのスキルを呼び出してください：

• CopilotKit ランタイムに接続できない、またはエラーが返される
• エージェントが接続、応答、イベントのストリーミングに失敗する
• フロントエンドのツールが実行されない、または結果が返されない
• 文字起こし（音声）に失敗する
• パッケージ間のバージョン不一致エラーが表示される
• AG-UI SSE イベントの形式が不正、またはイベントが欠落している
• CORS エラーによって、ブラウザーからランタイムへのリクエストがブロックされる

診断ワークフロー

ステップ 1：情報を収集する

修正方法を提案する前に、次の情報を収集します：

1. パッケージのバージョン -- npm ls @copilotkit/runtime @copilotkit/react @copilotkit/core @ag-ui/client（または v1 相当のパッケージ）を実行します。ランタイムと React パッケージのバージョン不一致は、よくある根本原因です。
2. ランタイムモード -- SSE モード（CopilotSseRuntime）ですか、それとも Intelligence モード（CopilotIntelligenceRuntime）ですか？ランタイムのコンストラクターを確認します。
3. トランスポートの設定 -- CopilotKitProvider の runtimeUrl には何が設定されていますか？createCopilotEndpoint の basePath と一致していますか？
4. エージェントの種類 -- エージェントは BuiltInAgent、LangGraphAgent、A2AAgent、それともカスタムの AbstractAgent ですか？
5. エラーメッセージ -- ブラウザーのコンソールとサーバーログから、正確なエラーを収集します。CopilotKit は構造化エラーコードを使用します（references/error-patterns.md を参照）。
6. ブラウザーのネットワークタブ -- /info リクエスト（ランタイムの検出）、/agent/:id/run の SSE ストリーム、CORS のプリフライトリクエストの失敗を確認します。

ステップ 2：ログとエラーコードを確認する

CopilotKit には、次の 3 つのエラーコード体系があります：

• V1 エラーコード -- v1 ランタイムレイヤー（@copilotkit/runtime）のレガシーエラーコードです。NETWORK_ERROR、AGENT_NOT_FOUND、API_NOT_FOUND などのコードがあります。@copilotkit/* パッケージが内部で v2 をラップするため、一部の状況では引き続き表示されます。
• V2 の CopilotKitCoreErrorCode -- @copilotkit/core で使用されます。runtime_info_fetch_failed、agent_connect_failed、agent_run_failed などのコードがあります。
• TranscriptionErrorCode -- 音声の文字起こしに v1 と v2 の両方で使用されます。service_not_configured、rate_limited、auth_failed などのコードがあります。

エラーコードを references/error-patterns.md のカタログと照合し、根本原因と解決方法を確認します。

ステップ 3：AG-UI イベントを追跡する

ストリーミングやエージェントに関する問題では、AG-UI イベントのフローを追跡します：

1. RunStartedEvent -- エージェントの実行が開始されたことを確認します
2. TextMessageStartEvent / TextMessageChunkEvent / TextMessageEndEvent -- テキストのストリーミング
3. ToolCallStartEvent / ToolCallArgsEvent / ToolCallEndEvent -- ツールの呼び出し
4. ToolCallResultEvent -- ツールの結果が返されること
5. StateSnapshotEvent / StateDeltaEvent -- エージェントの状態同期
6. ReasoningStartEvent / ReasoningMessageContentEvent / ReasoningMessageEndEvent -- 推論トークン（一時停止を引き起こす場合があります。issue #3323 を参照）
7. RunFinishedEvent -- 正常な完了
8. RunErrorEvent -- エージェントレベルのエラー

CopilotKit Web Inspector（@copilotkit/web-inspector）を有効にすると、イベントをリアルタイムで確認できます。または、ブラウザーのネットワークタブで SSE ストリームを直接確認します。text/event-stream レスポンスでは、各イベントが data: 行として表示されます。

ステップ 4：根本原因を特定する

リファレンスドキュメントを使って、症状を既知の問題と照合します：

• references/runtime-debugging.md -- 接続、CORS、トランスポート、SSE ストリーミング
• references/agent-debugging.md -- エージェントの検出、状態同期、ツールの実行、AG-UI プロトコル
• references/error-patterns.md -- 解決方法を含むエラーコードの完全なカタログ
• references/quick-workflows.md -- よくあるシナリオの段階的な診断手順

ステップ 5：修正して検証する

1. 修正を適用します
2. /info エンドポイントから期待されるエージェントリストが返されることを確認します
3. SSE ストリームでイベントの一連の流れが最後まで出力されることを確認します（RunStarted から RunFinished まで）
4. ブラウザーのコンソールに構造化エラーが残っていないか確認します

mcp-docs を使用した最新ドキュメントの検索

デバッグ中は、copilotkit-docs MCP サーバーを使用して、CopilotKit の最新ドキュメントを検索してください。このサーバーでは、2 つのツールを利用できます。search-docs（ドキュメントの検索）と search-code（ソースコードの例の検索）です。

MCP のセットアップ

Claude Code： MCP サーバーはプラグインの .mcp.json によって自動設定されるため、手動でのセットアップは不要です。エージェントは copilotkit-docs サーバーの search-docs および search-code ツールを直接呼び出せます。

Codex： 次の内容を .codex/config.toml に追加してください。

[mcp_servers.copilotkit-docs]
type = "http"
url = "https://mcp.copilotkit.ai/mcp"

ツールの使用方法

search-docs および search-code ツールは、MCP ツール呼び出しとして実行します（CLI コマンドではありません）。デバッグ中に検索する内容の例を以下に示します。

search-docs("AGENT_NOT_FOUND")
search-docs("CopilotRuntime configuration")
search-docs("AG-UI protocol events")
search-docs("troubleshooting common issues")
search-docs("CORS configuration copilotkit")
search-code("CopilotRuntime error handling")

公式のトラブルシューティングドキュメントは次のとおりです。

• https://docs.copilotkit.ai/troubleshooting/common-issues
• https://docs.copilotkit.ai/coagents/troubleshooting/common-issues

CopilotKit コードベース内の主要なファイルの場所

コンポーネント	パス
V1 エラークラスとコード	packages/v1/shared/src/utils/errors.ts
V2 コアエラーコード	packages/v2/core/src/core/core.ts (CopilotKitCoreErrorCode enum)
V2 文字起こしエラー	packages/v2/shared/src/transcription-errors.ts
ランタイム SSE レスポンス	packages/v2/runtime/src/handlers/shared/sse-response.ts
ランタイム情報エンドポイント	packages/v2/runtime/src/handlers/get-runtime-info.ts
ランタイム CORS 設定	packages/v2/runtime/src/endpoints/hono.ts
Intelligence platform クライアント	packages/v2/runtime/src/intelligence-platform/client.ts
エージェントパッケージ（BuiltInAgent）	packages/v2/agent/src/index.ts
Web Inspector	packages/v2/web-inspector/src/index.ts