Skip to content

Commit 4f50e75

Browse files
nuthalapativarunomeraplakcubic-dev-ai[bot]
authored
docs(ag-ui): add README with usage examples and CopilotKit integration (#1352)
* docs(ag-ui): add README with usage examples and CopilotKit integration * docs(ag-ui): add missing @voltagent/core and @ai-sdk/openai to install command * Update packages/ag-ui/README.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * Update packages/ag-ui/README.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * Update packages/ag-ui/README.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> --------- Co-authored-by: Omer Aplak <omeraplak@gmail.com> Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
1 parent eca69b5 commit 4f50e75

2 files changed

Lines changed: 136 additions & 0 deletions

File tree

‎.changeset/ag-ui-readme.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@voltagent/ag-ui": patch
3+
---
4+
5+
Add README documentation

‎packages/ag-ui/README.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
+<div align="center">
2+
<a href="https://voltagent.dev/">
3+
<img width="1500" height="276" alt="voltagent" src="https://github.com/user-attachments/assets/d9ad69bd-b905-42a3-81af-99a0581348c0" />
4+
</a>
5+
6+
<h3 align="center">
7+
AI Agent Engineering Platform
8+
</h3>
9+
10+
<div align="center">
11+
<a href="https://voltagent.dev">Home Page</a> |
12+
<a href="https://voltagent.dev/docs/">Documentation</a> |
13+
<a href="https://github.com/voltagent/voltagent/tree/main/examples">Examples</a>
14+
</div>
15+
</div>
16+
17+
<br/>
18+
19+
<div align="center">
20+
21+
[![GitHub issues](https://img.shields.io/github/issues/voltagent/voltagent)](https://github.com/voltagent/voltagent/issues)
22+
[![GitHub pull requests](https://img.shields.io/github/issues-pr/voltagent/voltagent)](https://github.com/voltagent/voltagent/pulls)
23+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
24+
[![npm version](https://img.shields.io/npm/v/@voltagent/ag-ui.svg)](https://www.npmjs.com/package/@voltagent/ag-ui)
25+
[![npm downloads](https://img.shields.io/npm/dm/@voltagent/ag-ui.svg)](https://www.npmjs.com/package/@voltagent/ag-ui)
26+
[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord)
27+
28+
</div>
29+
30+
## @voltagent/ag-ui
31+
32+
An [AG-UI](https://github.com/ag-ui-protocol/ag-ui) adapter for VoltAgent. Wrap any VoltAgent `Agent` as an AG-UI `AbstractAgent` that streams VoltAgent events as AG-UI protocol events, and optionally expose it through a [CopilotKit](https://www.copilotkit.ai/) runtime.
33+
34+
---
35+
36+
## Install
37+
38+
```bash
39+
npm install @voltagent/ag-ui @voltagent/core @ai-sdk/openai @ag-ui/client @ag-ui/core
40+
# or
41+
yarn add @voltagent/ag-ui @voltagent/core @ai-sdk/openai @ag-ui/client @ag-ui/core
42+
# or
43+
pnpm add @voltagent/ag-ui @voltagent/core @ai-sdk/openai @ag-ui/client @ag-ui/core
44+
```
45+
46+
Add `@copilotkit/runtime` as well if you plan to use the CopilotKit handlers below.
47+
48+
## Usage
49+
50+
Wrap a VoltAgent agent so it speaks the AG-UI protocol:
51+
52+
```typescript
53+
import { Agent } from "@voltagent/core";
54+
import { createVoltAgentAGUI } from "@voltagent/ag-ui";
55+
import { openai } from "@ai-sdk/openai";
56+
57+
const agent = new Agent({
58+
name: "my-agent",
59+
instructions: "A helpful assistant",
60+
model: openai("gpt-4o-mini"),
61+
});
62+
63+
const aguiAgent = createVoltAgentAGUI({ agent });
64+
```
65+
66+
`createVoltAgentAGUI` accepts:
67+
68+
| Option | Type | Description |
69+
| -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
70+
| `agent` | `Agent` | The VoltAgent agent to expose over AG-UI |
71+
| `deriveUserId` | `(input: RunAgentInput) => string \| undefined` | Optional function to derive a `userId` for memory/telemetry from the AG-UI run input |
72+
73+
`aguiAgent.run(input)` returns an `Observable<BaseEvent>` that emits AG-UI lifecycle, message, and tool-call events translated from the agent's `streamText` output.
74+
75+
## CopilotKit Integration
76+
77+
Use `createCopilotKitHandler` to get a framework-agnostic fetch handler for a [CopilotKit runtime](https://www.copilotkit.ai/):
78+
79+
```typescript
80+
import { createCopilotKitHandler, createVoltAgentAGUI } from "@voltagent/ag-ui";
81+
import { agent } from "./agent"; // a VoltAgent instance
82+
83+
const handler = createCopilotKitHandler({
84+
agents: { assistant: createVoltAgentAGUI({ agent }) },
85+
endpoint: "/api/copilotkit",
86+
});
87+
88+
export default {
89+
fetch: handler,
90+
};
91+
```
92+
93+
Or mount it directly on a Hono-style app with `registerCopilotKitRoutes`, picking agents up from the global `AgentRegistry` instead of wiring them by hand:
94+
95+
```typescript
96+
import { registerCopilotKitRoutes } from "@voltagent/ag-ui";
97+
98+
registerCopilotKitRoutes({
99+
app,
100+
resourceIds: ["assistant"], // omit to expose every registered agent
101+
path: "/copilotkit",
102+
});
103+
```
104+
105+
### `CopilotKitHandlerOptions`
106+
107+
| Option | Type | Default | Description |
108+
| ---------------- | ------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------- |
109+
| `agents` | `Record<string, AbstractAgent>` | — | Static map of AG-UI agents |
110+
| `loadAgents` | `() => Promise<Record<string, AbstractAgent>> \| Record<string, AbstractAgent>` | — | Lazy loader; overrides `agents` if provided |
111+
| `serviceAdapter` | `CopilotServiceAdapter` | `ExperimentalEmptyAdapter` | CopilotKit service adapter |
112+
| `endpoint` | `string` | `"/copilotkit"` | Endpoint path used by CopilotKit clients |
113+
114+
### `RegisterCopilotKitRoutesOptions`
115+
116+
| Option | Type | Default | Description |
117+
| ------------- | ------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------- |
118+
| `app` | Hono-style app (`all(path, handler)`) | — | App instance to register the route on |
119+
| `agents` | `Record<string, Agent>` | — | VoltAgent agents to expose, wrapped lazily with `createVoltAgentAGUI` |
120+
| `resourceIds` | `string[]` | all registered agents | Filter which agents from the global `AgentRegistry` are exposed (if `agents` is omitted) |
121+
| `path` | `string` | `"/copilotkit"` | Path to mount the CopilotKit endpoint |
122+
123+
## Documentation
124+
125+
- [VoltAgent Documentation](https://voltagent.dev/docs/)
126+
- [AG-UI Protocol](https://github.com/ag-ui-protocol/ag-ui)
127+
- [CopilotKit](https://www.copilotkit.ai/)
128+
129+
## License
130+
131+
Licensed under the MIT License, Copyright © 2026-present VoltAgent.

0 commit comments

Comments
 (0)