+

@voltagent/ag-ui

An 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 runtime.

Install

npm install @voltagent/ag-ui @voltagent/core @ai-sdk/openai @ag-ui/client @ag-ui/core
# or
yarn add @voltagent/ag-ui @voltagent/core @ai-sdk/openai @ag-ui/client @ag-ui/core
# or
pnpm add @voltagent/ag-ui @voltagent/core @ai-sdk/openai @ag-ui/client @ag-ui/core

Add @copilotkit/runtime as well if you plan to use the CopilotKit handlers below.

Usage

Wrap a VoltAgent agent so it speaks the AG-UI protocol:

import { Agent } from "@voltagent/core";
import { createVoltAgentAGUI } from "@voltagent/ag-ui";
import { openai } from "@ai-sdk/openai";

const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant",
  model: openai("gpt-4o-mini"),
});

const aguiAgent = createVoltAgentAGUI({ agent });

createVoltAgentAGUI accepts:

| Option | Type | Description | | -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ | | agent | Agent | The VoltAgent agent to expose over AG-UI | | deriveUserId | (input: RunAgentInput) => string \| undefined | Optional function to derive a userId for memory/telemetry from the AG-UI run input |

aguiAgent.run(input) returns an Observable<BaseEvent> that emits AG-UI lifecycle, message, and tool-call events translated from the agent's streamText output.

CopilotKit Integration

Use createCopilotKitHandler to get a framework-agnostic fetch handler for a CopilotKit runtime:

import { createCopilotKitHandler, createVoltAgentAGUI } from "@voltagent/ag-ui";
import { agent } from "./agent"; // a VoltAgent instance

const handler = createCopilotKitHandler({
  agents: { assistant: createVoltAgentAGUI({ agent }) },
  endpoint: "/api/copilotkit",
});

export default {
  fetch: handler,
};

Or mount it directly on a Hono-style app with registerCopilotKitRoutes, picking agents up from the global AgentRegistry instead of wiring them by hand:

import { registerCopilotKitRoutes } from "@voltagent/ag-ui";

registerCopilotKitRoutes({
  app,
  resourceIds: ["assistant"], // omit to expose every registered agent
  path: "/copilotkit",
});

CopilotKitHandlerOptions

| Option | Type | Default | Description | | ---------------- | ------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------- | | agents | Record<string, AbstractAgent> | — | Static map of AG-UI agents | | loadAgents | () => Promise<Record<string, AbstractAgent>> \| Record<string, AbstractAgent> | — | Lazy loader; overrides agents if provided | | serviceAdapter | CopilotServiceAdapter | ExperimentalEmptyAdapter | CopilotKit service adapter | | endpoint | string | "/copilotkit" | Endpoint path used by CopilotKit clients |

RegisterCopilotKitRoutesOptions

| Option | Type | Default | Description | | ------------- | ------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------- | | app | Hono-style app (all(path, handler)) | — | App instance to register the route on | | agents | Record<string, Agent> | — | VoltAgent agents to expose, wrapped lazily with createVoltAgentAGUI | | resourceIds | string[] | all registered agents | Filter which agents from the global AgentRegistry are exposed (if agents is omitted) | | path | string | "/copilotkit" | Path to mount the CopilotKit endpoint |

Documentation

• VoltAgent Documentation
• AG-UI Protocol
• CopilotKit

License

Licensed under the MIT License, Copyright © 2026-present VoltAgent.