如何用 CopilotKit Debug Mode 在 AG-UI 事件管道中定位事件丢失【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit当 Agent 行为异常——事件没有到达客户端、状态不更新、工具调用没有执行——你需要的不是猜测而是事件管道本身的日志。CopilotKit 的 Debug Mode 提供结构化的服务端日志Pino组件标签copilotkit-debug覆盖从Agent run started到SSE stream completed的完整请求生命周期前端则可以通过浏览器 Network 面板或 AG-UI Event Inspector 核对同一批事件是否真的在线路上。下面给出从开启调试到判断事件丢在哪一段的完整操作路径。开启服务端 Debug Mode事件丢失问题的第一观察点是运行时Runtime侧事件是否被 Agent 发出、是否写入了 SSE 流。在CopilotRuntime构造参数中传入debug: trueconst runtime new CopilotRuntime({ agents: { // your agents }, debug: true, });开启后每次 Agent 运行会产生带copilotkit-debug标签的结构化 Pino 日志经pino-pretty格式化。文档示例输出如下[14:32:01.123] DEBUG (copilotkit-debug): Agent run started agentName: default threadId: abc-123 [14:32:01.130] DEBUG (copilotkit-debug): SSE stream opened [14:32:01.145] DEBUG (copilotkit-debug): Event emitted type: TEXT_MESSAGE_START messageId: msg-1 role: assistant [14:32:01.200] DEBUG (copilotkit-debug): Event emitted type: TEXT_MESSAGE_CONTENT deltaLength: 42 [14:32:01.250] DEBUG (copilotkit-debug): Event emitted type: TEXT_MESSAGE_END [14:32:01.260] DEBUG (copilotkit-debug): Event emitted type: RUN_FINISHED [14:32:01.261] DEBUG (copilotkit-debug): SSE stream completed eventCount: 4 loggedEventCount: 4以上是文档示例仅用于说明日志形态你的运行会产生不同的时间戳、threadId和事件数不要按示例数值做固定校验。服务端会记录的日志类别如下类别日志消息含义LifecycleAgent run startedAgent 运行开始含 agent 名称与 thread IDLifecycleSSE stream openedSSE 响应流已创建LifecycleSSE stream completed流结束含总事件数LifecycleSSE stream errored流发生错误EventsEvent emitted每个 AG-UI 事件写入流时各记一条按需控制日志粒度需要更细的控制时把debug从true换成对象形式debug: { events: true, // 记录每个发出的/收到的事件 lifecycle: true, // 记录请求/运行生命周期start、finish、error verbose: false, // 记录完整 payload 而非摘要 }各输入对应的默认行为输入eventslifecycleverbosedebug: truetruetruefalsedebug: {}truetruefalsedebug: { events: false }falsetruefalse注意verbose默认关闭是刻意为之——避免在日志中泄露 PII。要拿完整事件 payload 必须显式写debug: { verbose: true }。非 verbose 模式下事件日志只包含messageId、toolCallId、toolCallName、role和内容长度这类摘要字段。定位事件丢失时通常先保持默认的debug: true只有当摘要不足以判断 payload 内容时再打开verbose。在服务端日志中定位丢失点开启 debug 后复现一次出问题的交互然后按文档给出的三步核对查找Event emitted日志——期望的事件是否确实被发出了核对SSE stream completed中的eventCount是否符合预期数量。用浏览器 Network 面板确认 SSE 事件是否真的到达客户端。由此可以区分两种情况服务端有Event emitted但浏览器 SSE 流里没有问题出在传输/连接层而不是 Agent 侧。文档对状态不更新场景给出同样的判断法在日志中找STATE_SNAPSHOT或STATE_DELTA若服务端有而浏览器 SSE 流中没有可能存在连接问题。服务端根本没有Event emitted事件在 Agent 运行阶段就缺失了应继续看Agent run started之后的 lifecycle 日志确认运行是否真正开始、是否出现SSE stream errored。工具调用不执行的核对点同一套日志也可用于排查工具调用没执行。依次确认服务端是否发出了TOOL_CALL_STARTTOOL_CALL_ARGS和TOOL_CALL_END是否按顺序跟随这些事件是否出现在浏览器 Network 面板的 SSE 流中。可选分支用 AG-UI Event Inspector 实时查看事件流如果不想盯终端日志可以用 VS Code 里的 AG-UI Event Inspector 以实时面板形式查看 runtime 与客户端之间的完整事件流带分类过滤、彩色事件徽章、完整 JSON payload。前提条件CopilotKit runtime 以开发模式本地运行NODE_ENV不是production已安装 CopilotKit VS Code 扩展。/cpk-debug-events端点在NODE_ENVproduction时会被禁用这是有意设计——它流式输出内部事件数据不应暴露在生产环境。操作步骤先确认端点可达。端点位于GET {runtimeUrl}/cpk-debug-events路径相对于 runtime 挂载的basePath而不是服务源的根路径。例如 runtime 挂载在 8200 端口的/api/copilotkit流地址就是http://localhost:8200/api/copilotkit/cpk-debug-events请求http://localhost:8200/cpk-debug-events会返回404 {error:Not found}。可用 curl 验证curl -N http://localhost:8200/api/copilotkit/cpk-debug-events端点正常时会立即返回: connected并保持连接打开。在 VS Code 中打开命令面板CtrlShiftP/CmdShiftP运行CopilotKit: Open AG-UI Inspector在面板顶部输入框填入 runtime URL默认http://localhost:4000并点击Connect。这里要填前端传给runtimeUrl的完整挂载地址含 base path而不是只有 origin。连接建立后状态指示变绿。回到应用触发一次 Agent 交互发消息、调用工具或操作任何 CopilotKit 组件事件随即开始流入面板。阅读事件流每行显示相对时间戳如0.142s、按类别着色的事件类型徽章、以及关键字段摘要message ID、工具名、文本预览。顶部类别过滤按钮可显示/隐藏类别搜索框可按工具名、message ID 或内容检索 payload。点击任意事件行可展开完整 JSON payload包含agentId、threadId、runId及完整事件数据。事件类型与文档的分类对照类别事件类型LifecycleRUN_STARTED、RUN_FINISHEDErrorsRUN_ERRORText MessagesTEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT、TEXT_MESSAGE_END、TEXT_MESSAGE_CHUNKTool CallsTOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END、TOOL_CALL_CHUNK、TOOL_CALL_RESULTStateSTATE_SNAPSHOT、STATE_DELTA一个重要的适用限制这条 SSE 调试流承载的是自托管 runtime发出的 AG-UI 事件。如果你的 runtime 配置了intelligence运行走的是 CopilotKit Intelligence 的实时连接/cpk-debug-events会连接成功并显示: connected但之后一直是空的。这种 runtime 要追踪运行事件应使用客户端侧读取事件的 in-app Inspector而不是这条端点。React 客户端调试开关可选React 前端可以给CopilotKitprovider 传debug{true}CopilotKit runtimeUrl/api/copilotkit debug{true} YourApp / /CopilotKit这个开关会把 debug 配置转发给 AG-UI 客户端传输层transformChunks具体产生什么传输层调试输出取决于 AG-UI 库版本。CopilotKit 自身不会发console.debug——最丰富的事件管道日志仍然来自服务端的CopilotRuntime定位事件丢失时服务端debug: true是主路径。服务端与客户端的 debug 开关相互独立客户端开启不影响服务端反之亦然。Angular 前端没有单独的客户端 debug 开关文档建议直接启用 runtime 侧 debug再用浏览器开发者工具检查 SSE 请求或连接 AG-UI Event Inspector 到开发环境 runtime。限制与注意事项Debug Mode 日志量很大verbose 模式下尤甚文档明确要求只用于开发和调试不要在生产环境开启。/cpk-debug-events端点仅在非生产环境可用NODE_ENV ! production时自动激活无需额外配置。Debug Mode 聚焦事件管道日志如果你要的是 UI 层错误展示错误横幅、dev console那是另一套机制showDevConsole{true}与onError回调见 Error Debugging两者不要混用。若运行时是intelligence配置SSE 调试流为空不代表连接故障应改用 in-app Inspector见 AG-UI Event Inspector。参考文档Debug Mode本文的服务端/客户端开关、日志类别与排查步骤来源AG-UI Event Inspector/cpk-debug-events端点与 VS Code 检查器操作Error Debugging ObservabilityUI 级错误展示与onError编程接口【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何用 CopilotKit Debug Mode 在 AG-UI 事件管道中定位事件丢失
如何用 CopilotKit Debug Mode 在 AG-UI 事件管道中定位事件丢失【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit当 Agent 行为异常——事件没有到达客户端、状态不更新、工具调用没有执行——你需要的不是猜测而是事件管道本身的日志。CopilotKit 的 Debug Mode 提供结构化的服务端日志Pino组件标签copilotkit-debug覆盖从Agent run started到SSE stream completed的完整请求生命周期前端则可以通过浏览器 Network 面板或 AG-UI Event Inspector 核对同一批事件是否真的在线路上。下面给出从开启调试到判断事件丢在哪一段的完整操作路径。开启服务端 Debug Mode事件丢失问题的第一观察点是运行时Runtime侧事件是否被 Agent 发出、是否写入了 SSE 流。在CopilotRuntime构造参数中传入debug: trueconst runtime new CopilotRuntime({ agents: { // your agents }, debug: true, });开启后每次 Agent 运行会产生带copilotkit-debug标签的结构化 Pino 日志经pino-pretty格式化。文档示例输出如下[14:32:01.123] DEBUG (copilotkit-debug): Agent run started agentName: default threadId: abc-123 [14:32:01.130] DEBUG (copilotkit-debug): SSE stream opened [14:32:01.145] DEBUG (copilotkit-debug): Event emitted type: TEXT_MESSAGE_START messageId: msg-1 role: assistant [14:32:01.200] DEBUG (copilotkit-debug): Event emitted type: TEXT_MESSAGE_CONTENT deltaLength: 42 [14:32:01.250] DEBUG (copilotkit-debug): Event emitted type: TEXT_MESSAGE_END [14:32:01.260] DEBUG (copilotkit-debug): Event emitted type: RUN_FINISHED [14:32:01.261] DEBUG (copilotkit-debug): SSE stream completed eventCount: 4 loggedEventCount: 4以上是文档示例仅用于说明日志形态你的运行会产生不同的时间戳、threadId和事件数不要按示例数值做固定校验。服务端会记录的日志类别如下类别日志消息含义LifecycleAgent run startedAgent 运行开始含 agent 名称与 thread IDLifecycleSSE stream openedSSE 响应流已创建LifecycleSSE stream completed流结束含总事件数LifecycleSSE stream errored流发生错误EventsEvent emitted每个 AG-UI 事件写入流时各记一条按需控制日志粒度需要更细的控制时把debug从true换成对象形式debug: { events: true, // 记录每个发出的/收到的事件 lifecycle: true, // 记录请求/运行生命周期start、finish、error verbose: false, // 记录完整 payload 而非摘要 }各输入对应的默认行为输入eventslifecycleverbosedebug: truetruetruefalsedebug: {}truetruefalsedebug: { events: false }falsetruefalse注意verbose默认关闭是刻意为之——避免在日志中泄露 PII。要拿完整事件 payload 必须显式写debug: { verbose: true }。非 verbose 模式下事件日志只包含messageId、toolCallId、toolCallName、role和内容长度这类摘要字段。定位事件丢失时通常先保持默认的debug: true只有当摘要不足以判断 payload 内容时再打开verbose。在服务端日志中定位丢失点开启 debug 后复现一次出问题的交互然后按文档给出的三步核对查找Event emitted日志——期望的事件是否确实被发出了核对SSE stream completed中的eventCount是否符合预期数量。用浏览器 Network 面板确认 SSE 事件是否真的到达客户端。由此可以区分两种情况服务端有Event emitted但浏览器 SSE 流里没有问题出在传输/连接层而不是 Agent 侧。文档对状态不更新场景给出同样的判断法在日志中找STATE_SNAPSHOT或STATE_DELTA若服务端有而浏览器 SSE 流中没有可能存在连接问题。服务端根本没有Event emitted事件在 Agent 运行阶段就缺失了应继续看Agent run started之后的 lifecycle 日志确认运行是否真正开始、是否出现SSE stream errored。工具调用不执行的核对点同一套日志也可用于排查工具调用没执行。依次确认服务端是否发出了TOOL_CALL_STARTTOOL_CALL_ARGS和TOOL_CALL_END是否按顺序跟随这些事件是否出现在浏览器 Network 面板的 SSE 流中。可选分支用 AG-UI Event Inspector 实时查看事件流如果不想盯终端日志可以用 VS Code 里的 AG-UI Event Inspector 以实时面板形式查看 runtime 与客户端之间的完整事件流带分类过滤、彩色事件徽章、完整 JSON payload。前提条件CopilotKit runtime 以开发模式本地运行NODE_ENV不是production已安装 CopilotKit VS Code 扩展。/cpk-debug-events端点在NODE_ENVproduction时会被禁用这是有意设计——它流式输出内部事件数据不应暴露在生产环境。操作步骤先确认端点可达。端点位于GET {runtimeUrl}/cpk-debug-events路径相对于 runtime 挂载的basePath而不是服务源的根路径。例如 runtime 挂载在 8200 端口的/api/copilotkit流地址就是http://localhost:8200/api/copilotkit/cpk-debug-events请求http://localhost:8200/cpk-debug-events会返回404 {error:Not found}。可用 curl 验证curl -N http://localhost:8200/api/copilotkit/cpk-debug-events端点正常时会立即返回: connected并保持连接打开。在 VS Code 中打开命令面板CtrlShiftP/CmdShiftP运行CopilotKit: Open AG-UI Inspector在面板顶部输入框填入 runtime URL默认http://localhost:4000并点击Connect。这里要填前端传给runtimeUrl的完整挂载地址含 base path而不是只有 origin。连接建立后状态指示变绿。回到应用触发一次 Agent 交互发消息、调用工具或操作任何 CopilotKit 组件事件随即开始流入面板。阅读事件流每行显示相对时间戳如0.142s、按类别着色的事件类型徽章、以及关键字段摘要message ID、工具名、文本预览。顶部类别过滤按钮可显示/隐藏类别搜索框可按工具名、message ID 或内容检索 payload。点击任意事件行可展开完整 JSON payload包含agentId、threadId、runId及完整事件数据。事件类型与文档的分类对照类别事件类型LifecycleRUN_STARTED、RUN_FINISHEDErrorsRUN_ERRORText MessagesTEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT、TEXT_MESSAGE_END、TEXT_MESSAGE_CHUNKTool CallsTOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END、TOOL_CALL_CHUNK、TOOL_CALL_RESULTStateSTATE_SNAPSHOT、STATE_DELTA一个重要的适用限制这条 SSE 调试流承载的是自托管 runtime发出的 AG-UI 事件。如果你的 runtime 配置了intelligence运行走的是 CopilotKit Intelligence 的实时连接/cpk-debug-events会连接成功并显示: connected但之后一直是空的。这种 runtime 要追踪运行事件应使用客户端侧读取事件的 in-app Inspector而不是这条端点。React 客户端调试开关可选React 前端可以给CopilotKitprovider 传debug{true}CopilotKit runtimeUrl/api/copilotkit debug{true} YourApp / /CopilotKit这个开关会把 debug 配置转发给 AG-UI 客户端传输层transformChunks具体产生什么传输层调试输出取决于 AG-UI 库版本。CopilotKit 自身不会发console.debug——最丰富的事件管道日志仍然来自服务端的CopilotRuntime定位事件丢失时服务端debug: true是主路径。服务端与客户端的 debug 开关相互独立客户端开启不影响服务端反之亦然。Angular 前端没有单独的客户端 debug 开关文档建议直接启用 runtime 侧 debug再用浏览器开发者工具检查 SSE 请求或连接 AG-UI Event Inspector 到开发环境 runtime。限制与注意事项Debug Mode 日志量很大verbose 模式下尤甚文档明确要求只用于开发和调试不要在生产环境开启。/cpk-debug-events端点仅在非生产环境可用NODE_ENV ! production时自动激活无需额外配置。Debug Mode 聚焦事件管道日志如果你要的是 UI 层错误展示错误横幅、dev console那是另一套机制showDevConsole{true}与onError回调见 Error Debugging两者不要混用。若运行时是intelligence配置SSE 调试流为空不代表连接故障应改用 in-app Inspector见 AG-UI Event Inspector。参考文档Debug Mode本文的服务端/客户端开关、日志类别与排查步骤来源AG-UI Event Inspector/cpk-debug-events端点与 VS Code 检查器操作Error Debugging ObservabilityUI 级错误展示与onError编程接口【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考