react-core

CopilotKit React Core

@copilotkit/react-core 是 CopilotKit 的 React 前端部分：它挂载 provider， 通过 SSE 以 AG-UI 与 runtime（或在 SPA 模式下直接与 CopilotKit Intelligence）通信，并 为每个交互界面暴露 hooks。

本 SKILL.md 是索引。请阅读 references/ 下与你任务匹配的参考文档——不要试图从本文件中吸收整个包的内容。

心智模型——你组合的三个 shell

1. Provider shell——CopilotKit provider（来自 @copilotkit/react-core/v2）位于或接近根节点（对于 Next.js App Router，位于 "use client" 内）。携带 runtimeUrl（必需）、headers、 credentials、properties、onError、debug、enableInspector。
2. Chat shell——CopilotChat / CopilotPopup / CopilotSidebar，或组合使用 CopilotChatView + slot 原语（CopilotChatInput、CopilotChatMessageView 等）。 所有聊天组件均从 @copilotkit/react-core/v2 提供。CopilotPanel 并不 存在——它是一个常见的幻觉。
3. Hook shell——在 provider 下的任意组件内，调用 useAgent、 useFrontendTool、useRenderTool 等。每个 hook 都接受可选的 { agentId }，用于 按 agent 范围的注册。

何时加载哪个参考

任务	参考
挂载 CopilotKit provider，将 runtimeUrl 指向 runtime，RSC 边界规则	references/provider-setup.md
引入 CopilotChat / CopilotPopup / CopilotSidebar，用插槽原语组合 CopilotChatView	references/chat-components.md
通过 useAttachments 处理文件 / 图片附件 — 拖放、点击、粘贴、自定义上传	references/attachments.md
客户端调试工具 — enableInspector、debug prop、懒加载的 web inspector	references/debug-mode.md
读取 / 订阅 Agent（useAgent）并推送全局上下文（useAgentContext）	references/agent-access.md
基于声明的 Agent 能力对 UI 进行功能门控（useCapabilities）	references/capabilities.md
构建多 Agent UI（每个面板的 useAgent、Agent 作用域工具、key 重新挂载模式）	references/switching-agents.md（+ switching-agents-recipes.md 用于具体布局）
列出 / 重命名 / 归档 / 删除持久化的 Intelligence 线程（useThreads）	references/threads.md（需要 runtime Intelligence 模式）
注册浏览器端工具（useFrontendTool）	references/client-side-tools.md
渲染每个工具的 UI（useRenderTool、useComponent、useDefaultRenderTool、useRenderToolCall）	references/rendering-tool-calls.md
将工具执行置于用户批准之后（useHumanInTheLoop）	references/human-in-the-loop.md
配置动态或静态建议胶囊（useConfigureSuggestions、useSuggestions）	references/suggestions.md
渲染非聊天活动消息（useRenderActivityMessage）	references/rendering-activity-messages.md
在特定消息之前 / 之后注入自定义 UI（useRenderCustomMessages）	references/custom-message-renderers.md

不变量与注意事项（一次性加载，先于任何参考文档）

• runtimeUrl 为必填项；生产环境中若缺少它，提供方会抛出异常。CopilotKit Intelligence 配置在 runtime 上，绝不在提供方上。
• agents__unsafe_dev_only 与 selfManagedAgents 是彼此的开发专用别名。不安全用于生产环境。 受支持的 SPA 路径请参见 packages/a2ui-renderer 或 spa-without-runtime 生命周期技能。
• CopilotPanel 并不存在。v2 聊天组件由 react-core/v2 提供——并非 react-ui（v2 的 react-ui 仅含 CSS）。
• 不存在 useAgents() Hook。请通过 copilotkit.subscribe({ onAgentsChanged }) 发现 Agent。
• useRenderToolCall 是一个解析器（用于自定义聊天界面），不是注册 Hook。请使用 useRenderTool / useComponent / useDefaultRenderTool 进行注册。
• UI 套件检测规则——任何 render 或工具调用 UI 在编写原生 JSX 之前，必须先复用使用方的 shadcn / MUI / Chakra / Ant / Mantine 基础组件。这适用于 client-side-tools、rendering-tool-calls 和 human-in-the-loop。
• 工具调用的 status 值为 camelCase：'inProgress' | 'executing' | 'complete'。进行中的参数为 Partial<T>。
• useHumanInTheLoop 合成的处理函数必须调用 respond(result)（包括拒绝路径），否则 Agent 运行会挂起。在 Executing 状态之外，respond 为 undefined。在 Executing 中途卸载会放弃该次运行。
• 在 Intelligence 模式之外，useThreads 会报错 'Runtime URL is not configured'。
• useAgent 返回 { agent, isReady }。当 isReady 为 false 时，agent 是一个临时替身，会在 /info 解析完成后被替换为真实实例——agent 会改变引用，所有依赖它的 effect 都会重新运行。切勿在以 agent 为键的 effect 内初始化应用状态（关联映射、进行中请求记录）。
• React 的 key 会丢弃其下方的所有状态。key={activeAgent} / key={threadId} 应放在真正拥有该状态的最小子树上——放在布局级 provider 上会静默清除无关的应用状态，而在接入 Intelligence 后，线程 id 会在挂载后异步变化，因此它会在交互中途触发。
• v1 → v2 迁移重命名：useCopilotAction → useFrontendTool + useHumanInTheLoop；imageUploadsEnabled → attachments。请参见 v1-to-v2-migration 生命周期技能。

首次阅读者的阅读顺序

1. provider-setup — 挂载 provider。
2. chat-components — 接入聊天界面。
3. agent-access — 与 Agent 通信。
4. client-side-tools + rendering-tool-calls — 添加工具调用 UI。
5. 根据你的功能需求阅读其他任何内容。