CopilotKit Built-in Agent 返回空消息怎么排查【免费下载链接】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当你在 CopilotKit v2 中用BuiltInAgent接入对话发送消息后 Agent 只回复一条空消息时说明请求链路是通的但这一轮没有产出可用内容。官方故障排查文档把空消息归因为三类原因模型字符串不被 runtime 的 provider 支持、Agent 的prompt为空导致没有可执行的系统指令、前端工具 handler 抛错后被 Agent 当作空结果当作本轮输出。本文按这三条路径给出排查步骤和观察手段。排查一核对模型字符串与 provider空消息最常见的原因是传给BuiltInAgent的模型字符串不被 runtime 的 provider 支持。Built-in Agent 底层使用 Vercel AI SDK模型通过provider:model格式指定provider/model分隔符也可以。先打开你注册 Agent 的 runtime 文件找到model这一项对照 Model Selection 文档中的支持列表Provider文档给出的示例OpenAIopenai:gpt-5、openai:gpt-4.1、openai:gpt-4o、openai:o3-miniAnthropicanthropic:claude-sonnet-4-6、anthropic:claude-haiku-4-5Googlegoogle:gemini-2.5-pro、google:gemini-2.5-flashMiniMaxminimax:MiniMax-M3、minimax:MiniMax-M2.7确认字符串在表内且 provider 拼写正确。确认无误后还要确认 runtime 进程能拿到对应 provider 的 API keyModel Selection 文档给出的环境变量是# OpenAI OPENAI_API_KEYsk-... # Anthropic ANTHROPIC_API_KEYsk-ant-... # Google GOOGLE_API_KEY... # MiniMax MINIMAX_API_KEY...如果 key 通过环境变量缺失也可以直接在配置里传apiKeyconst agent new BuiltInAgent({ model: openai:gpt-4.1, apiKey: process.env.MY_OPENAI_KEY, });注意模型配置在 Agent 上CopilotKit 不提供按请求切换模型的托管端点需要换模型就在后端构造 Agent 时改model。排查二给 Agent 一个非空的 prompt常见 issue 文档指出的第二类原因是Built-in Agent 的prompt为空而用户消息本身又没有什么可执行的内容Agent 就没有可用的系统指令。按 advanced-configuration 的写法在BuiltInAgent配置中显式给出系统提示词const builtInAgent new BuiltInAgent({ model: openai:gpt-5.4-mini, prompt: You are a customer support agent for Acme Corp. Be concise and helpful. Always check the knowledge base before answering., });这里的prompt值用你自己业务的系统指令替换即可关键是它不能为空。改完重启 runtime 后重新发消息如果之前空回复的会话现在能产出内容说明命中的是这条原因。排查三前端工具 handler 是否抛错第三类原因某个前端工具在 handler 中抛错Agent 把空结果当作本轮输出。对应的错误码是tool_handler_failed含义A frontend tool handler threw出自 Error Debugging 的错误码表CodeDescriptionruntime_info_fetch_failedCould not reach the runtimes/infoendpointagent_connect_failedAgent connection (thread setup) failedagent_run_failedAgent run rejected (e.g. network error)agent_run_failed_eventThe agentsonRunFailedsubscriber firedagent_run_error_eventAgent emitted aRUN_ERROReventtool_argument_parse_failedTool call arguments were not valid JSONtool_handler_failedA frontend tool handler threw如果报错的是tool_argument_parse_failed说明工具调用参数不是合法 JSON问题在参数解析而非 handler 本身两种情况的修复方向不同核对错误码后再动手。如何观察到具体是哪一类错误排查需要看到实际错误事件文档给出两条观察手段。本地开发用视觉化错误控制台在 provider 上打开showDevConsole错误会直接显示在界面上import { CopilotKit } from copilotkit/react-core/v2; export default function App() { return ( CopilotKit runtimeUrl/api/copilotkit showDevConsole{true} {/* your app */} /CopilotKit ); }生产环境不建议开 dev console它会把内部错误细节暴露给终端用户改用 v2 API 的onError回调它同时挂在CopilotKit和CopilotChat上不需要publicApiKeyCopilotKit runtimeUrl/api/copilotkit onError{(event) { // event.code — error type (e.g. runtime_info_fetch_failed, agent_run_failed) // event.error — the Error object // event.context — additional context (agentId, toolName, etc.) console.error([CopilotKit ${event.code}], event.error.message); }} App / /CopilotKit;复现一次空消息看event.code模型或网络问题通常对应agent_run_failedAgent run rejected, e.g. network error前端工具抛错对应tool_handler_failedevent.context会带出是哪个工具toolName如果onError什么都没触发优先回到排查一和排查二核对模型字符串与prompt。CopilotChat上还有一层 chat 级别的onError作用域限定在指定 chat 的 Agent且会在 provider 级回调之外额外触发CopilotChat agentIdmy-agent onError{(event) { showToast(Agent error: ${event.error.message}); }} /;限制与后续以上路径针对自托管 runtime 的BuiltInAgent场景空消息只说明这一轮没有产出内容先区分没收到任何错误和收到了具体错误码前者多半是模型字符串或 prompt 问题后者按错误码对号入座。生产构建中保持showDevConsole为 false依赖onError上报。如果模型用的是自定义 AI SDKLanguageModel实例OpenAI 兼容端点、代理、Ollama 等模型字符串检查不适用应直接确认该 provider 的 key 与baseURL配置参考 Model Selection 的 Custom Models 一节。【免费下载链接】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），仅供参考