# 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](/react-native/langgraph-fastapi/quickstart) sets it up, and it is the recommended way to use CopilotKit.

## Runtime languages [#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](/react-native/langgraph-fastapi/intelligence/managed-intelligence-platform) and [self-hosted](/react-native/langgraph-fastapi/intelligence/self-hosting) Intelligence; they do not provide an in-memory or SQLite runner.

| Language | Host | Without Intelligence |
| --- | --- | --- |
| TypeScript | Next.js, Express, Hono, and other JavaScript servers | Yes |
| Python | ASGI, with Python 3.11+ | No |
| Go | `net/http`, with Go 1.22+ | No |
| Ruby | Rack, including Rails and Sinatra, with Ruby 2.7+ | No |
| C#/.NET | ASP.NET Core, with .NET 8 | No |

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](/react-native/langgraph-fastapi/intelligence/quickstart#connect-your-runtime) 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 [#setting-up-the-runtime]

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

<Steps>
<Step>
Add the route file. Here is a minimal example for Next.js:

```ts title="app/api/copilotkit/[[...slug]]/route.ts" doctest="component"
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;
```
</Step>

<Step>
Point your frontend at `/api/copilotkit`:

</Step>
</Steps>

For Express, NestJS, or plain Node.js HTTP variants, see the [quickstart](/react-native/langgraph-fastapi/quickstart).
For the exact HTTP routes the runtime exposes (and how to probe them with `curl`),
see [Runtime HTTP endpoints](/react-native/langgraph-fastapi/backend/runtime-endpoints).

<Callout type="info" title="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](/migrate/v2) and [Provider and handler pairs](/react-native/langgraph-fastapi/backend/runtime-endpoints#provider-and-handler-pairs).
</Callout>

## Agents [#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](/react-native/langgraph-fastapi/quickstart).
- **Factory mode:** bring your own AI SDK, TanStack AI, or custom LLM backend. Best when you need full control. See [Factory Mode](/react-native/langgraph-fastapi/backend/custom-agent).

To register agent logic you wrote yourself, extend AG-UI's `AbstractAgent`. See [Write your own AG-UI agent](/react-native/langgraph-fastapi/backend/custom-ag-ui-agent).

<Callout type="warn" title="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.
</Callout>

## Which name identifies an agent [#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.

```ts title="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.

<Callout type="warn" title="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](/troubleshooting/error-reference). The error message lists the keys the
  runtime actually returned, which is the quickest way to see the real names.
</Callout>

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 [#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.

```ts title="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 [#what-the-runtime-provides]

### Authentication & security [#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](/auth).

### AG-UI middleware [#ag-ui-middleware]

The [AG-UI protocol](/react-native/langgraph-fastapi/backend/ag-ui) 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 [#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 [#copilotkit-intelligence]

[Threads](/react-native/langgraph-fastapi/AG-UI-Streams), the [inspector](/react-native/langgraph-fastapi/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](/react-native/langgraph-fastapi/learning).

## Built-in middleware [#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 [#a2ui]

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

```ts title="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:

```ts
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 [#mcpapps]

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

```ts title="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 [#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](/auth).

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`.

<Callout type="warn" title="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).
</Callout>

### Server-configured headers win [#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 [#configuring-the-policy]

Pass `forwardHeaders` to `CopilotRuntime` to tune what forwards:

```ts title="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.

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

<Callout type="warn" title="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`.
</Callout>

## Keeping quiet streams alive [#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 [#connecting-to-an-ag-ui-agent-directly]

CopilotKit is built on the [AG-UI protocol](/react-native/langgraph-fastapi/backend/ag-ui), 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:

<Callout type="warn">
Direct agent connections are intended for development and prototyping. They are **not recommended for production** and are not officially supported by CopilotKit.
</Callout>

If you intend to manage the agent connection yourself in production and have
secured it, use the supported
[`selfManagedAgents`](/react-native/langgraph-fastapi/backend/self-managed-agents) 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 [#comparison]

| | With Runtime | Direct Connection |
|---|---|---|
| **Authentication** | Runtime auth hooks | You manage it |
| **AG-UI Middleware** | Runs server-side | Not available |
| **Agent Routing** | Automatic | Manual |
| **Ecosystem Features** | Full support | Limited |
| **CopilotKit Support** | Supported | Not supported |
| **Setup** | Requires a backend endpoint | Frontend-only |
