copilotkit-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CopilotKit Debugging Skill

CopilotKit 调试技能

When to Use

使用场景

Invoke this skill when:

The CopilotKit runtime is unreachable or returning errors
Agents fail to connect, respond, or stream events
Frontend tools are not executing or returning results
Transcription (voice) is failing
Version mismatch errors appear between packages
AG-UI SSE events are malformed or missing
CORS errors block browser requests to the runtime

在以下情况调用此技能：

CopilotKit运行时无法访问或返回错误
Agent连接失败、无响应或事件流中断
前端工具无法执行或返回结果
语音转录功能失效
各包之间出现版本不匹配错误
AG-UI SSE事件格式错误或缺失
CORS错误阻止浏览器向运行时发送请求

Diagnostic Workflow

诊断流程

Step 1: Gather Information

步骤1：收集信息

Before proposing any fix, collect:

Package versions -- Run
```
npm ls @copilotkit/runtime @copilotkit/react @copilotkit/core @ag-ui/client
```
(or the v1 equivalents). Version mismatches between runtime and react packages are a common root cause.
Runtime mode -- Is this SSE mode (
```
CopilotSseRuntime
```
) or Intelligence mode (
```
CopilotIntelligenceRuntime
```
)? Check the runtime constructor.
Transport configuration -- What is
```
runtimeUrl
```
set to in
```
CopilotKitProvider
```
? Does it match the
```
basePath
```
in
```
createCopilotEndpoint
```
?

Agent type -- Is the agent a

BuiltInAgent

LangGraphAgent

A2AAgent

, or custom

AbstractAgent

Error messages -- Collect the exact error from browser console and server logs. CopilotKit uses structured error codes (see
```
references/error-patterns.md
```
).
Browser network tab -- Check the
```
/info
```
request (runtime discovery), the
```
/agent/:id/run
```
SSE stream, and any CORS preflight failures.

在提出修复方案前，先收集以下信息：

包版本 —— 运行
```
npm ls @copilotkit/runtime @copilotkit/react @copilotkit/core @ag-ui/client
```
（或v1等价命令）。运行时与react包之间的版本不匹配是常见的根本原因。
运行时模式 —— 当前是SSE模式（
```
CopilotSseRuntime
```
）还是智能模式（
```
CopilotIntelligenceRuntime
```
）？检查运行时构造函数。
传输配置 ——
```
CopilotKitProvider
```
中的
```
runtimeUrl
```
设置为何值？它是否与
```
createCopilotEndpoint
```
中的
```
basePath
```
匹配？
Agent类型 —— Agent是
```
BuiltInAgent
```
、
```
LangGraphAgent
```
、
```
A2AAgent
```
还是自定义
```
AbstractAgent
```
？
错误信息 —— 从浏览器控制台和服务器日志中收集准确的错误信息。CopilotKit使用结构化错误代码（详见
```
references/error-patterns.md
```
）。
浏览器网络面板 —— 检查
```
/info
```
请求（运行时发现）、
```
/agent/:id/run
```
SSE流以及任何CORS预检失败情况。

Step 2: Check Logs and Error Codes

步骤2：检查日志与错误代码

CopilotKit has three error code systems:

V1 error codes -- Legacy error codes from the v1 runtime layer (
```
@copilotkit/runtime
```
). Codes like
```
NETWORK_ERROR
```
,
```
AGENT_NOT_FOUND
```
,
```
API_NOT_FOUND
```
. Still surfaced in some contexts since
```
@copilotkit/*
```
packages wrap v2 internally.

V2
CopilotKitCoreErrorCode
-- Used by

@copilotkit/core

. Codes like

runtime_info_fetch_failed

agent_connect_failed

agent_run_failed

TranscriptionErrorCode
-- Used by both v1 and v2 for voice transcription. Codes like

service_not_configured

rate_limited

auth_failed

Match the error code to the catalog in

references/error-patterns.md

for root cause and resolution.

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

中的目录匹配，找到根本原因和解决方法。

Step 3: Trace AG-UI Events

步骤3：追踪AG-UI事件

For streaming/agent issues, trace the AG-UI event flow:

RunStartedEvent -- Confirms the agent run was initiated
TextMessageStartEvent / TextMessageChunkEvent / TextMessageEndEvent -- Text streaming
ToolCallStartEvent / ToolCallArgsEvent / ToolCallEndEvent -- Tool invocations
ToolCallResultEvent -- Tool results flowing back
StateSnapshotEvent / StateDeltaEvent -- Agent state synchronization
ReasoningStartEvent / ReasoningMessageContentEvent / ReasoningMessageEndEvent -- Reasoning tokens (can cause stalls, see issue #3323)
RunFinishedEvent -- Successful completion
RunErrorEvent -- Agent-level error

Enable the CopilotKit Web Inspector (

@copilotkit/web-inspector

) to see events in real time. Or check the SSE stream directly in the browser Network tab -- each event is a

data:

line in the

text/event-stream

response.

针对流传输/Agent问题，追踪AG-UI事件流：

RunStartedEvent —— 确认Agent运行已启动
TextMessageStartEvent / TextMessageChunkEvent / TextMessageEndEvent —— 文本流传输
ToolCallStartEvent / ToolCallArgsEvent / ToolCallEndEvent —— 工具调用
ToolCallResultEvent —— 工具结果返回
StateSnapshotEvent / StateDeltaEvent —— Agent状态同步
ReasoningStartEvent / ReasoningMessageContentEvent / ReasoningMessageEndEvent —— 推理令牌（可能导致停滞，详见问题#3323）
RunFinishedEvent —— 成功完成
RunErrorEvent —— Agent级错误

启用CopilotKit Web Inspector（

@copilotkit/web-inspector

）实时查看事件。或直接在浏览器网络面板中检查SSE流——每个事件都是

text/event-stream

响应中的

data:

行。

Step 4: Identify Root Cause

步骤4：定位根本原因

Use the reference documents to match symptoms to known issues:

references/runtime-debugging.md
-- Connectivity, CORS, transport, SSE streaming
references/agent-debugging.md
-- Agent discovery, state sync, tool execution, AG-UI protocol
references/error-patterns.md
-- Complete error code catalog with resolutions
references/quick-workflows.md
-- Step-by-step diagnostic sequences for common scenarios

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

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

Step 5: Fix and Verify

步骤5：修复与验证

Apply the fix
Verify the
```
/info
```
endpoint returns the expected agent list
Confirm the SSE stream produces a complete event sequence (RunStarted through RunFinished)
Check the browser console for any remaining structured errors

应用修复方案
验证
```
/info
```
端点返回预期的Agent列表
确认SSE流生成完整的事件序列（从RunStarted到RunFinished）
检查浏览器控制台是否仍有结构化错误

Using mcp-docs for Live Documentation Lookups

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

During debugging, use the

copilotkit-docs

MCP server to look up the latest CopilotKit documentation. This server provides two tools:

search-docs

(search documentation) and

search-code

(search source code examples).

调试期间，使用

copilotkit-docs

MCP服务器查询最新的CopilotKit文档。该服务器提供两个工具：

search-docs

（搜索文档）和

search-code

（搜索源代码示例）。

MCP Setup

MCP设置

Claude Code: The MCP server is auto-configured by the plugin's

.mcp.json

-- no manual setup needed. The agent can call the

search-docs

and

search-code

tools from the

copilotkit-docs

server directly.

Codex: Add the following to your

.codex/config.toml

toml

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

Claude Code： MCP服务器由插件的

.mcp.json

自动配置——无需手动设置。Agent可直接从

copilotkit-docs

服务器调用

search-docs

和

search-code

工具。

Codex： 将以下内容添加到

.codex/config.toml

中：

toml

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

Tool Usage

工具使用

The

search-docs

and

search-code

tools are invoked as MCP tool calls (not CLI commands). Examples of what to search for during debugging:

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")

The official troubleshooting docs are at:

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

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

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

Key File Locations in the CopilotKit Codebase

CopilotKit代码库中的关键文件位置

Component	Path
V1 Error classes & codes	`packages/v1/shared/src/utils/errors.ts`
V2 Core error codes	`packages/v2/core/src/core/core.ts` ( `CopilotKitCoreErrorCode` enum)
V2 Transcription errors	`packages/v2/shared/src/transcription-errors.ts`
Runtime SSE response	`packages/v2/runtime/src/handlers/shared/sse-response.ts`
Runtime info endpoint	`packages/v2/runtime/src/handlers/get-runtime-info.ts`
Runtime CORS config	`packages/v2/runtime/src/endpoints/hono.ts`
Intelligence platform client	`packages/v2/runtime/src/intelligence-platform/client.ts`
Agent package (BuiltInAgent)	`packages/v2/agent/src/index.ts`
Web Inspector	`packages/v2/web-inspector/src/index.ts`

组件	路径
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`
运行时info端点	`packages/v2/runtime/src/handlers/get-runtime-info.ts`
运行时CORS配置	`packages/v2/runtime/src/endpoints/hono.ts`
智能平台客户端	`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`