copilotkit-debug

CopilotKit 调试技能

适用场景

遇到以下情况时，请调用此技能：

• 无法访问 CopilotKit 运行时，或运行时返回错误
• Agent 无法连接、响应或流式传输事件
• 前端工具未执行或未返回结果
• 转录（语音）失败
• 软件包之间出现版本不匹配错误
• 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. 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 -- 推理令牌（可能导致停滞，参见 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 工具调用（而非 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 枚举）
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
Agent 包（BuiltInAgent）	packages/v2/agent/src/index.ts
Web Inspector	packages/v2/web-inspector/src/index.ts