---
title: "Copilot Runtime"
description: "The Copilot Runtime is the backend that connects your frontend to your AI agents, providing authentication, middleware, routing, and more."
icon: "lucide/Server"
---

The Copilot Runtime is the backend layer that connects your frontend application to your AI agents. It's set up during the [quickstart](./quickstart) and is the recommended way to use CopilotKit.

## Setting up the runtime

The runtime is a lightweight server endpoint that you add to your backend. Here's a minimal example using Next.js:

```ts title="app/api/copilotkit/route.ts"
import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";

const serviceAdapter = new ExperimentalEmptyAdapter();

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

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};
```

Then point your frontend at the endpoint:

```tsx
import { CopilotKit } from "@copilotkit/react-core/v2";

<CopilotKit runtimeUrl="/api/copilotkit">
  <YourApp />
</CopilotKit>
```

For Express, NestJS, or plain Node.js HTTP variants, see the [quickstart](./quickstart).

## Agents

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

- **Simple mode** — pass a model string, CopilotKit handles everything. Best for quick setup. See [Quickstart](./quickstart).
- **Factory mode** — bring your own AI SDK, TanStack AI, or custom LLM backend. Best when you need full control. See [Factory Mode](/backend/custom-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/route.ts"
import { BuiltInAgent } from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: {
    // This agent is used automatically by CopilotPopup, CopilotSidebar, etc.
    default: new BuiltInAgent({ model: "openai:gpt-5.4-mini" }),
  },
});
```

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 `useAgent` or the prebuilt components.

## 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. When you use the runtime, safe defaults prevent your agent endpoints from being exposed to unauthenticated access.

### AG-UI middleware

The [AG-UI protocol](./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

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.

### Premium features

[Observability](./premium/observability), the [inspector](./inspector), and other premium capabilities are provided through the runtime. These give you conversation persistence, monitoring, and debugging out of the box.

## 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:

```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 needed. If you want to override the default theme, pass an `a2ui` prop to `<CopilotKit>`:

```tsx
import { CopilotKit } from "@copilotkit/react-core/v2";

<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ theme: myCustomTheme }}>
  {children}
</CopilotKit>
```

### 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", serverId: "my-server" },
    ],
  },
});
```

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.

## Connecting to an AG-UI agent directly

CopilotKit is built on the [AG-UI protocol](./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 passing agent instances straight to the `CopilotKit`:

```tsx
import { HttpAgent } from "@ag-ui/client";
import { CopilotKit } from "@copilotkit/react-core/v2";

const myAgent = new HttpAgent({
  url: "https://my-agent.example.com",
});

<CopilotKit agents__unsafe_dev_only={{ "my-agent": myAgent }}>
  <YourApp />
</CopilotKit>;
```

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

Key trade-offs:

1. **Authentication is your responsibility** — the runtime's safe defaults do not apply.
2. **Many ecosystem features won't work** — runtime-backed middleware, observability, and other capabilities depend on the server-side path.

### Comparison

| | With Runtime | Direct Connection |
|---|---|---|
| **Authentication** | Safe defaults provided | 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 |