copilotkit-debug

CopilotKit デバッグスキル

使用するタイミング

次の場合にこのスキルを呼び出します。

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

診断ワークフロー

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

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

1. パッケージのバージョン -- npm ls @copilotkit/runtime @copilotkit/react-core @copilotkit/core @ag-ui/client（または v1 相当のパッケージ）を実行します。ランタイムと React パッケージのバージョン不一致は、よくある根本原因です。
2. ランタイムモード -- SSE モード（CopilotSseRuntime）ですか、それとも Intelligence モード（CopilotIntelligenceRuntime）ですか？ランタイムのコンストラクターを確認します。
3. トランスポート設定 -- CopilotKit プロバイダー（@copilotkit/react-core/v2）の runtimeUrl には何が設定されていますか？createCopilotRuntimeHandler の 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 の最新ドキュメントを参照してください。このサーバーには、search-docs（ドキュメントを検索）と search-code（ソースコードの例を検索）の 2 つのツールがあります。

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 コードベース内の主要なファイルの場所

コンポーネント	パス
レガシーのエラークラスとコード	packages/shared/src/utils/errors.ts
V2 コアのエラーコード	packages/core/src/core/core.ts (CopilotKitCoreErrorCode enum)
V2 の文字起こしエラー	packages/shared/src/transcription-errors.ts
ランタイムの SSE レスポンス	packages/runtime/src/v2/runtime/handlers/shared/sse-response.ts
ランタイム情報のエンドポイント	packages/runtime/src/v2/runtime/handlers/get-runtime-info.ts
ランタイムの CORS 設定	packages/runtime/src/v2/runtime/core/fetch-cors.ts
CopilotKit Intelligence クライアント	packages/runtime/src/v2/runtime/intelligence-platform/client.ts
BuiltInAgent	packages/runtime/src/agent/index.ts
Web Inspector	packages/web-inspector/src/index.ts