react-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CopilotKit React Core

@copilotkit/react-core

is the React frontend half of CopilotKit: it mounts a provider, speaks AG-UI over SSE to a runtime (or directly to CopilotKit Cloud in SPA mode), and exposes hooks for every interaction surface.

This SKILL.md is the index. Read the reference under

references/

that matches your task — do not try to absorb the whole package from this file.

@copilotkit/react-core

是 CopilotKit 的 React 前端部分：它负责挂载 Provider，通过 SSE 与运行时（或在 SPA 模式下直接与 CopilotKit Cloud）进行 AG-UI 通信，并为所有交互场景提供钩子（hooks）。

本 SKILL.md 是索引文档。请根据你的任务阅读

references/

下对应的参考文档，不要试图通过本文档掌握整个包的全部内容。

Mental model — three shells you compose

心智模型——三个可组合的层级

Provider shell —

CopilotKitProvider

at or near the root (inside

"use client"

for Next.js App Router). Carries

runtimeUrl

(or

publicLicenseKey

for SPA),

headers

credentials

properties

onError

debug

showDevConsole

Chat shell —
```
CopilotChat
```
/
```
CopilotPopup
```
/
```
CopilotSidebar
```
or a composed
```
CopilotChatView
```
+ slot primitives (
```
CopilotChatInput
```
,
```
CopilotChatMessageView
```
, etc.). All chat components ship from
```
@copilotkit/react-core/v2
```
. CopilotPanel
does not exist — it's a common hallucination.
Hook shell — inside any component under the provider, call
```
useAgent
```
,
```
useFrontendTool
```
,
```
useRenderTool
```
, etc. Every hook takes optional
```
{ agentId }
```
for agent-scoped registration.

Provider 层级 — 在应用根节点或接近根节点的位置挂载
```
CopilotKitProvider
```
（在 Next.js App Router 中需置于
```
"use client"
```
代码块内）。包含
```
runtimeUrl
```
（SPA 模式下使用
```
publicLicenseKey
```
）、
```
headers
```
、
```
credentials
```
、
```
properties
```
、
```
onError
```
、
```
debug
```
、
```
showDevConsole
```
等配置项。
聊天组件层级 — 使用
```
CopilotChat
```
/
```
CopilotPopup
```
/
```
CopilotSidebar
```
，或组合使用
```
CopilotChatView
```
+ 插槽原语（
```
CopilotChatInput
```
、
```
CopilotChatMessageView
```
等）。所有聊天组件均来自
```
@copilotkit/react-core/v2
```
。CopilotPanel
不存在——这是常见的误解。
钩子层级 — 在 Provider 之下的任何组件中，调用
```
useAgent
```
、
```
useFrontendTool
```
、
```
useRenderTool
```
等钩子。每个钩子都可传入可选的
```
{ agentId }
```
参数，以实现 Agent 范围的注册。

When to load which reference

何时加载对应参考文档

Task	Reference
Mount `CopilotKitProvider` , pick `runtimeUrl` vs `publicLicenseKey` , RSC boundary rules	`references/provider-setup.md`
Drop in `CopilotChat` / `CopilotPopup` / `CopilotSidebar` , compose `CopilotChatView` with slot primitives	`references/chat-components.md`
File / image attachments via `useAttachments` — drag-drop, click, paste, custom upload	`references/attachments.md`
Client-side debug tooling — `showDevConsole` , `debug` prop, lazy-loaded web inspector	`references/debug-mode.md`
Read / subscribe to an agent ( `useAgent` ) and push global context ( `useAgentContext` )	`references/agent-access.md`
Feature-gate UI on declared agent capabilities ( `useCapabilities` )	`references/capabilities.md`
Build a multi-agent UI (per-panel `useAgent` , agent-scoped tools, key-remount pattern)	`references/switching-agents.md` (+ `switching-agents-recipes.md` for concrete layouts)
List / rename / archive / delete durable Intelligence threads ( `useThreads` )	`references/threads.md` (requires runtime Intelligence mode)
Register browser-side tools ( `useFrontendTool` )	`references/client-side-tools.md`
Render per-tool UI ( `useRenderTool` , `useComponent` , `useDefaultRenderTool` , `useRenderToolCall` )	`references/rendering-tool-calls.md`
Gate tool execution behind user approval ( `useHumanInTheLoop` )	`references/human-in-the-loop.md`
Configure dynamic or static suggestion pills ( `useConfigureSuggestions` , `useSuggestions` )	`references/suggestions.md`
Render non-chat activity messages ( `useRenderActivityMessage` )	`references/rendering-activity-messages.md`
Inject custom UI before/after specific messages ( `useRenderCustomMessages` )	`references/custom-message-renderers.md`

任务	参考文档
挂载 `CopilotKitProvider` ，选择 `runtimeUrl` 或 `publicLicenseKey` ，了解 RSC 边界规则	`references/provider-setup.md`
引入 `CopilotChat` / `CopilotPopup` / `CopilotSidebar` ，使用插槽原语组合 `CopilotChatView`	`references/chat-components.md`
通过 `useAttachments` 实现文件/图片附件功能——拖拽、点击、粘贴、自定义上传	`references/attachments.md`
客户端调试工具—— `showDevConsole` 、 `debug` 属性、懒加载的 Web 检查器	`references/debug-mode.md`
读取/订阅 Agent（ `useAgent` ）并推送全局上下文（ `useAgentContext` ）	`references/agent-access.md`
根据已声明的 Agent 能力对 UI 进行功能管控（ `useCapabilities` ）	`references/capabilities.md`
构建多 Agent UI（每个面板使用 `useAgent` 、Agent 范围的工具、键重新挂载模式）	`references/switching-agents.md` （+ `switching-agents-recipes.md` 查看具体布局示例）
列出/重命名/归档/删除持久化智能线程（ `useThreads` ）	`references/threads.md` （需要运行时智能模式）
注册浏览器端工具（ `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`

Invariants and gotchas (load-once, before any reference)

不变规则与常见陷阱（阅读任何参考文档前请先了解）

```
publicLicenseKey
```
is canonical.
```
publicApiKey
```
is a deprecated alias — expect it in legacy code.
```
agents__unsafe_dev_only
```
and
```
selfManagedAgents
```
are dev-only aliases of each other. Not production-safe. See
```
packages/a2ui-renderer
```
or the
```
spa-without-runtime
```
lifecycle skill for the supported SPA path.
```
CopilotPanel
```
does not exist. v2 chat components ship from
```
react-core/v2
```
— not
```
react-ui
```
(v2
```
react-ui
```
is CSS-only).

useAgents()

hook exists. Discover agents via

copilotkit.subscribe({ onAgentsChanged })

```
useRenderToolCall
```
is a resolver (for custom chat surfaces), not a registration hook. Register with
```
useRenderTool
```
/
```
useComponent
```
/
```
useDefaultRenderTool
```
.
UI-kit detection rule — any
```
render
```
or tool-call UI MUST reuse the consumer's shadcn / MUI / Chakra / Ant / Mantine primitives before writing raw JSX. This applies across
```
client-side-tools
```
,
```
rendering-tool-calls
```
, and
```
human-in-the-loop
```
.

Tool-call

status

values are camelCase:

'inProgress' | 'executing' | 'complete'

. In-progress args are

Partial<T>

```
useHumanInTheLoop
```
synthesized handler MUST call
```
respond(result)
```
(including reject paths), otherwise the agent run hangs.
```
respond
```
is
```
undefined
```
outside
```
Executing
```
status. Unmounting mid-Executing abandons the run.

useThreads

errors with

'Runtime URL is not configured'

outside Intelligence mode.

v1 → v2

migration renames:

useCopilotAction

→

useFrontendTool

useHumanInTheLoop

;

imageUploadsEnabled

→

attachments

. See the

v1-to-v2-migration

lifecycle skill.

```
publicLicenseKey
```
是标准配置项。
```
publicApiKey
```
是已废弃的别名——仅会在旧代码中出现。
```
agents__unsafe_dev_only
```
和
```
selfManagedAgents
```
是彼此的开发环境专用别名。不可用于生产环境。如需了解支持的 SPA 路径，请查看
```
packages/a2ui-renderer
```
或
```
spa-without-runtime
```
生命周期技能文档。
```
CopilotPanel
```
不存在。v2 聊天组件来自
```
react-core/v2
```
——而非
```
react-ui
```
（v2 的
```
react-ui
```
仅提供 CSS）。

不存在

useAgents()

钩子。可通过

copilotkit.subscribe({ onAgentsChanged })

发现 Agent。

```
useRenderToolCall
```
是一个解析器（用于自定义聊天界面），不是注册钩子。请使用
```
useRenderTool
```
/
```
useComponent
```
/
```
useDefaultRenderTool
```
进行注册。
UI 套件检测规则——任何
```
render
```
或工具调用 UI 必须优先复用用户的 shadcn / MUI / Chakra / Ant / Mantine 原语，再编写原生 JSX。此规则适用于
```
client-side-tools
```
、
```
rendering-tool-calls
```
和
```
human-in-the-loop
```
相关内容。
工具调用的
```
status
```
值采用小驼峰命名：
```
'inProgress' | 'executing' | 'complete'
```
。进行中的参数为
```
Partial<T>
```
类型。
```
useHumanInTheLoop
```
合成的处理函数必须调用
```
respond(result)
```
（包括拒绝路径），否则 Agent 运行会挂起。仅在
```
Executing
```
状态下
```
respond
```
才会存在。执行过程中卸载组件会终止运行。
在智能模式之外使用
```
useThreads
```
会抛出
```
'Runtime URL is not configured'
```
错误。

v1 → v2 迁移的重命名：

useCopilotAction

→

useFrontendTool

useHumanInTheLoop

；

imageUploadsEnabled

→

attachments

。请查看

v1-to-v2-migration

生命周期技能文档了解详情。

Reading order for a first-time reader

首次阅读的推荐顺序

```
provider-setup
```
— mount the provider.
```
chat-components
```
— wire a chat surface.
```
agent-access
```
— talk to agents.
```
client-side-tools
```
+
```
rendering-tool-calls
```
— add tool-call UI.
Anything else as your feature requires.

```
provider-setup
```
— 挂载 Provider。
```
chat-components
```
— 配置聊天界面。
```
agent-access
```
— 与 Agent 交互。
```
client-side-tools
```
+
```
rendering-tool-calls
```
— 添加工具调用 UI。
根据你的功能需求阅读其他文档。