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 (or publicLicenseKey for SPA), headers, credentials, properties, onError, debug, enableInspector.

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

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

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