react-core

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 Intelligence 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

1. Provider shell — the CopilotKit provider (from @copilotkit/react-core/v2) at or near the root (inside "use client" for Next.js App Router). Carries runtimeUrl (required), headers, credentials, properties, onError, debug, enableInspector.
2. 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.
3. 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 the CopilotKit provider, point runtimeUrl at the runtime, 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 — enableInspector, 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)

• runtimeUrl is required; the provider throws in production without it. CopilotKit Intelligence is configured on the runtime, never on the provider.
• 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.
• useAgent returns { agent, isReady }. While isReady is false, agent is a provisional stand-in that is swapped for the real instance when /info resolves — agent changes reference and every effect depending on it re-runs. Never initialize app state (correlation maps, in-flight request records) inside an effect keyed on agent.
• A React key discards all state below it. key={activeAgent} / key={threadId} belongs on the smallest subtree that genuinely owns that state — on a layout-level provider it silently wipes unrelated app state, and with Intelligence wired the thread id changes asynchronously after mount, so it fires mid-interaction.
• v1 → v2 migration renames: useCopilotAction → useFrontendTool + useHumanInTheLoop; imageUploadsEnabled → attachments. See the v1-to-v2-migration lifecycle skill.

Reading order for a first-time reader

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