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.
| 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 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:
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.
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'sid.MastraAgent.getRemoteAgentsandgetLocalAgentsboth read it fromlistAgents(). Givennew Agent({ name: "My Agent" })exported asmyAgentand registered asagents: { myAgent }, the runtime key ismyAgent. - LangGraph:
graphIdis a separate binding, from the runtime to a key in your deployment'slanggraph.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 usesample_agentfor 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.
Local vs remote agents
There are two ways to mount Mastra agents on Copilot Runtime. Where your agent runs decides which one you use.
- Remote: your Mastra instance already runs as its own process
(
mastra dev, a container, a deployed service).MastraAgent.getRemoteAgentsreaches it over HTTP and leaves it where it is. Choose this for any project that already runs a Mastra service. - Local: your Mastra instance lives inside the same process as the runtime
route, and you import it directly.
MastraAgent.getLocalAgentsbridges it in-process. This suits a new single-process app, where there is no separate agent to keep.
Shared state, state streaming, and background tasks need a local agent.
Remote agents
getRemoteAgents is asynchronous: it calls listAgents() on your Mastra server
and returns one AG-UI agent per agent that server reports, keyed by agent id.
import { CopilotRuntime, createCopilotRuntimeHandler, InMemoryAgentRunner } from "@copilotkit/runtime/v2";
import { MastraAgent } from "@ag-ui/mastra";
import { MastraClient } from "@mastra/client-js";
const mastraClient = new MastraClient({
baseUrl: process.env.MASTRA_BASE_URL ?? "http://127.0.0.1:4111",
});
const runtime = new CopilotRuntime({
agents: () =>
MastraAgent.getRemoteAgents({
mastraClient,
resourceId: "user-1",
}),
runner: new InMemoryAgentRunner(),
});Pass it as a factory, as above, rather than calling it at module scope.
agents does accept the promise itself (agents: MastraAgent.getRemoteAgents({ ... })),
but that starts the HTTP call when the module loads, with nothing awaiting it yet.
If the agent server is not up, the rejection is unhandled and Node terminates the
process.
With the factory, nothing runs until a request arrives. If the agent server is
down, that request fails with a 500. The next request tries again, so the route
recovers when the agent server starts. The cost is one listAgents() call per
request. Cache the result in a module-scope variable if that matters to you.
Resolving per request also lets resourceId follow the caller, because the
factory receives the request:
const runtime = new CopilotRuntime({
agents: ({ request }) =>
MastraAgent.getRemoteAgents({
mastraClient,
resourceId: userIdFrom(request),
}),
runner: new InMemoryAgentRunner(),
});GetRemoteAgentsOptions:
| Option | Required | Purpose |
|---|---|---|
mastraClient | yes | A MastraClient from @mastra/client-js, pointed at your agent server's base URL. |
resourceId | yes | Mastra's memory resource: the key that working memory is stored under, for example the user id. |
observationalMemory | no | Surface Mastra Observational Memory as AG-UI activity events. true for every agent, or an array of agent ids. Off by default. |
tracingOptions | no | Forwarded to each run. See Execution tracing. |
Base URL convention. Read the address from the environment and default to the local Mastra dev port, so the same route works locally and against a deployed service:
baseUrl: process.env.MASTRA_BASE_URL ?? "http://127.0.0.1:4111"Prefer 127.0.0.1 over localhost. On machines that resolve localhost to IPv6
first, the loopback name can miss an agent server bound to IPv4 only.
Local agents
getLocalAgents is synchronous and takes the Mastra instance itself, not a
client. It also accepts requestContext and untilIdle, neither of which has a
remote equivalent. Background tasks build on
untilIdle, so a run that needs it has to be embedded.
const runtime = new CopilotRuntime({
agents: MastraAgent.getLocalAgents({ mastra, resourceId: "user-1" }),
runner: new InMemoryAgentRunner(),
});Execution tracing
When you embed a Mastra agent in Copilot Runtime, its tracing is carried through AG-UI end to end, so runs show up in your Mastra observability backend with no extra wiring.
-
Inbound: pass
tracingOptionsalongsidemastrainMastraAgent.getLocalAgentsto tie a run to a trace that you choose. Build the agents per request, as below, so each run gets its own trace.getRemoteAgentstakes the same option. The shape is{ traceId?: string; metadata?: Record<string, unknown> }:const runtime = new CopilotRuntime({ agents: ({ request }) => MastraAgent.getLocalAgents({ mastra, resourceId: userIdFrom(request), tracingOptions: { traceId: traceIdFrom(request), metadata: { feature: "support-chat", tenant: tenantIdFrom(request) }, }, }), }); -
Outbound: Mastra assigns each run an execution
traceIdand surfaces it in theresultfield of theRUN_FINISHEDevent as{ traceId }. Use it to tie feedback or scores to the exact run, for examplecreateFeedback({ traceId }).
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: {
// 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:
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:
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-*, includingx-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:
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-motivateddenycan never be defeated by an overlappingallow.allow: switches to allowlist mode. Only the listed headers forward, and the usualauthorization/x-*eligibility does not apply. Yourdeny/denyPrefixesstill subtract from this set.useDefaultDenylist: defaults totrue. Setfalseto opt out of the built-in denylist, soauthorizationand everyx-*header forward unless yourdeny/denyPrefixesstrip 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:
- Authentication is your responsibility. The runtime's auth hooks do not apply.
- Many ecosystem features won't work. Runtime-backed middleware and other capabilities depend on the server-side path.
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 |
How is this guide?