copilotkit

End-to-end debugging for CopilotKit v2 — CopilotKitCoreErrorCode catalog (17 snake_case codes including runtime_info_fetch_failed, agent_thread_locked, agent_run_failed, tool_handler_failed, etc.), TranscriptionErrorCode catalog (9 codes), AG-UI SSE event tracing, web inspector lazy-loading, onError wiring on both CopilotKitProvider and CopilotChat, server-first debug discipline, and deprecated-alias → canonical cheat sheet. v1 CopilotKitErrorCode (SCREAMING_SNAKE) is kept for migration context only. Load when diagnosing a CopilotKit runtime or client failure, when interpreting an error code, when tracing missing events, or when wiring onError handlers.

Pre-deploy checklist for CopilotKit v2 apps — persistent AgentRunner (not InMemory) behind horizontal scaling, CORS, showDevConsole off, debug off, credentials:'include' for cookie auth, env-sourced secrets on edge runtimes, publicApiKey / licenseToken, dev-only-prop audit (agents__unsafe_dev_only, selfManagedAgents). Pointer skill — does NOT teach auth, rate-limit, or observability (those are server- framework concerns wired via the middleware skill). Load before any first production deploy of a CopilotKit v2 app.

End-to-end quickstart for CopilotKit v2 — scaffold, mount the runtime, mount the provider, render chat, add the first tool. Canonical framework order is React Router v7 framework mode → TanStack Start → Next.js App Router, plus an SPA-without-runtime branch. Every branch uses createCopilotRuntimeHandler (the fetch primitive) — avoid createCopilotExpressHandler / createCopilotHonoHandler. Factory Mode BuiltInAgent with TanStack AI is the preferred default. Load when bootstrapping a new CopilotKit v2 app, adding runtime to an existing React app, or deciding which framework branch to wire.

Render A2UI (Agent-to-UI declarative surfaces) in CopilotKit v2. Enable the runtime via CopilotRuntime({ a2ui: {...} }), then enable the provider via <CopilotKitProvider a2ui={{ theme }}>. Auto-activates via /info — do NOT manually pass renderActivityMessages. createA2UIMessageRenderer ships from @copilotkit/react-core/v2; low-level primitives (A2UIProvider, A2UIRenderer, createCatalog) ship from @copilotkit/a2ui-renderer. Covers theme customization, createSurface dedup, action-bridge try/finally cleanup. Load when an agent emits A2UI operations (createSurface / updateComponents / updateDataModel), when wiring a2ui on CopilotRuntime, or when styling A2UI surfaces.

@copilotkit/react-core — mount CopilotKitProvider 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.