react-core

Original：🇺🇸 English

Translated

@copilotkit/react-core — mount CopilotKitProvider in a Next.js App Router / React Router v7 / TanStack Start / SPA app, drop in CopilotChat/CopilotPopup/CopilotSidebar (v2 chat components ship from react-core/v2 — NOT react-ui, which is CSS-only in v2), access and subscribe to agents with useAgent / useAgentContext / useCapabilities, switch between multiple agents, manage durable Intelligence threads with useThreads, register browser-side tools via useFrontendTool, render tool calls with useRenderTool / useComponent / useDefaultRenderTool, gate execution with useHumanInTheLoop, wire file attachments with useAttachments, configure suggestion pills, and register activity- and custom-message renderers. publicLicenseKey is canonical (publicApiKey is deprecated alias). Load the reference under references/ that matches your task.

4installs

Sourcecopilotkit/copilotkit

Added on2026-06-03

NPX Install

npx skill4agent add copilotkit/copilotkit react-core

SKILL.md Content

View Translation Comparison →

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.

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.

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`

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).

No

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.

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.