Copilot Runtime

The Copilot Runtime is the backend layer that connects your frontend application to your AI agents. It's set up during the 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:

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:

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.

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.
• Factory mode — bring your own AI SDK, TanStack AI, or custom LLM backend. Best when you need full control. See Factory Mode.

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.

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 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, the 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:

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

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:

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

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

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#