CopilotKit React Provider 安装与配置完全指南Transport 协商、鉴权模式与常见陷阱【免费下载链接】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/CopilotKitCopilotKitProvider从copilotkit/react-core/v2导入是 CopilotKit 在 React 应用中的根组件所有 hooksuseAgent、useFrontendTool、useRenderTool等与聊天组件CopilotChat、CopilotPopup、CopilotSidebar都必须挂载在它内部。本指南将带你完成 Provider 的挂载位置选型、Transport传输模式协商机制、三种典型框架的接入姿势以及鉴权头、全局错误处理、运行期属性共享等核心模式最后汇总六个开发者最容易踩的坑及其源码级成因读完即可在生产环境中正确落地 CopilotKit。选择正确的 Provider 组件v1/v2 兼容桥还是纯净 ProviderCopilotKit 的 React 侧存在两个容易混淆的入口CopilotKit来自copilotkit/react-core/v2官方推荐。它是 v1 与 v2 之间的兼容桥同时是CopilotKitProvider的超集。从源码可以看到该组件在 packages/react-core/src/v1-deprecated/components/copilot-provider/copilotkit.tsx 中直接复用了 v2 的CopilotKitProvider其内部CopilotKitV2Provider即来自../../../v2再包上 v1 的ThreadsProvider、错误边界与 Toast 体系为旧代码提供无缝迁移路径。CopilotKitProvider同样从copilotkit/react-core/v2导出纯粹的 v2 实现不需要 v1 兼容层时的更轻选择。其完整实现位于 packages/react-core/src/v2/providers/CopilotKitProvider.tsx。务必避免从包根路径copilotkit/react-core导入CopilotKit。v2 入口文件 packages/react-core/src/v2/index.ts 的头部声明了use client并在末尾以export { CopilotKit } from ../v1-deprecated/components/copilot-provider/copilotkit显式 re-export 该兼容组件而包根导出的是遗留 v1 入口它与 v2 的 hooks 和组件不兼容。判断当前代码属于哪个版本最直接的方法是看导入子路径凡是copilotkit/react-core/v2都是 v2包根导入都是 v1。从包配置可以确认导出矩阵packages/react-core/package.json 中exports字段定义了.v1 主入口与./v2v2 子路径两条独立通道./v2/styles.css单独映射到./dist/v2/index.css这也解释了为什么样式需要单独导入。Transport 机制默认协商按需固定多数场景下你不需要显式配置传输模式。两个 Provider 默认都让useSingleEndpoint保持未设置状态客户端随后自动协商先探测GET {runtimeUrl}/info失败则回退到单路由single-route的POST封套。这种「协商」模式既能对接多路由 handler所有createCopilot*handler 的默认形态也能对接单路由 handler。从源码看useSingleEndpoint三态映射关系非常清晰。packages/react-core/src/v2/providers/CopilotKitProvider.tsx 的构造函数参数与提交期 effect 中都有同一段映射逻辑useSingleEndpoint true → runtimeTransport: single useSingleEndpoint false → runtimeTransport: rest useSingleEndpoint 未设置 → runtimeTransport: auto仅在需要刻意固定某一种模式时才设置该 propuseSingleEndpointTransport 模式前置要求省略推荐协商auto兼容任一 handler 模式{true}单路由POST封套handler 以mode: single-route挂载{false}多路由 REST 路由handler 使用默认多路由模式固定错误模式是经典的首跑失败场景把单路由封套发给多路由运行时请求匹配不到任何路由运行时返回 404而GET /info依旧返回 200于是应用看起来「已连接」实则不可用。遇到这种情况请直接去掉该 prop而不是猜测另一个值——让协商逻辑自行决定。底层行为有测试保障packages/react-core/src/v2/providers/tests/CopilotKitProvider.test.tsx 中的useSingleEndpoint → runtimeTransport mapping用例逐一断言了三态映射并验证了useSingleEndpointprop 变化时 transport 会随之更新packages/react-core/src/v1-deprecated/components/copilot-provider/tests/copilotkit-transport-default.test.tsx 则验证了省略 prop 时runtimeTransport默认等于auto。源码层面的/info探测细节/info探测并非在组件构造时发起。为避免 React 并发渲染、Suspense 与 StrictMode 下的重复请求构造器一旦放在 render 阶段执行网络请求就会随每次被丢弃的渲染重复触发Provider 以deferInitialConnection: true延迟初始化连接真正的connect()在提交期 effect 中幂等地调用——StrictMode 的双重 effect 与无关 prop 变化导致的 effect 重跑都会折叠为一次/info请求源码注释标注了 issue #5801。这一点在 packages/core/src/tests/core-defer-runtime-connection.test.ts 中有完整验证connect()恰好触发一次/info请求重复调用不会多发被丢弃的孤儿 core 则一次请求都不会发出。三种典型框架的安装姿势Next.js App Router以及任何基于 RSC 的框架copilotkit/react-core/v2以use client开头见 packages/react-core/src/v2/index.ts 第 1 行因此 Provider必须从客户端组件挂载而不是服务端组件。最干净的做法是创建一个专用的客户端providers.tsx// app/providers.tsx use client; import { CopilotKit } from copilotkit/react-core/v2; import copilotkit/react-core/v2/styles.css; export function Providers({ children }: { children: React.ReactNode }) { return ( CopilotKit runtimeUrl/api/copilotkit credentialsinclude onError{({ code, error, context }) { console.error([copilotkit], code, error, context); }} {children} /CopilotKit ); }credentialsinclude用于跨源请求携带 HTTP-only cookie在服务端组件中这一能力天然缺失这也是必须在客户端挂载的另一个原因。对于会话期间会变化的鉴权头轮换的 bearer token、刷新的 cookie请采用下文「轮换鉴权 token 的稳定 headers」模式不要写useMemo(() ({ Authorization: ... }), [])——空依赖数组会在挂载时捕获一次 token之后再也不会刷新。然后在服务端 layout 中导入它// app/layout.tsx — server component import { Providers } from ./providers; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( html langen body Providers{children}/Providers /body /html ); }Vite / React Router v7 / SPA纯客户端应用无需use client指令直接在最外层组件挂载import { CopilotKit } from copilotkit/react-core/v2; import copilotkit/react-core/v2/styles.css; export function App({ children }: { children: React.ReactNode }) { return CopilotKit runtimeUrl/api/copilotkit{children}/CopilotKit; }使用 CopilotKit Intelligence 的纯 SPA无自托管运行时不部署自有 runtime 时传入publicLicenseKey即可走 CopilotKit Intelligence 云服务CopilotKit publicLicenseKeyck_pub_... /publicLicenseKey是纯客户端 bundle 运行 CopilotKit 的标准 prop。publicApiKey是被废弃的别名两者解析为同一值——旧代码中可以接受它但新代码一律写publicLicenseKey。源码中的解析顺序是publicApiKey ?? publicLicenseKey见 packages/react-core/src/v2/providers/CopilotKitProvider.tsx 的resolvedPublicKey因此当两个 prop 都传入时publicApiKey会优先建议永远不要同时使用。注意当runtimeUrl与 license key 都未提供时Provider 在开发环境下console.warn、生产环境下直接抛错Missing required prop: runtimeUrl or publicApiKey or publicLicenseKey。当提供了publicLicenseKey但未提供runtimeUrl时请求会落到常量COPILOT_CLOUD_CHAT_URLhttps://api.cloud.copilotkit.ai/copilotkit/v1并自动将 license key 注入X-CopilotCloud-Public-Api-Key请求头常量HEADER_NAME——前提是该头未被显式传入的 headers 覆盖。核心模式轮换鉴权 token 的稳定 headers对于会话期间会变化的 token应使用命令式 setter 而不是带着新headersprop 重新渲染 Provideruse client; import { useCopilotKit } from copilotkit/react-core/v2; import { useEffect } from react; export function AuthTokenSync({ token }: { token: string | null }) { const { copilotkit } useCopilotKit(); useEffect(() { // setHeaders 是覆盖overwrite而非合并merge——先展开当前 headers // 让别处设置的条目如 public license key得以保留。null 值会清除该头 // 因此登出时传 Authorization: null 会移除该头而不是发送一个空值。 copilotkit.setHeaders({ ...copilotkit.headers, Authorization: token ? Bearer ${token} : null, }); }, [copilotkit, token]); return null; }关键语义setHeaders接受null/undefined值并丢弃对应 key因此Authorization: null是官方支持的清头方式设为空字符串则会让该头以空值继续存在。不要同时通过headersprop 与命令式setHeaders设置同一个头。每当任一 Provider prop 变化Provider 都会用 prop 派生出的 headers 调用一次setHeaders——这是全量覆盖会丢掉所有命令式设置的 headers而不只是 prop 也定义了的 key见 packages/react-core/src/v2/providers/CopilotKitProvider.tsx 的提交期 effect 中copilotkit.setHeaders(mergedHeaders)。因此轮换值如 auth token应完全排除在headersprop 之外只通过setHeaders管理。全局错误处理onError会针对 core 抛出的每一个CopilotKitCoreErrorCode触发避免 UI 在 runtime URL 配错或 CORS 配置错误时卡死在「connecting...」状态CopilotKit runtimeUrl/api/copilotkit onError{({ code, error, context }) { telemetry.capture({ code, message: error.message, context }); }} /回调签名包含三个字段errorError实例、codeCopilotKitCoreErrorCode与context任意结构化上下文Recordstring, any。从 Provider 源码看未提供onError时 core 错误会退化为console.error[CopilotKit] Error (${event.code}): ...连接失败的可见性会大打折扣。每次 run 共享应用属性properties会在每次 agent run 时流向 runtime适合传递租户 ID、特性开关或任何服务端需要的数据const properties useMemo( () ({ tenantId: user.tenantId, locale: user.locale }), [user.tenantId, user.locale], ); CopilotKit runtimeUrl/api/copilotkit properties{properties} /;注意保持properties引用稳定useMemo否则每次渲染都会触发 Provider 内部状态的 diff 波动。常见错误清单六个高频陷阱CRITICAL — 从 Server Component 挂载 Provider错误// app/page.tsx (server component — no use client) import { CopilotKit } from copilotkit/react-core/v2; export default function Page() { return CopilotKit runtimeUrl/api/copilotkit.../CopilotKit; }正确// app/providers.tsx use client; import { CopilotKit } from copilotkit/react-core/v2; export function Providers({ children }: { children: React.ReactNode }) { return CopilotKit runtimeUrl/api/copilotkit{children}/CopilotKit; } // app/layout.tsx imports Providers.copilotkit/react-core/v2以use client开头packages/react-core/src/v2/index.ts 第 1 行。从服务端组件导入会静默剥离交互性——Provider 照常渲染但所有 hooks 都不会接线表现为「界面在、功能全无」且无任何报错。CRITICAL — 生产环境使用agents__unsafe_dev_only或selfManagedAgents错误CopilotKit agents__unsafe_dev_only{{ default: new BuiltInAgent({ apiKey: process.env.OPENAI_KEY! }), }} / // 或别名同一机制 CopilotKit selfManagedAgents{{ default: new BuiltInAgent({ apiKey: ... }) }} /正确// 通过 runtime 路由密钥留在服务端 CopilotKit runtimeUrl/api/copilotkit / // 或纯 SPA 使用 CopilotKit Intelligence CopilotKit publicLicenseKeyck_pub_... /两个 prop 是同一个仅限开发环境的机制的别名会把内嵌凭据直接打包进浏览器 bundle。从源码看Provider 内部把二者合并为mergedAgents{ ...agents, ...selfManagedAgents }后传给 core且当使用了selfManagedAgents而没有publicLicenseKey时无论开发还是生产环境都会发出警示这是 Enterprise Intelligence 层的机制此处仅作客户端告警提示并不强制拦截。任何情况下都不要在生产 agents 中使用它们。HIGH — 内联对象 prop 每次渲染重建错误CopilotKit runtimeUrl/api/copilotkit headers{{ Authorization: Bearer ${token} }} properties{{ tenantId: user.tenantId }} /正确const headers useMemo(() ({ Authorization: Bearer ${token} }), [token]); const properties useMemo( () ({ tenantId: user.tenantId }), [user.tenantId], ); CopilotKit runtimeUrl/api/copilotkit headers{headers} properties{properties} /;每次渲染产生的新对象引用会让 Provider 反复 diff 内部状态可能引发 tool/renderer 注册抖动。Provider 内部的useStableArrayProp还会在数组类 proprenderToolCalls、frontendTools、humanInTheLoop等的形状未做记忆化就变化时console.error告警提示应改用useFrontendTool等 hook 动态增删工具。Provider 源码中还用Object.freeze定义了EMPTY_HEADERS、EMPTY_PROPERTIES、EMPTY_AGENTS三个冻结常量作为默认值确保调用方省略对象 prop 时 effect 不会因引用变化而重复执行——这从反面印证了稳定引用的重要性。HIGH — 缺少onError导致用户卡在「connecting...」错误CopilotKit runtimeUrl/api/copilotkit /正确CopilotKit runtimeUrl/api/copilotkit onError{({ code, error, context }) { telemetry.capture({ code, error, context }); }} /没有onError时连接失败runtime URL 错误、CORS、网络问题会让 Provider 停留在临时状态ProxiedCopilotRuntimeAgent实例永远无法 resolve聊天 UI 会永远显示「connecting...」用户看不到真实错误。Provider 内部通过onErrorRef转发 core 的onError事件未提供回调时退化为console.error——事件不会被吞掉但可观测性很差。HIGH — 新代码里写publicApiKey错误CopilotKit publicApiKeyck_pub_... /正确CopilotKit publicLicenseKeyck_pub_... /publicApiKey作为废弃别名仍可工作但publicLicenseKey才是标准名。解析逻辑为publicLicenseKey || publicApiKeyv1 兼容层 packages/react-core/src/v1-deprecated/components/copilot-provider/copilotkit.tsx 中同样有props.publicLicenseKey || props.publicApiKey新代码一律写标准形式。MEDIUM — Provider 挂在使用它的 layout 之下错误html body Header{/* Header uses useFrontendTool internally */}/Header CopilotKit{children}/CopilotKit /body /html正确html body CopilotKit Header / {children} /CopilotKit /body /html任何调用useCopilotKit、useFrontendTool、useAgent或其他 CopilotKit hook 的组件都必须是CopilotKitProvider 的后代。把 Provider 放在消费方旁边或之下会在挂载时直接抛错。Provider 通过三层 contextSandboxFunctionsContext、CopilotKitContext、LicenseContext向子树提供能力并以CopilotKitAgentIdContext发布 provider 级默认agentId——这是 v2 中替代 v1CopilotKit agent...prop 的方式默认值为default被所有未显式指定agentId的CopilotChat继承。其他值得关注的 Provider prop除了上述核心 propCopilotKitProviderProps 还定义了以下常用能力便于你按需选用headers支持静态对象或函数两种形式Recordstring, string | (() Recordstring, string)函数形式会在每次请求前求值。agentIdprovider 级默认 agent替代 v1 的agentprop默认default。enableInspector开发环境默认启用 Inspector生产与服务端渲染时始终关闭showDevConsole已废弃不再控制 Inspector。frontendTools/renderToolCalls/renderActivityMessages/renderCustomMessages静态注册前端工具与各类消息渲染器均要求稳定数组引用动态增删请用useFrontendTool等 hook。humanInTheLoop静态注册 human-in-the-loop 工具动态请用useHumanInTheLoopProvider 会为每个工具生成 promise 式 handler 并在执行中暂停等待respond。openGenerativeUI启用 LLM 生成的沙箱 UIgenerateSandboxedUi工具可传入sandboxFunctionsiframe 内通过await Websandbox.connection.remote.fn(args)调用与designSkill默认提供一套 shadcn/ui 风格设计准则。a2uiA2UI 渲染器配置运行时上报a2ui配置后自动激活提供theme、catalog、loadingComponent、includeSchema、recovery等选项。defaultThrottleMsuseAgent因OnMessagesChanged触发重渲染时的默认节流间隔毫秒作为 hooks 与聊天组件未显式指定throttleMs时的兜底值。debug开启客户端事件管道的调试日志DebugConfig。licenseTokenCopilotKit Intelligence 离线验证的签名 license token需从 CopilotKit 运营后台获取。小结正确接入 CopilotKit React Provider 的关键决策可以浓缩为四条从copilotkit/react-core/v2导入包根是 v1、挂在组件树根部且必须是客户端组件、useSingleEndpoint默认留空交给自动协商、轮换 token 只走setHeaders而不用headersprop。配合onError全局兜底与稳定的properties引用绝大多数「连不上」「卡 loading」「token 不刷新」的问题都能在几分钟内定位。若想深入底层机制建议继续阅读 CopilotKitProvider 源码、v2 入口与 v1 兼容桥 以及 transport 映射与/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考