You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(shell-docs): promote unselected/ richer content over root stubs and v1 versions
Nine files where the root version was either a one-line component stub
(`<Inspector />`, `<HeadlessUI />`, `<Observability />`, `<Overview />`)
or used v1 API patterns (`<CopilotKit>` / `@copilotkit/react-core`)
that the unselected/ tree had already updated to v2 patterns
(`<CopilotKitProvider>` / `@copilotkit/react-core/v2`). Promoting the
richer content over the root stubs / v1 versions:
- inspector.mdx (root: 11L stub → 79L of real content)
- premium/headless-ui.mdx (root: 7L stub → 290L)
- premium/observability.mdx (root: 7L stub → 259L)
- premium/overview.mdx (root: 7L stub → 84L)
- generative-ui/your-components/interactive.mdx (root: 21L IntegrationGrid placeholder → 78L with snippet_cell)
- troubleshooting/common-issues.mdx (v1 imports → v2; tighter prose)
- troubleshooting/error-debugging.mdx (v1 imports → v2; "& Observability" added to title; programmatic onError section retained)
- backend/ag-ui.mdx (v1 → v2 imports)
- backend/copilot-runtime.mdx (v1 → v2 imports)
The unselected/ versions weren't a side-tree of duplicate content —
they were the v2-aware refresh that hadn't propagated to root yet.
First commit of the `unselected/` editorial cleanup tracked under
PDX-49. Cat A deletes (root canonical), Cat B deletes (BIA canonical),
D-promote moves (interrupt-based + 12 tutorials), Cat D-delete
(agent-app-context), redirect rules, and inbound link rewrites still
to come.
description: How CopilotKit uses the AG-UI protocol to connect your frontend to your AI agents.
4
+
description: "How CopilotKit uses the AG-UI protocol to connect your frontend to your Built-in Agent."
5
5
---
6
6
7
-
CopilotKit is built on the [AG-UI protocol](https://ag-ui.com), a lightweight, event-based standard that defines how AI agents communicate with user-facing applications over Server-Sent Events (SSE).
7
+
CopilotKit is built on the [AG-UI protocol](https://ag-ui.com) — a lightweight, event-based standard that defines how AI agents communicate with user-facing applications over Server-Sent Events (SSE).
8
8
9
9
Everything in CopilotKit — messages, state updates, tool calls, and more — flows through AG-UI events. Understanding this layer helps you debug, extend, and build on top of CopilotKit more effectively.
10
10
11
-
## Accessing Your Agent with `useAgent`
11
+
## Accessing your agent with `useAgent`
12
12
13
13
The `useAgent` hook is your primary interface to the AG-UI agent powering your copilot. It returns an `AbstractAgent` from the AG-UI client library — the same base type that all AG-UI agents implement.
The returned `agent` is a standard AG-UI `AbstractAgent`. You can subscribe to its events, read its state, and interact with it using the same interface defined by the [AG-UI specification](https://docs.ag-ui.com).
34
34
35
-
### Subscribing to AG-UI Events
35
+
### Subscribing to AG-UI events
36
36
37
37
Every agent exposes a `subscribe` method that lets you listen for specific AG-UI events as they stream in. Each callback receives the event and the current agent state:
@@ -92,73 +92,34 @@ The full list of subscribable events maps directly to the [AG-UI event types](ht
92
92
| Custom |`onCustomEvent`, `onRawEvent`| Custom and raw events for extensibility |
93
93
| High-level |`onMessagesChanged`, `onStateChanged`| Aggregate notifications after any message or state mutation |
94
94
95
-
## The Proxy Pattern
95
+
## The proxy pattern
96
96
97
97
When you use CopilotKit with a runtime, your frontend never talks directly to your agent. Instead, CopilotKit creates a **proxy agent** on the frontend that forwards requests through the Copilot Runtime.
98
98
99
-
On startup, CopilotKit calls the runtime's `/info` endpoint to discover which agents are available. Each agent is wrapped in a `ProxiedCopilotRuntimeAgent` — a thin client that extends AG-UI's `HttpAgent`. From your component's perspective, this proxy behaves identically to a local AG-UI agent: same `AbstractAgent` interface, same subscribe API, same properties. But under the hood, every `run` call is an HTTP request to your server, and every response is an SSE stream of AG-UI events flowing back.
99
+
On startup, CopilotKit calls the runtime's `/info` endpoint to discover which agents are available. Each agent is wrapped in a `ProxiedCopilotRuntimeAgent` — a thin client that extends AG-UI's `HttpAgent`. From your component's perspective, this proxy behaves identically to a local AG-UI agent: same `AbstractAgent` interface, same subscribe API, same properties. Under the hood, every `run` call is an HTTP request to your server, and every response is an SSE stream of AG-UI events flowing back.
100
100
101
101
```tsx title="What your component sees"
102
102
const { agent } =useAgent(); // Returns an AbstractAgent
103
-
agent.messages; // Read messages
104
-
agent.state; // Read state
105
-
agent.subscribe({ ...});// Subscribe to events
103
+
agent.messages; // Read messages
104
+
agent.state; // Read state
105
+
agent.subscribe({ /* … */}); // Subscribe to events
106
106
```
107
107
108
108
```tsx title="What actually happens"
109
109
// useAgent() → AgentRegistry checks /info → wraps each agent in ProxiedCopilotRuntimeAgent
110
110
// agent.runAgent() → HTTP POST to runtime → runtime routes to your agent → SSE stream back
111
111
```
112
112
113
-
This indirection is what enables the runtime to provide authentication, middleware, agent routing, and ecosystem features like threads and observability — without changing how you interact with agents on the frontend.
113
+
This indirection is what enables the runtime to provide authentication, middleware, agent routing, and premium features — without changing how you interact with agents on the frontend.
114
114
115
-
## How Agents Slot into the Runtime
115
+
## How the Built-in Agent slots into AG-UI
116
116
117
-
On the server side, the `CopilotRuntime` accepts a map of AG-UI `AbstractAgent`instances. Each agent framework provides its own implementation, but they all extend the same base type.
117
+
Even though `BuiltInAgent` looks like a "single-function convenience", it's still an AG-UI `AbstractAgent`under the hood. When you register it with the runtime:
118
118
119
-
Here's a real example from the `langgraph-python` integration — registering a `LangGraphAgent` (which is an `AbstractAgent`) under multiple agent IDs that all share the same backend graph:
119
+
1. A request comes in to your runtime endpoint
120
+
2. The runtime resolves the target agent by ID (`"default"`, `"research-agent"`, …)
121
+
3. It clones the agent (for thread safety) and populates messages, state, and thread context from the request
122
+
4. The `AgentRunner` executes the agent, which produces a stream of AG-UI `BaseEvent`s
123
+
5. Events are encoded as SSE and streamed back to the frontend proxy
2. It clones the agent (for thread safety) and sets messages, state, and thread context from the request
161
-
3. The `AgentRunner` executes the agent, which produces a stream of AG-UI `BaseEvent`s
162
-
4. Events are encoded as SSE and streamed back to the frontend proxy
163
-
164
-
Because every agent is an `AbstractAgent`, you can register any AG-UI-compatible agent — whether it's an `HttpAgent` pointing at a remote server, a framework-specific adapter like `LangGraphAgent`, or a custom implementation — and the runtime handles routing, middleware, and delivery uniformly.
125
+
Because every agent is an `AbstractAgent`, the same plumbing routes requests to a `BuiltInAgent`, an `HttpAgent` pointing at a remote server, or any custom implementation you register alongside — the frontend never has to care.
Copy file name to clipboardExpand all lines: showcase/shell-docs/src/content/docs/backend/copilot-runtime.mdx
+37-38Lines changed: 37 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
-
title: Copilot Runtime
2
+
title: "Copilot Runtime"
3
+
description: "The Copilot Runtime is the backend that connects your frontend to your AI agents, providing authentication, middleware, routing, and more."
3
4
icon: "lucide/Server"
4
-
description: The Copilot Runtime is the backend that connects your frontend to your AI agents, providing authentication, middleware, routing, and more.
5
5
---
6
6
7
-
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.
7
+
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.
8
8
9
-
## Setting Up the Runtime
9
+
## Setting up the runtime
10
10
11
11
The runtime is a lightweight server endpoint that you add to your backend. Here's a minimal example using Next.js:
For setup with other backend frameworks (Express, NestJS, Node.js HTTP), see the [quickstart](/quickstart).
48
+
For Express, NestJS, or plain Node.js HTTP variants, see the [quickstart](./quickstart).
49
49
50
50
## Agents
51
51
52
52
The runtime supports multiple agent types. `BuiltInAgent` is the primary agent class:
53
53
54
-
-**Simple mode** — pass a model string, CopilotKit handles everything. Best for quick setup. See [Quickstart](/quickstart).
55
-
-**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).
54
+
-**Simple mode** — pass a model string, CopilotKit handles everything. Best for quick setup. See [Quickstart](./quickstart).
55
+
-**Factory mode** — bring your own AI SDK, TanStack AI, or custom LLM backend. Best when you need full control. See [Factory Mode](/integrations/built-in-agent/custom-agent).
56
56
57
-
## The Default Agent
57
+
## The default agent
58
58
59
-
If you register an agent with 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.
59
+
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.
60
60
61
61
```ts title="app/api/copilotkit/route.ts"
62
62
const runtime =newCopilotRuntime({
63
63
agents: {
64
-
// This agent will be used automatically by CopilotPopup, CopilotSidebar, etc.
When you register multiple agents, the `"default"` agent is what powers the chat unless a specific agent is selected. Other agents can still be used by passing their `agentId` to `useAgent` or the prebuilt components.
70
+
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.
71
71
72
-
## What the Runtime Provides
72
+
## What the runtime provides
73
73
74
-
### Authentication and Security
74
+
### Authentication & security
75
75
76
-
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 are put in place so your agent endpoints are not exposed to unauthenticated access.
76
+
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.
77
77
78
-
### AG-UI Middleware
78
+
### AG-UI middleware
79
79
80
-
The [AG-UI protocol](/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.
80
+
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.
81
81
82
-
### Agent Routing
82
+
### Agent routing
83
83
84
-
When you register multiple agents with the runtime, it handles discovery and routing automatically. Your frontend doesn't need to know the details of where each agent lives or how to reach it.
84
+
When you register multiple agents, the runtimehandles discovery and routing automatically. Your frontend doesn't need to know where each agent lives or how to reach it.
85
85
86
-
### Premium Features
86
+
### Premium features
87
87
88
-
Features like threads, observability, and the inspector are provided through the runtime. These give you conversation persistence, monitoring, and debugging capabilities out of the box.
88
+
[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.
89
89
90
-
## Built-in Middleware
90
+
## Built-in middleware
91
91
92
-
The runtime supports two first-class middleware options you can enable directly on `CopilotRuntime` without calling `.use()` on each agent manually.
92
+
The runtime exposes two first-class middleware options you can enable directly on `CopilotRuntime` without calling `.use()` on each agent manually.
93
93
94
94
### A2UI
95
95
@@ -98,7 +98,7 @@ Pass `a2ui: {}` to automatically apply `A2UIMiddleware` to all registered agents
98
98
```ts title="app/api/copilotkit/route.ts"
99
99
const runtime =newCopilotRuntime({
100
100
agents: { default: myAgent },
101
-
a2ui: {}, // enables A2UI rendering for all agents
101
+
a2ui: {}, // enables A2UI rendering for all agents
102
102
});
103
103
```
104
104
@@ -108,12 +108,12 @@ To scope it to specific agents only, pass an `agents` list:
108
108
a2ui: { agents: ["my-agent"] }
109
109
```
110
110
111
-
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>`:
111
+
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 `<CopilotKitProvider>`:
@@ -133,9 +133,9 @@ const runtime = new CopilotRuntime({
133
133
134
134
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.
135
135
136
-
## What If I Want to Connect to My AG-UI Agent Directly?
136
+
## Connecting to an AG-UI agent directly
137
137
138
-
CopilotKit is built on the [AG-UI protocol](/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 passing agent instances directly to the `CopilotKit` provider:
138
+
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 `CopilotKitProvider`:
139
139
140
140
```tsx
141
141
import { HttpAgent } from"@ag-ui/client";
@@ -144,20 +144,19 @@ const myAgent = new HttpAgent({
Direct agent connections are intended for development and prototyping. This approach is not recommended for production unless you are confident in your setup, and is not officially supported by CopilotKit. If you run into issues with a direct connection, you will need to troubleshoot on your own.
153
+
Direct agent connections are intended for development and prototyping. They are **not recommended for production** and are not officially supported by CopilotKit.
154
154
</Callout>
155
155
156
-
There are important things to understand before going this route:
156
+
Key trade-offs:
157
157
158
-
1.**Authentication is your responsibility.** When you use the Copilot Runtime, safe defaults are put in place so that your agent endpoints are not exposed to unauthenticated access. When you connect directly, it is entirely up to you to secure your agent endpoint and manage authentication.
159
-
160
-
2.**Many ecosystem features won't work.** The AG-UI protocol supports a middleware layer designed to run on the backend. Many features in the CopilotKit ecosystem depend on this server-side middleware. Without the runtime, these features — including threads, observability, and other capabilities — will not be available.
158
+
1.**Authentication is your responsibility** — the runtime's safe defaults do not apply.
159
+
2.**Many ecosystem features won't work** — runtime-backed middleware, observability, and other capabilities depend on the server-side path.
0 commit comments