copilotkit

Upgrade a single-agent CopilotKit v2 app to multi-agent with per-panel useAgent({ agentId }), agent-scoped tools / renderers / context, key-remount when swapping agents in one chat slot, and thread-switcher UIs via useThreads. No useAgents() hook exists — discover the agent list via copilotkit.subscribe({ onAgentsChanged }). Load when moving from one agent to many, when agentId filters start appearing on tools, or when building a side-by-side multi-panel chat.

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.

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.