CopilotKit Runtime

@copilotkit/runtime

AbstractAgent

AgentRunner

references/

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
});

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

When to load which reference

references/setup-endpoint.md

hooks.onRequest

hooks.onBeforeHandler

beforeRequestMiddleware

afterRequestMiddleware

references/middleware.md

InMemoryAgentRunner

SqliteAgentRunner

references/agent-runners.md

-in-memory.md

-sqlite.md

-custom.md

references/intelligence-mode.md

TranscriptionService

/transcribe

references/transcription.md

BuiltInAgent

references/built-in-agent.md

-factory-modes.md

-helper-utilities.md

-model-identifiers.md

defineTool

BuiltInAgent.config.tools

references/server-side-tools.md

CopilotRuntime({ agents })

references/wiring-external-agents.md

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

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 CopilotKit Cloud (

  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

   .