/runtime

name: runtime
description: >
  @copilotkit/runtime — mount a fetch-native CopilotRuntime on any JS server, wire
  middleware, pick an AgentRunner, instantiate BuiltInAgent (Factory Mode with TanStack AI
  is the preferred default) or plug in any of 12 external agent frameworks (Mastra,
  LangGraph, CrewAI Crews/Flows, PydanticAI, ADK, LlamaIndex, Agno, AWS Strands, MS Agent
  Framework, AG2, A2A), enable Intelligence mode for durable threads + websocket,
  register server-side tools via defineTool, and wire voice transcription. Uses the
  fetch-based createCopilotRuntimeHandler primitive — the Express/Hono adapters are
  discouraged. Load the reference under references/ that matches your task.
type: core
library: copilotkit
library_version: "1.56.2"
requires: []
sources:
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/core/fetch-handler.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/core/runtime.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/core/hooks.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/core/middleware.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/runner/agent-runner.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/runner/in-memory.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/runner/intelligence.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/intelligence-platform/client.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/transcription-service/transcription-service.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/handlers/handle-transcribe.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/agent/index.ts"
  - "CopilotKit/CopilotKit:packages/runtime/src/agent/converters/tanstack.ts"
  - "CopilotKit/CopilotKit:packages/sqlite-runner/src/sqlite-runner.ts"
  - "CopilotKit/CopilotKit:packages/shared/src/transcription-errors.ts"

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 Inte