CopilotKit 出现运行时不连通、Agent 不响应…

诊断 CopilotKit runtime 连通失败、Agent 不响应/不流式、前端工具不执行、语音转写失败、版本不匹配、AG-UI SSE 事件异常及 CORS 阻断等问题。

适用场景

解决思路

1. 先收集包版本：运行 `npm ls @copilotkit/runtime @copilotkit/react @copilotkit/core @ag-ui/client`（或 v1 对应包），检查 runtime 与 react 包版本是否不匹配，这是常见根因。
2. 确认 runtime 模式：判断是 SSE 模式（`CopilotSseRuntime`）还是 Intelligence 模式（`CopilotIntelligenceRuntime`），检查 runtime 构造函数。
3. 检查传输配置：查看 `CopilotKitProvider` 中的 `runtimeUrl`，确认它与 `createCopilotEndpoint` 的 `basePath` 一致。
4. 确认 Agent 类型：判断是 `BuiltInAgent`、`LangGraphAgent`、`A2AAgent` 还是自定义 `AbstractAgent`。
5. 收集错误信息：从浏览器 console 和服务端日志获取精确错误；CopilotKit 使用结构化错误码（见 `references/error-patterns.md`）。
6. 检查浏览器 Network 面板：查看 `/info` 请求（runtime discovery）、`/agent/:id/run` SSE 流以及任何 CORS preflight 失败。
7. 掌握三套错误码系统：V1 error codes 来自 v1 runtime 层 `@copilotkit/runtime`，如 `NETWORK_ERROR`、`AGENT_NOT_FOUND`、`API_NOT_FOUND`，仍可能出现在某些上下文，因为 `@copilotkit/*` 包内部包装 v2。
8. 识别 V2 `CopilotKitCoreErrorCode`：由 `@copilotkit/core` 使用，如 `runtime_info_fetch_failed`、`agent_connect_failed`、`agent_run_failed`。
9. 识别 `TranscriptionErrorCode`：v1 和 v2 语音转写共用，如 `service_not_configured`、`rate_limited`、`auth_failed`。
10. 将错误码匹配 `references/error-patterns.md` 目录，查根因与解决方案。
11. 追踪 AG-UI 事件流：先看 `RunStartedEvent` 确认 agent run 已启动。
12. 继续看 `TextMessageStartEvent` / `TextMessageChunkEvent` / `TextMessageEndEvent`，确认文本流式输出。
13. 查看 `ToolCallStartEvent` / `ToolCallArgsEvent` / `ToolCallEndEvent`，确认工具调用。
14. 查看 `ToolCallResultEvent`，确认工具结果回流。
15. 查看 `StateSnapshotEvent` / `StateDeltaEvent`，确认 Agent 状态同步。
16. 查看 `ReasoningStartEvent` / `ReasoningMessageContentEvent` / `ReasoningMessageEndEvent`，确认 reasoning token；它们可能导致停滞（见 issue #3323）。
17. 查看 `RunFinishedEvent`，确认成功完成。
18. 查看 `RunErrorEvent`，捕获 Agent 级错误。
19. 启用 CopilotKit Web Inspector（`@copilotkit/web-inspector`）实时查看事件；或直接在浏览器 Network 面板检查 SSE 流，每个事件是 `text/event-stream` 响应中的一行 `data:`。
20. 匹配症状到参考文档：`references/runtime-debugging.md` 用于连通性、CORS、传输、SSE 流式问题。
21. `references/agent-debugging.md` 用于 Agent 发现、状态同步、工具执行、AG-UI 协议问题。
22. `references/error-patterns.md` 用于完整错误码目录与解决方案。
23. `references/quick-workflows.md` 用于常见场景的分步诊断序列。
24. 应用修复。
25. 验证 `/info` 端点返回预期的 agent 列表。
26. 确认 SSE 流产生完整事件序列（从 `RunStarted` 到 `RunFinished`）。
27. 检查浏览器 console 是否还有残留的结构化错误。
28. 调试期间使用 `copilotkit-docs` MCP server 查询最新 CopilotKit 文档；它提供两个工具：`search-docs`（搜索文档）和 `search-code`（搜索源码示例）。
29. Claude Code：MCP server 由插件的 `.mcp.json` 自动配置，无需手动设置；agent 可直接调用 `copilotkit-docs` server 的 `search-docs` 和 `search-code` 工具。
30. Codex：在 `.codex/config.toml` 添加 `[mcp_servers.copilotkit-docs]`，`type = "http"`，`url = "https://mcp.copilotkit.ai/mcp"`。
31. 将 `search-docs` 和 `search-code` 作为 MCP tool calls 调用（不是 CLI 命令）。调试时可搜索：`search-docs("AGENT_NOT_FOUND")`。
32. 可搜索 `search-docs("CopilotRuntime configuration")`。
33. 可搜索 `search-docs("AG-UI protocol events")`。
34. 可搜索 `search-docs("troubleshooting common issues")`。
35. 可搜索 `search-docs("CORS configuration copilotkit")`。
36. 可搜索 `search-code("CopilotRuntime error handling")`。
37. 官方 troubleshooting 文档：`https://docs.copilotkit.ai/troubleshooting/common-issues`。
38. 官方 CoAgents troubleshooting 文档：`https://docs.copilotkit.ai/coagents/troubleshooting/common-issues`。
39. 排查源码时查看 V1 错误类与错误码：`packages/v1/shared/src/utils/errors.ts`。
40. V2 Core 错误码：`packages/v2/core/src/core/core.ts`（`CopilotKitCoreErrorCode` enum）。
41. V2 Transcription 错误：`packages/v2/shared/src/transcription-errors.ts`。
42. Runtime SSE response：`packages/v2/runtime/src/handlers/shared/sse-response.ts`。
43. Runtime info endpoint：`packages/v2/runtime/src/handlers/get-runtime-info.ts`。
44. Runtime CORS config：`packages/v2/runtime/src/endpoints/hono.ts`。
45. Intelligence platform client：`packages/v2/runtime/src/intelligence-platform/client.ts`。
46. Agent package（BuiltInAgent）：`packages/v2/agent/src/index.ts`。
47. Web Inspector：`packages/v2/web-inspector/src/index.ts`。

适用边界 · 注意事项

• 不适用于非 CopilotKit 项目，或问题与 CopilotKit runtime、Agent、AG-UI、语音转写、版本/CORS 无关的情况。
• 没有浏览器 Network 面板、console 或服务端日志时，无法执行完整的证据收集步骤。
• 无法访问 CopilotKit 源码/参考文档或不能使用 `copilotkit-docs` MCP 时，只能基于已有信息排查。