Copilot Runtime

The Copilot Runtime is the backend that connects your frontend to your AI agents, providing authentication, middleware, routing, and more.

Your frontend needs a trusted server between it and your agents. The Copilot Runtime is that server. It keeps API keys out of the browser, lets you check who is calling, and routes each chat to the right agent. The quickstart sets it up, and it is the recommended way to use CopilotKit.

Runtime languages

TypeScript is the default and most fully featured runtime. It is the only runtime that can run without CopilotKit Intelligence. Use it for an open-source setup, or connect it to Intelligence when you need its services.

Python, Go, Ruby, and C#/.NET runtimes require an Intelligence project and server-side API key. They work with both cloud-hosted and self-hosted Intelligence; they do not provide an in-memory or SQLite runner.

LanguageHostWithout Intelligence
TypeScriptNext.js, Express, Hono, and other JavaScript serversYes
PythonASGI, with Python 3.11+No
Gonet/http, with Go 1.22+No
RubyRack, including Rails and Sinatra, with Ruby 2.7+No
C#/.NETASP.NET Core, with .NET 8No

Your runtime language does not have to match your agent language. Each runtime can connect to a remote AG-UI agent. A Python agent can stay behind a TypeScript runtime, for example.

Use the Intelligence quickstart for language-specific installation, authentication, and server setup. The runtime API is different in each language. Some TypeScript options are not available in every language: BuiltInAgent, custom AgentRunner classes, audio transcription, and Open Generative UI.

The examples below use the TypeScript runtime.

Setting up the runtime

The runtime is a server endpoint that you add to your backend.

Add the route file. Here is a minimal example for Next.js:

app/api/copilotkit/[[...slug]]/route.ts
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
  InMemoryAgentRunner,
} from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: {
    // your agents go here
  },
  runner: new InMemoryAgentRunner(),
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handler;
export const POST = handler;
export const PATCH = handler;
export const DELETE = handler;

Point your frontend at /api/copilotkit:

For Express, NestJS, or plain Node.js HTTP variants, see the quickstart. For the exact HTTP routes the runtime exposes (and how to probe them with curl), see Runtime HTTP endpoints.

Migrating from the v1 endpoint factories

The copilotRuntimeNextJSAppRouterEndpoint, copilotRuntimeNodeHttpEndpoint, copilotRuntimeNodeExpressEndpoint, and copilotRuntimeNestEndpoint helpers from @copilotkit/runtime are the v1 endpoint factories, deprecated since 1.68.2. Use createCopilotRuntimeHandler from @copilotkit/runtime/v2. For Express, use createCopilotExpressHandler from @copilotkit/runtime/v2/express. For a plain Node.js HTTP server, use createCopilotNodeListener from @copilotkit/runtime/v2/node. The v2 handlers serve several routes by default. If your React provider sets useSingleEndpoint={true}, remove it. See Migrate to v2 and Provider and handler pairs.

Agents

The runtime supports multiple agent types. BuiltInAgent is the primary agent class:

  • Simple mode: pass a model string and let CopilotKit handle the rest. Best for quick setup. See Quickstart.
  • Factory mode: bring your own AI SDK, TanStack AI, or custom LLM backend. Best when you need full control. See Factory Mode.

To register agent logic you wrote yourself, extend AG-UI's AbstractAgent. See Write your own AG-UI agent.

Wiring an external agent: what to pass, and which URL

Two mistakes account for most failures here.

agents takes AbstractAgent instances. A framework's own SDK client is not one. Pass the @ag-ui/<framework> wrapper for it, or a plain HttpAgent, rather than the client itself.

And the URL an external agent takes is its own server or deployment, not /api/copilotkit. /api/copilotkit is the address that the browser calls. The agent URL is the address that the runtime calls. Each integration guide names the exact URL its framework serves, including any required suffix.

Which name identifies an agent

The name you use to address an agent from the frontend must equal a key of the runtime's agents map. That key is the only name the frontend can ask for. An agent's own name, id, or class name is never used for routing, and the two are free to differ.

app/api/copilotkit/[[...slug]]/route.ts
const runtime = new CopilotRuntime({
  agents: {
    // `my_agent` is the key — the one string the frontend may ask for.
    my_agent: new HttpAgent({ url: "http://localhost:8000/" }),
  },
});

Most integrations write that key literally in the runtime route, as above, so the binding is visible in one file. Some derive it instead, and that is where the rule stops being obvious:

  • Mastra: the runtime key is the record key in new Mastra({ agents: { ... } }), not the agent's id. MastraAgent.getRemoteAgents and getLocalAgents both read it from listAgents(). Given new Agent({ name: "My Agent" }) exported as myAgent and registered as agents: { myAgent }, the runtime key is myAgent.
  • LangGraph: graphId is a separate binding, from the runtime to a key in your deployment's langgraph.json. It does not have to equal the runtime's agents-map key, and it is not the name the frontend asks for. The starter template happens to use sample_agent for both.

An agent's declared name is not its routing key

Asking for a name the runtime did not register resolves no agent. In React, useAgent throws an error that starts with useAgent: Agent '<name>' not found after runtime sync. See Agent discovery failed. The error message lists the keys the runtime actually returned, which is the quickest way to see the real names.

To read the registered keys directly, hit GET {runtimeUrl}/info. It returns the agents the runtime advertises, under exactly the names the frontend must use.

The default agent

If you register an agent under the name "default", CopilotKit's prebuilt UI components will use it automatically without any additional configuration on the frontend. This is useful when you have one primary agent and don't want to specify an agentId everywhere.

app/api/copilotkit/[[...slug]]/route.ts
import { BuiltInAgent } from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: {
    // Frontend components use this agent unless given another agentId.
    default: new BuiltInAgent({ model: "openai:gpt-6-luna" }),
  },
});

When you register multiple agents, the "default" agent is what powers the chat unless a specific agent is selected. Other agents can still be addressed by passing their agentId to a chat component or frontend agent API.

What the runtime provides

Authentication & security

The runtime runs on your server, which means agent communication stays server-side. This gives you a trusted environment to enforce authentication, validate requests, and keep API keys secure. The runtime does not reject unauthenticated requests on its own. Reject them in the onRequest hook of createCopilotRuntimeHandler, and pass identifyUser to CopilotRuntime to scope threads per user. See Authentication.

AG-UI middleware

The AG-UI protocol supports a middleware layer (agent.use) for logging, guardrails, request transformation, and more. Because the runtime runs server-side, this middleware executes in a trusted environment where it cannot be tampered with by the client.

Agent routing

When you register multiple agents, the runtime handles discovery and routing automatically. Your frontend doesn't need to know where each agent lives or how to reach it.

CopilotKit Intelligence

Threads, the inspector, and other CopilotKit Intelligence capabilities are provided through the runtime. These give you conversation persistence and debugging without extra setup.

To group Threads for Learning, see Learning.

Built-in middleware

The runtime exposes two first-class middleware options you can enable directly on CopilotRuntime without calling .use() on each agent manually.

A2UI

Pass a2ui: {} to automatically apply A2UIMiddleware to all registered agents:

app/api/copilotkit/route.ts
const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  a2ui: {}, // enables A2UI rendering for all agents
});

To scope it to specific agents only, pass an agents list:

a2ui: { agents: ["my-agent"] }

On the frontend, the A2UI renderer activates automatically. No extra configuration is needed. Configure a2ui only when you want to override the default theme:

mcpApps

Pass mcpApps to configure MCP servers for all agents from a single place:

app/api/copilotkit/route.ts
const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  mcpApps: {
    servers: [
      { type: "http", url: "http://localhost:3108/mcp" },
    ],
  },
});

Each server entry optionally accepts an agentId field to scope that server to a single agent. Without it, the server is available to all agents.

The runtime does not support includeTools or excludeTools on a server entry. Passing either key throws a configuration error.

Forwarding request headers to your agent

When a request reaches the runtime, some inbound headers are forwarded onto the outgoing call to your agent (the /run path that actually dispatches the agent). This is how a token configured by the frontend provider reaches a self-hosted agent. See Authentication.

By default the runtime forwards authorization and any x-* header, minus a built-in denylist of infrastructure, proxy, and platform headers that no legitimate agent integration needs forwarded from the edge. The denylist strips, among others:

  • Proxy / topology: x-forwarded-*, x-real-ip
  • Cloud / CDN tracing: x-amzn-trace-id, x-amz-* (AWS), x-azure-*, x-fastly-*, x-cloud-trace-context, x-cache, x-served-by
  • Platform-injected: x-vercel-*, x-middleware-* (Next.js)
  • CopilotKit platform: x-copilotcloud-*, including x-copilotcloud-public-api-key

Everything else still forwards: authorization, and any custom application header like x-tenant-id, x-api-key, or x-user-id.

Upgrade note: x-request-id is now stripped

Earlier runtime versions forwarded x-request-id. It is now stripped by default because it is predominantly a proxy-assigned trace id. If your agent relies on receiving your own x-request-id, re-enable it with forwardHeaders: { allow: [...] } or useDefaultDenylist: false (below).

Server-configured headers win

Headers you set on an agent (e.g. new HttpAgent({ headers: { Authorization: "Bearer <service-token>" } })) take precedence over a forwarded inbound header of the same name, matched case-insensitively. A service-to-service token you configured on the server is never silently overridden by a browser- or edge-injected inbound header.

Configuring the policy

Pass forwardHeaders to CopilotRuntime to tune what forwards:

app/api/copilotkit/route.ts
const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  forwardHeaders: {
    // Strip additional headers on top of the default denylist:
    deny: ["x-internal-debug"],
    denyPrefixes: ["x-acme-"],
  },
});

The options:

  • deny / denyPrefixes: extra exact names / name-prefixes to strip. These always strip (deny wins), even in allowlist mode, so a security-motivated deny can never be defeated by an overlapping allow.
  • allow: switches to allowlist mode. Only the listed headers forward, and the usual authorization / x-* eligibility does not apply. Your deny / denyPrefixes still subtract from this set.
  • useDefaultDenylist: defaults to true. Set false to opt out of the built-in denylist, so authorization and every x-* header forward unless your deny / denyPrefixes strip them.

Empty or whitespace-only entries are ignored in every list.

// Allowlist mode: forward ONLY these two, nothing else.
forwardHeaders: { allow: ["authorization", "x-tenant-id"] }

Allowlist mode bypasses the default denylist

In allowlist mode the built-in denylist does not apply. Only your allow set (minus your own deny) forwards. If you do not intend to forward a protected header such as x-copilotcloud-public-api-key or x-forwarded-*, do not put it in allow.

Keeping quiet streams alive

A run can be silent for a long time while the agent reasons or waits on a slow tool. The runtime writes a : keep-alive SSE comment after 15 seconds without output so proxies and browsers with idle timeouts keep the connection open. Comments are transport frames: they never become AG-UI events. Tune or disable this with sseKeepAliveIntervalSeconds (0 disables it).

Connecting to an AG-UI agent directly

CopilotKit is built on the AG-UI protocol, which is an open standard. If you want to connect your frontend directly to an AG-UI-compatible agent without the runtime, you can do so by registering agent instances with the frontend SDK:

Direct agent connections are intended for development and prototyping. They are not recommended for production and are not officially supported by CopilotKit.

If you intend to manage the agent connection yourself in production and have secured it, use the supported selfManagedAgents configuration instead of the local-development agent option.

Key trade-offs:

  1. Authentication is your responsibility. The runtime's auth hooks do not apply.
  2. Many ecosystem features won't work. Runtime-backed middleware and other capabilities depend on the server-side path.

Comparison

With RuntimeDirect Connection
AuthenticationRuntime auth hooksYou manage it
AG-UI MiddlewareRuns server-sideNot available
Agent RoutingAutomaticManual
Ecosystem FeaturesFull supportLimited
CopilotKit SupportSupportedNot supported
SetupRequires a backend endpointFrontend-only

How is this guide?