copilotkit-debug

CopilotKit 调试技能

何时使用

在以下情况调用此技能：

• CopilotKit 运行时不可达或返回错误
• Agent 无法连接、响应或流式传输事件
• 前端工具未执行或未返回结果
• 转录（语音）失败
• 包之间出现版本不匹配错误
• 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 provider（来自 @copilotkit/react-core/v2）上的 runtimeUrl 设置为什么？它是否与 createCopilotRuntimeHandler 中的 basePath 匹配？
4. Agent 类型 -- Agent 是 BuiltInAgent、LangGraphAgent、A2AAgent，还是自定义 AbstractAgent？
5. 错误消息 -- 从浏览器控制台和服务器日志中收集确切的错误。CopilotKit 使用结构化错误代码（参见 references/error-patterns.md）。
6. 浏览器网络标签页 -- 检查 /info 请求（运行时发现）、/agent/:id/run SSE 流，以及任何 CORS 预检失败。

第 2 步：检查日志和错误代码

CopilotKit 有三套错误代码系统：

• 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 事件

对于流式/Agent 问题，追踪 AG-UI 事件流：

1. RunStartedEvent -- 确认 Agent 运行已启动
2. TextMessageStartEvent / TextMessageChunkEvent / TextMessageEndEvent -- 文本流式传输
3. ToolCallStartEvent / ToolCallArgsEvent / ToolCallEndEvent -- 工具调用
4. ToolCallResultEvent -- 工具结果回流
5. StateSnapshotEvent / StateDeltaEvent -- Agent 状态同步
6. ReasoningStartEvent / ReasoningMessageContentEvent / ReasoningMessageEndEvent -- 推理 token（可能导致停滞，参见 issue #3323）
7. RunFinishedEvent -- 成功完成
8. RunErrorEvent -- Agent 级错误

启用 CopilotKit Web Inspector（@copilotkit/web-inspector）以实时查看事件。或在浏览器网络标签页中直接检查 SSE 流 -- 每个事件都是 text/event-stream 响应中的一行 data:。

第 4 步：确定根因

使用参考文档将症状与已知问题匹配：

• references/runtime-debugging.md -- 连接性、CORS、传输、SSE 流式传输
• references/agent-debugging.md -- Agent 发现、状态同步、工具执行、AG-UI 协议
• references/error-patterns.md -- 完整的错误代码目录及解决方案
• references/quick-workflows.md -- 常见场景的分步诊断流程

第 5 步：修复并验证

1. 应用修复
2. 验证 /info 端点返回预期的 Agent 列表
3. 确认 SSE 流产生完整的事件序列（从 RunStarted 到 RunFinished）
4. 检查浏览器控制台是否有任何残留的结构化错误

使用 mcp-docs 进行实时文档查询

在调试过程中，使用 copilotkit-docs MCP 服务查找最新的 CopilotKit 文档。该服务提供两个工具：search-docs（搜索文档）和 search-code（搜索源代码示例）。

MCP 设置

Claude Code： MCP 服务由插件的 .mcp.json 自动配置——无需手动设置。Agent 可以直接从 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 工具调用（而非命令行命令）来调用。以下是调试期间可搜索内容的示例：

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 代码库中的关键文件位置

Component	Path
Legacy error classes & codes	packages/shared/src/utils/errors.ts
V2 Core error codes	packages/core/src/core/core.ts (CopilotKitCoreErrorCode enum)
V2 Transcription errors	packages/shared/src/transcription-errors.ts
Runtime SSE response	packages/runtime/src/v2/runtime/handlers/shared/sse-response.ts
Runtime info endpoint	packages/runtime/src/v2/runtime/handlers/get-runtime-info.ts
Runtime CORS config	packages/runtime/src/v2/runtime/core/fetch-cors.ts
CopilotKit Intelligence client	packages/runtime/src/v2/runtime/intelligence-platform/client.ts
BuiltInAgent	packages/runtime/src/agent/index.ts
Web Inspector	packages/web-inspector/src/index.ts