runtime

CopilotKit Runtime

@copilotkit/runtime is the server half of CopilotKit: it accepts AG-UI protocol requests, dispatches them to an AbstractAgent (built-in or external), runs the stream through an AgentRunner, and responds as Server-Sent Events.

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 — the three dictionaries you hand to CopilotRuntime

new CopilotRuntime({
  agents, // Record<string, AbstractAgent>     — see wiring-external-agents or built-in-agent
  runner, // AgentRunner (optional)            — see agent-runners
  intelligence, // CopilotKitIntelligence (optional) — see intelligence-mode (auto-wires runner)
  mcpApps, // McpAppsConfig (optional)          — see wiring-mcp-apps-middleware
  a2ui, // A2UIConfig (optional)             — see packages/a2ui-renderer skill
  hooks, // { onRequest, onBeforeHandler }    — see middleware
  beforeRequestMiddleware,
  afterRequestMiddleware, // legacy — see middleware
  transcription, // TranscriptionService (optional)  — see transcription
});

You then mount it:

import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});
export default { fetch: handler };

When to load which reference

Task	Reference
Mounting on any fetch-native server (Cloudflare Workers, Bun, Deno, Vercel Edge, Next.js App Router, React Router v7, TanStack Start) or delegating from Express/Node	references/setup-endpoint.md
Auth / logging / rate-limit / request-scoped guards via hooks.onRequest / hooks.onBeforeHandler (preferred) or legacy beforeRequestMiddleware / afterRequestMiddleware	references/middleware.md
Choosing between InMemoryAgentRunner, SqliteAgentRunner, or a custom subclass — including thread-locking semantics and the runner/Intelligence mutual exclusion	references/agent-runners.md (+ -in-memory.md, -sqlite.md, -custom.md for backend-specific detail)
Enabling durable threads + realtime websocket via CopilotKit Intelligence (a managed service, not self-hostable)	references/intelligence-mode.md
Voice transcription — implementing a TranscriptionService subclass for the /transcribe endpoint	references/transcription.md
Instantiating BuiltInAgent — Simple Mode (classic) or Factory Mode with TanStack AI (preferred AG-UI-compliant default), AI SDK, or custom factory	references/built-in-agent.md (+ -factory-modes.md, -helper-utilities.md, -model-identifiers.md)
Defining server-side tools via defineTool for BuiltInAgent.config.tools (Simple Mode only)	references/server-side-tools.md
Wiring an external agent framework into CopilotRuntime({ agents })	references/wiring-external-agents.md (index) + per-framework refs (wiring-mastra.md, wiring-langgraph.md, wiring-crewai-crews.md, wiring-crewai-flows.md, wiring-pydantic-ai.md, wiring-adk.md, wiring-llamaindex.md, wiring-agno.md, wiring-aws-strands.md, wiring-ms-agent-framework.md, wiring-ag2.md, wiring-a2a.md)
Wiring MCP Apps (runtime-level middleware, not an agent)	references/wiring-mcp-apps-middleware.md

Invariants and gotchas (load-once, before any reference)

• createCopilotRuntimeHandler is the canonical primitive. createCopilotExpressHandler / createCopilotHonoHandler exist but are avoid at all costs — delegate from Express/Hono routes to the fetch primitive instead.
• publicLicenseKey is the canonical provider-side field. publicApiKey is a deprecated alias — expect to see it in legacy code, emit the canonical name in new code.
• Intelligence mode auto-wires IntelligenceAgentRunner. Passing both runner and intelligence to CopilotRuntime is rejected at construction.
• Intelligence mode targets the managed CopilotKit Intelligence service (api.cloud.copilotkit.ai) and is not self-hostable.
• hooks.onRequest runs before beforeRequestMiddleware (hook-based middleware wins for Response short-circuits). beforeRequestMiddleware runs after hooks.onRequest (see fetch-handler.ts:136-147).
• identifyUser (Intelligence) does not forward thrown Response objects — convert to 500. Gate auth rejection in hooks.onRequest, which does forward Responses.
• agents__unsafe_dev_only and selfManagedAgents are dev-only aliases of each other; do not reach for them in production. Either signals that the SPA is in dev mode.

Reading order for a first-time reader

1. setup-endpoint — the primitive.
2. built-in-agent or pick one from wiring-external-agents — the agent.
3. agent-runners — production persistence choice.
4. Optional: middleware, intelligence-mode, server-side-tools, transcription.