CopilotKit 用 useSingleEndpoint 报 404 但 /info 正常怎么排查【免费下载链接】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 Runtime 时一个典型的诡异现象是前端设置了useSingleEndpoint聊天请求全部 404但直接请求GET /info却正常返回 200应用看起来像是“连上了”实际每次 run/connect 都失败。根因是前端的传输模式transport与后端 handler 的路由模式不匹配。本文基于 Runtime HTTP endpoints 和 Deploy to any runtime 给出排查路径确认后端模式、让前后端模式一致、再验证路由真正可达。前提你的前端从copilotkit/react-core/v2使用CopilotKit或CopilotKitProvider后端用createCopilotRuntimeHandler、createCopilotExpressHandler、createCopilotHonoHandler等挂载了 Runtime。为什么 /info 正常但业务请求 404浏览器 provider 和 Runtime handler 必须就传输模式达成一致而且不是可互换的Provider 设置useSingleEndpoint传输模式需要的 handler路由形态CopilotKit/CopilotKitProvider省略auto从 Runtime 探测任意跟随 handlerCopilotKit/CopilotKitProvider{true}singlesingle-routeroute.ts仅POSTCopilotKit/CopilotKitProvider{false}restmulti-route[[...slug]]/route.ts4 个 HTTP 动词文档明确警告Pinning the wrong mode 404s silently把useSingleEndpoint{true}发给 multi-route Runtime 时前端发出的 envelope 匹配不到任何路由Runtime 返回 404而GET /info仍然返回 200所以应用“看起来已连接”。Runtime 的 404 错误响应体会直接指明修复方式先看一下响应 body 再动手。反过来multi-route 前端对 single-route Runtime 会在发现阶段失败GET {basePath}/info直接 404。所以“/info正常 业务请求 404”这个组合指向的方向就是前端 pin 成了 single后端实际是 multi。第一步确认后端到底是哪种模式看后端 handler 的创建代码mode参数决定一切省略mode或mode: multi-routemulti-route 模式暴露GET {basePath}/info、POST {basePath}/agent/:agentId/run、POST {basePath}/agent/:agentId/connect、POST {basePath}/agent/:agentId/stop/:threadId、POST {basePath}/transcribe等独立路由。mode: single-route只暴露一个POST {basePath}接受 JSON envelope{ method: agent/run, params: { agentId: default }, body: { ... } }。各 handler 支持的形态模式HandlerMulti-route默认createCopilotRuntimeHandler、createCopilotHonoHandler、createCopilotExpressHandler、createCopilotNodeHandler、createCopilotNodeListenerSingle-route以上任意一个 mode: single-route仅 single-route、无选项copilotRuntimeNextJSAppRouterEndpoint、copilotRuntimeNextJSPagesRouterEndpoint、copilotRuntimeNodeHttpEndpoint、copilotRuntimeNodeExpressEndpoint、copilotRuntimeNestEndpoint注意最后一个类别所有copilotRuntime*Endpoint框架封装内部固定以mode: single-route构建 handler。如果你的后端是 Next.js App Router 这类封装它只会提供单路由——这时前端如果传useSingleEndpoint{false}就会把浏览器指向这些封装根本不提供的 REST 路由。第二步用 curl 确认两种路由的可达性确认后端模式后用 curl 直接验证路由是否存在端口 4000、basePath/api/copilotkit是文档示例值替换成你的实际值multi-route 的/infocurl -s http://localhost:4000/api/copilotkit/info正常应返回描述已注册 agents 的 JSON。如果这一步返回 404说明basePath与请求的 URL 不一致或 handler 没挂载如果是连接错误说明服务没有在该 host/port 监听。single-route 的 info envelopecurl -s http://localhost:4000/api/copilotkit \ -H content-type: application/json \ -d {method:info}single-route 模式下没有GET /info信息要经过 envelope 获取。用这两条命令各打一次就能判定你的 Runtime 实际提供的是哪套路由哪边 200后端就是哪种模式。修复让传输模式一致最短路径是删掉useSingleEndpointimport { CopilotKitProvider } from copilotkit/react-core/v2; CopilotKitProvider runtimeUrl/api/copilotkit YourApp / /CopilotKitProvider;自 1.70.2 起CopilotKit和CopilotKitProvider对省略useSingleEndpoint的处理一致传输模式为auto客户端探测 Runtime 并匹配它实际提供的模式。只有在你明确想跳过探测时才 pinuseSingleEndpointpin 了就必须与 handler 模式严格一致// 后端 multi-route 时 CopilotKit runtimeUrl/api/copilotkit useSingleEndpoint{false} // 后端 single-route 时 CopilotKit runtimeUrl/api/copilotkit useSingleEndpoint一个版本边界要留意1.70.2 之前v1 的CopilotKit包装器内部把该 flag 固定为true即省略属性也会选择 single-route 传输对 multi-route handler 就 404。如果你用的是这些旧版本且不想升级就显式传useSingleEndpoint{false}前提是后端为 multi-route。另一个容易踩的坑后端 Runtime 的导入必须走/v2入口copilotkit/runtime/v2Express 适配器为copilotkit/runtime/v2/express。从包根copilotkit/runtime导入拿到的是 v1 表面它的CopilotRuntime不提供这些路由而症状同样是“路由 404”而不是导入报错——如果你确认过模式匹配却依然全 404检查一下导入路径。验证修复是否生效修复后重启/重新加载应用按后端模式验证对应路由multi-routecurl -s http://localhost:4000/api/copilotkit/info返回 agent 列表 JSON。single-route发送上面的{method:info}envelope响应应包含singleRoute段如singleRoute: { resourceOperations: true, ... }文档示例具体字段取决于你的 Runtime 配置。前端侧可以用onError回调观察错误码变化runtime_info_fetch_failed表示/info都不可达agent_connect_failed表示线程连接失败来源Error Debugging。模式修复后这两个代码不应再出现聊天首条消息能正常返回。相关入口连接 404 的另一类常见原因agentId 未注册、connect()早于run()见 Common Issues 的 “Connect route returns 404 on a fresh thread” 一节它和本文的“模式不匹配”是不同根因前者 Runtime 会返回{error:Agent not found, ...}。各框架完整挂载示例Express、Hono、Bun、Deno、Cloudflare Workers见 Deploy to any runtime其中说明 multi-route 需要挂载完整basePath子树并放行GET、POST、PATCH、DELETEsingle-route 只需一个POST精确路径。Angular 侧不存在这个问题provideCopilotKit从/info自动发现传输模式没有useSingleEndpoint选项。【免费下载链接】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 用 useSingleEndpoint 报 404 但 /info 正常怎么排查？
CopilotKit 用 useSingleEndpoint 报 404 但 /info 正常怎么排查【免费下载链接】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 Runtime 时一个典型的诡异现象是前端设置了useSingleEndpoint聊天请求全部 404但直接请求GET /info却正常返回 200应用看起来像是“连上了”实际每次 run/connect 都失败。根因是前端的传输模式transport与后端 handler 的路由模式不匹配。本文基于 Runtime HTTP endpoints 和 Deploy to any runtime 给出排查路径确认后端模式、让前后端模式一致、再验证路由真正可达。前提你的前端从copilotkit/react-core/v2使用CopilotKit或CopilotKitProvider后端用createCopilotRuntimeHandler、createCopilotExpressHandler、createCopilotHonoHandler等挂载了 Runtime。为什么 /info 正常但业务请求 404浏览器 provider 和 Runtime handler 必须就传输模式达成一致而且不是可互换的Provider 设置useSingleEndpoint传输模式需要的 handler路由形态CopilotKit/CopilotKitProvider省略auto从 Runtime 探测任意跟随 handlerCopilotKit/CopilotKitProvider{true}singlesingle-routeroute.ts仅POSTCopilotKit/CopilotKitProvider{false}restmulti-route[[...slug]]/route.ts4 个 HTTP 动词文档明确警告Pinning the wrong mode 404s silently把useSingleEndpoint{true}发给 multi-route Runtime 时前端发出的 envelope 匹配不到任何路由Runtime 返回 404而GET /info仍然返回 200所以应用“看起来已连接”。Runtime 的 404 错误响应体会直接指明修复方式先看一下响应 body 再动手。反过来multi-route 前端对 single-route Runtime 会在发现阶段失败GET {basePath}/info直接 404。所以“/info正常 业务请求 404”这个组合指向的方向就是前端 pin 成了 single后端实际是 multi。第一步确认后端到底是哪种模式看后端 handler 的创建代码mode参数决定一切省略mode或mode: multi-routemulti-route 模式暴露GET {basePath}/info、POST {basePath}/agent/:agentId/run、POST {basePath}/agent/:agentId/connect、POST {basePath}/agent/:agentId/stop/:threadId、POST {basePath}/transcribe等独立路由。mode: single-route只暴露一个POST {basePath}接受 JSON envelope{ method: agent/run, params: { agentId: default }, body: { ... } }。各 handler 支持的形态模式HandlerMulti-route默认createCopilotRuntimeHandler、createCopilotHonoHandler、createCopilotExpressHandler、createCopilotNodeHandler、createCopilotNodeListenerSingle-route以上任意一个 mode: single-route仅 single-route、无选项copilotRuntimeNextJSAppRouterEndpoint、copilotRuntimeNextJSPagesRouterEndpoint、copilotRuntimeNodeHttpEndpoint、copilotRuntimeNodeExpressEndpoint、copilotRuntimeNestEndpoint注意最后一个类别所有copilotRuntime*Endpoint框架封装内部固定以mode: single-route构建 handler。如果你的后端是 Next.js App Router 这类封装它只会提供单路由——这时前端如果传useSingleEndpoint{false}就会把浏览器指向这些封装根本不提供的 REST 路由。第二步用 curl 确认两种路由的可达性确认后端模式后用 curl 直接验证路由是否存在端口 4000、basePath/api/copilotkit是文档示例值替换成你的实际值multi-route 的/infocurl -s http://localhost:4000/api/copilotkit/info正常应返回描述已注册 agents 的 JSON。如果这一步返回 404说明basePath与请求的 URL 不一致或 handler 没挂载如果是连接错误说明服务没有在该 host/port 监听。single-route 的 info envelopecurl -s http://localhost:4000/api/copilotkit \ -H content-type: application/json \ -d {method:info}single-route 模式下没有GET /info信息要经过 envelope 获取。用这两条命令各打一次就能判定你的 Runtime 实际提供的是哪套路由哪边 200后端就是哪种模式。修复让传输模式一致最短路径是删掉useSingleEndpointimport { CopilotKitProvider } from copilotkit/react-core/v2; CopilotKitProvider runtimeUrl/api/copilotkit YourApp / /CopilotKitProvider;自 1.70.2 起CopilotKit和CopilotKitProvider对省略useSingleEndpoint的处理一致传输模式为auto客户端探测 Runtime 并匹配它实际提供的模式。只有在你明确想跳过探测时才 pinuseSingleEndpointpin 了就必须与 handler 模式严格一致// 后端 multi-route 时 CopilotKit runtimeUrl/api/copilotkit useSingleEndpoint{false} // 后端 single-route 时 CopilotKit runtimeUrl/api/copilotkit useSingleEndpoint一个版本边界要留意1.70.2 之前v1 的CopilotKit包装器内部把该 flag 固定为true即省略属性也会选择 single-route 传输对 multi-route handler 就 404。如果你用的是这些旧版本且不想升级就显式传useSingleEndpoint{false}前提是后端为 multi-route。另一个容易踩的坑后端 Runtime 的导入必须走/v2入口copilotkit/runtime/v2Express 适配器为copilotkit/runtime/v2/express。从包根copilotkit/runtime导入拿到的是 v1 表面它的CopilotRuntime不提供这些路由而症状同样是“路由 404”而不是导入报错——如果你确认过模式匹配却依然全 404检查一下导入路径。验证修复是否生效修复后重启/重新加载应用按后端模式验证对应路由multi-routecurl -s http://localhost:4000/api/copilotkit/info返回 agent 列表 JSON。single-route发送上面的{method:info}envelope响应应包含singleRoute段如singleRoute: { resourceOperations: true, ... }文档示例具体字段取决于你的 Runtime 配置。前端侧可以用onError回调观察错误码变化runtime_info_fetch_failed表示/info都不可达agent_connect_failed表示线程连接失败来源Error Debugging。模式修复后这两个代码不应再出现聊天首条消息能正常返回。相关入口连接 404 的另一类常见原因agentId 未注册、connect()早于run()见 Common Issues 的 “Connect route returns 404 on a fresh thread” 一节它和本文的“模式不匹配”是不同根因前者 Runtime 会返回{error:Agent not found, ...}。各框架完整挂载示例Express、Hono、Bun、Deno、Cloudflare Workers见 Deploy to any runtime其中说明 multi-route 需要挂载完整basePath子树并放行GET、POST、PATCH、DELETEsingle-route 只需一个POST精确路径。Angular 侧不存在这个问题provideCopilotKit从/info自动发现传输模式没有useSingleEndpoint选项。【免费下载链接】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），仅供参考
 详解：自动发现 WSL 发行版并定制默认行为)
