react-core
@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.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- react-core
- type
- framework
- library
- copilotkit
- 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" ]
- requires
- [ "copilotkit/runtime" ]
- 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.
- library_version
- 1.70.3
02 资源文件 15
- 参考文档references/agent-access.md9.1 KB
- 参考文档references/attachments.md7.7 KB
- 参考文档references/capabilities.md3.3 KB
- 参考文档references/chat-components.md5.2 KB
- 参考文档references/client-side-tools.md8.2 KB
- 参考文档references/custom-message-renderers.md6.3 KB
- 参考文档references/debug-mode.md3.5 KB
- 参考文档references/human-in-the-loop.md7.9 KB
- 参考文档references/provider-setup.md10.4 KB
- 参考文档references/rendering-activity-messages.md5.4 KB
- 参考文档references/rendering-tool-calls.md8.5 KB
- 参考文档references/suggestions.md4.9 KB
- 参考文档references/switching-agents-recipes.md4.7 KB
- 参考文档references/switching-agents.md6.0 KB
- 参考文档references/threads.md7.7 KB
03 SKILL.md 正文
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
- Provider shell — the
CopilotKitprovider (from@copilotkit/react-core/v2) at or near the root (inside"use client"for Next.js App Router). CarriesruntimeUrl(orpublicLicenseKeyfor SPA),headers,credentials,properties,onError,debug,enableInspector. - Chat shell —
CopilotChat/CopilotPopup/CopilotSidebaror a composedCopilotChatView+ slot primitives (CopilotChatInput,CopilotChatMessageView, etc.). All chat components ship from@copilotkit/react-core/v2.CopilotPaneldoes 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 the CopilotKit provider, 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 — 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)
publicLicenseKeyis canonical.publicApiKeyis a deprecated alias — expect it in legacy code.agents__unsafe_dev_onlyandselfManagedAgentsare dev-only aliases of each other. Not production-safe. Seepackages/a2ui-rendereror thespa-without-runtimelifecycle skill for the supported SPA path.CopilotPaneldoes not exist. v2 chat components ship fromreact-core/v2— notreact-ui(v2react-uiis CSS-only).- No
useAgents()hook exists. Discover agents viacopilotkit.subscribe({ onAgentsChanged }). useRenderToolCallis a resolver (for custom chat surfaces), not a registration hook. Register withuseRenderTool/useComponent/useDefaultRenderTool.- UI-kit detection rule — any
renderor tool-call UI MUST reuse the consumer's shadcn / MUI / Chakra / Ant / Mantine primitives before writing raw JSX. This applies acrossclient-side-tools,rendering-tool-calls, andhuman-in-the-loop. - Tool-call
statusvalues are camelCase:'inProgress' | 'executing' | 'complete'. In-progress args arePartial<T>. useHumanInTheLoopsynthesized handler MUST callrespond(result)(including reject paths), otherwise the agent run hangs.respondisundefinedoutsideExecutingstatus. Unmounting mid-Executing abandons the run.useThreadserrors with'Runtime URL is not configured'outside Intelligence mode.useAgentreturns{ agent, isReady }. WhileisReadyisfalse,agentis a provisional stand-in that is swapped for the real instance when/inforesolves —agentchanges reference and every effect depending on it re-runs. Never initialize app state (correlation maps, in-flight request records) inside an effect keyed onagent.- A React
keydiscards 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 → v2migration renames:useCopilotAction→useFrontendTool+useHumanInTheLoop;imageUploadsEnabled→attachments. See thev1-to-v2-migrationlifecycle 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.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.