OpenParable
Skip to content
← Back to skills

React Core

Development
react-core

React Core is an Agent Skill for development published in the CopilotKit/CopilotKit repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/CopilotKit/CopilotKit/blob/HEAD/packages/react-core/skills/react-core/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/react-core, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

TaskReference
Mount the CopilotKit provider, pick runtimeUrl vs publicLicenseKey, RSC boundary rulesreferences/provider-setup.md
Drop in CopilotChat / CopilotPopup / CopilotSidebar, compose CopilotChatView with slot primitivesreferences/chat-components.md
File / image attachments via useAttachments — drag-drop, click, paste, custom uploadreferences/attachments.md
Client-side debug tooling — showDevConsole, debug prop, lazy-loaded web inspectorreferences/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

  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.