react-core

name: react-core description: > @copilotkit/react-core — mount the CopilotKit provider (from @copilotkit/react-core/v2) 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. type: framework library: copilotkit library_version: "1.56.2" requires: - copilotkit/runtime sources: - "CopilotKit/CopilotKit:packages/react-core/src/v2/providers/CopilotKitProvider.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/index.ts" - "CopilotKit/CopilotKit:packages/react-core/src/v2/components/chat/index.ts" - "CopilotKit/CopilotKit:packages/react-core/src/v2/components/chat/CopilotChat.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/components/chat/CopilotChatView.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/components/CopilotKitInspector.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-agent.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-agent-context.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-capabilities.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-threads.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-frontend-tool.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-render-tool.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-render-tool-call.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-default-render-tool.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-component.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-human-in-the-loop.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-attachments.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-configure-suggestions.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-suggestions.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-render-activity-message.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/hooks/use-render-custom-messages.tsx" - "CopilotKit/CopilotKit:packages/react-core/src/v2/lib/slots.tsx" - "CopilotKit/CopilotKit:packages/core/src/core/core.ts" - "CopilotKit/CopilotKit:packages/core/src/core/agent-registry.ts" - "CopilotKit/CopilotKit:packages/core/src/core/run-handler.ts" - "CopilotKit/CopilotKit:packages/core/src/types.ts"

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, showDevConsole.
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

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

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.