diff --git a/website/astro.config.mjs b/website/astro.config.mjs
index 691dda32..3f05160f 100644
--- a/website/astro.config.mjs
+++ b/website/astro.config.mjs
@@ -198,6 +198,7 @@ export default defineConfig({
slug: 'docs/integrations/agent-plugins',
},
'docs/integrations/acp',
+ 'docs/integrations/ag-ui',
'docs/integrations/local-models',
'docs/integrations/storage',
'docs/integrations/observability',
diff --git a/website/src/content/docs/docs/integrations/ag-ui.mdx b/website/src/content/docs/docs/integrations/ag-ui.mdx
new file mode 100644
index 00000000..e3cd00cf
--- /dev/null
+++ b/website/src/content/docs/docs/integrations/ag-ui.mdx
@@ -0,0 +1,938 @@
+---
+title: Connect an AI chat frontend to Bub with AG-UI
+description: Try Bub's experimental AG-UI support. Connect an AI chat frontend with examples for streaming replies, browser tools, and UI history.
+sidebar:
+ label: Web frontends with AG-UI
+ badge: { text: 'App', variant: 'note' }
+tableOfContents:
+ maxHeadingLevel: 2
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+The `bub-ag-ui` plugin connects Bub to a web chat frontend over AG-UI. You can stream replies and let Bub call tools in the browser. The integration is experimental.
+
+This guide connects a chat UI and uses a weather tool to plan an afternoon in San Francisco. Start with the assistant-ui tab if you do not already have a frontend.
+
+## Before you start {#before-you-start}
+
+- [Install the Bub application](/docs/getting-started/install/#app-install) and [configure a model](/docs/app/configure/).
+- Install Node.js and npm for the frontend.
+
+## 1. Install and start the plugin {#install}
+
+Install the plugin in the environment that runs Bub, then start the service:
+
+```bash
+bub install bub-ag-ui@main
+bub ag-ui --help
+bub ag-ui --host 127.0.0.1 --port 28201
+```
+
+Keep this terminal open. The frontend will send requests to `http://127.0.0.1:28201/agent` and receive streaming replies.
+
+## 2. Connect a frontend {#choose-ui}
+
+Choose one of the tabs below. Each example connects to the same Bub service, runs a `get_weather` tool in the browser, and saves the displayed conversation for page reloads. The weather data is a fixed demo forecast for San Francisco.
+
+The tabs use these shared files. Copy the files needed by your frontend after creating its project.
+
+
+Shared example files
+
+Save the weather tool and data as `src/scenario.json` for CopilotKit, OpenUI, and AI Elements. The assistant-ui example includes them in its provider.
+
+```json title="src/scenario.json"
+{
+ "name": "Weekend weather planner",
+ "tool": {
+ "name": "get_weather",
+ "description": "Return a fixed demonstration weather forecast for a city. This is sample data for UI compatibility testing, not live weather.",
+ "parameters": {
+ "type": "object",
+ "properties": {"city": {"type": "string", "description": "City to look up"}},
+ "required": ["city"],
+ "additionalProperties": false
+ }
+ },
+ "result": {
+ "city": "San Francisco",
+ "temperature_c": 18,
+ "condition": "Partly cloudy",
+ "source": "Fixed demo forecast; not live weather"
+ },
+ "prompt": "Call get_weather for San Francisco. Using that demo forecast, suggest a relaxed afternoon with a bookstore, coffee, and a sunset walk. Reply in English with the heading 'A slower afternoon', a three-row Markdown table (Time / Plan), and a short weather note. Keep it under 100 words. Use only get_weather; do not delegate or call other tools."
+}
+```
+
+For CopilotKit and OpenUI, add this `server` property to `defineConfig({...})` in `vite.config.ts`. It serves the frontend on port 3000 and forwards `/api/*` to Bub, removing the `/api` prefix. The other two tabs include their own proxy configuration.
+
+```typescript title="vite.config.ts (server property)"
+server: {
+ host: "localhost",
+ port: 3000,
+ strictPort: true,
+ proxy: {
+ "/api": {
+ target: "http://127.0.0.1:28201",
+ changeOrigin: true,
+ rewrite: (path) => path.replace(/^\/api/, ""),
+ },
+ },
+},
+```
+
+Save this storage helper as `app/demo-session.ts` for assistant-ui, or `src/demo-session.ts` for the other frontends. It keeps the thread ID, messages, and state in the browser's `sessionStorage`.
+
+```typescript title="demo-session.ts"
+import { HttpAgent, type Message } from "@ag-ui/client";
+
+type DemoSession = {
+ threadId: string;
+ messages: Message[];
+ state: HttpAgent["state"];
+};
+
+// Demo storage for one browser tab. A deployed app supplies its own storage.
+export function readDemoSession(key: string): DemoSession {
+ const saved = sessionStorage.getItem(key);
+ if (saved) return JSON.parse(saved) as DemoSession;
+ const session = { threadId: crypto.randomUUID(), messages: [], state: {} };
+ sessionStorage.setItem(key, JSON.stringify(session));
+ return session;
+}
+
+export function persistDemoSession(key: string, agent: HttpAgent) {
+ const save = () =>
+ sessionStorage.setItem(
+ key,
+ JSON.stringify({
+ threadId: agent.threadId,
+ messages: agent.messages,
+ state: agent.state,
+ }),
+ );
+ return agent.subscribe({
+ onRunFinalized: save,
+ });
+}
+```
+
+
+
+
+
+
+assistant-ui provides an AG-UI runtime for the connection and browser-tool calls.
+
+### Create the project {#assistant-ui-project}
+
+Use the [official Starter](https://www.assistant-ui.com/docs/cli), select the default template, and install the AG-UI runtime. Keep the Starter's `@assistant-ui/react` version.
+
+```bash
+npx assistant-ui@latest create bub-assistant-ui
+cd bub-assistant-ui
+npm install @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4
+```
+
+### Connect to Bub {#assistant-ui-connect}
+
+Save the shared helper as `app/demo-session.ts`. Add this rewrite to the configuration object in `next.config.ts`, keeping the Starter settings and `withAui` wrapper:
+
+```typescript title="next.config.ts (configuration property)"
+async rewrites() {
+ return [{ source: "/api/:path*", destination: "http://127.0.0.1:28201/:path*" }];
+},
+```
+
+Create `app/BubRuntimeProvider.tsx` to connect the runtime, restore displayed messages, and register the weather tool:
+
+
+app/BubRuntimeProvider.tsx
+
+```tsx title="app/BubRuntimeProvider.tsx"
+"use client";
+
+import { useEffect, useState, type ReactNode } from "react";
+import { HttpAgent } from "@ag-ui/client";
+import { useAgUiRuntime, fromAgUiMessages } from "@assistant-ui/react-ag-ui";
+import {
+ AssistantRuntimeProvider,
+ ExportedMessageRepository,
+ type ThreadHistoryAdapter,
+} from "@assistant-ui/react";
+import { readDemoSession, persistDemoSession } from "./demo-session";
+
+type Session = { agent: HttpAgent; history: ThreadHistoryAdapter };
+
+function ConnectedRuntime({ session, children }: { session: Session; children: ReactNode }) {
+ const runtime = useAgUiRuntime({ agent: session.agent, adapters: { history: session.history } });
+ useEffect(
+ () =>
+ runtime.registerModelContextProvider({
+ getModelContext: () => ({
+ tools: {
+ get_weather: {
+ description: "Return a fixed demo forecast for San Francisco, not live weather.",
+ parameters: {
+ type: "object",
+ properties: { city: { type: "string" } },
+ required: ["city"],
+ },
+ execute: async () => ({
+ city: "San Francisco",
+ temperature_c: 18,
+ condition: "Partly cloudy",
+ source: "Fixed demo forecast; not live weather",
+ }),
+ },
+ },
+ }),
+ }),
+ [runtime],
+ );
+ return {children};
+}
+
+export function BubRuntimeProvider({ children }: { children: ReactNode }) {
+ const [session, setSession] = useState(null);
+ const [error, setError] = useState("");
+ useEffect(() => {
+ try {
+ const key = "bub-assistant-ui-demo";
+ const saved = readDemoSession(key);
+ const agent = new HttpAgent({
+ url: "/api/agent",
+ threadId: saved.threadId,
+ initialMessages: saved.messages,
+ initialState: saved.state,
+ });
+ const subscription = persistDemoSession(key, agent);
+ setSession({
+ agent,
+ history: {
+ load: async () => ({
+ ...ExportedMessageRepository.fromArray(fromAgUiMessages(saved.messages)),
+ state: saved.state,
+ }),
+ // The SDK subscription saves the complete messages/state snapshot.
+ append: async () => {},
+ },
+ });
+ return () => subscription.unsubscribe();
+ } catch (cause) {
+ setError(String(cause));
+ }
+ }, []);
+ if (error) return
{error}
;
+ if (!session) return
Loading conversation...
;
+ return {children};
+}
+```
+
+
+
+Replace `app/assistant.tsx` with the following and keep the existing `app/page.tsx` entry:
+
+```tsx title="app/assistant.tsx"
+"use client";
+
+import { BubRuntimeProvider } from "./BubRuntimeProvider";
+import { Thread } from "@/components/assistant-ui/elements/thread.aui";
+
+export const Assistant = () => (
+
+
+
+);
+```
+
+### Start the frontend {#assistant-ui-start}
+
+```bash
+npm run dev -- --hostname localhost --port 3000
+```
+
+
+
+
+This example uses `CopilotChat` and `useFrontendTool` with the development-only `agents__unsafe_dev_only` connection. For deployment, use a [CopilotKit runtime](https://docs.copilotkit.ai/backend/self-managed-agents), as shown in the [LangChain integration guide](https://docs.langchain.com/oss/python/langchain/frontend/integrations/copilotkit).
+
+### Create the project {#copilotkit-project}
+
+Create a React project and install the matching CopilotKit and AG-UI versions:
+
+```bash
+npm create vite@latest bub-copilotkit -- --template react-ts
+cd bub-copilotkit
+npm install
+npm install @copilotkit/react-core@1.85.0 @ag-ui/client@1.0.2 @ag-ui/core@1.0.2 rxjs@7.8.1 zod@3.25.76
+```
+
+### Connect to Bub {#copilotkit-connect}
+
+Save the shared files as `src/demo-session.ts` and `src/scenario.json`, then add the shared Vite proxy. Create `src/BubHttpAgent.ts` to restore displayed messages from browser storage without requesting them from Bub:
+
+
+src/BubHttpAgent.ts
+
+```typescript title="src/BubHttpAgent.ts"
+import { HttpAgent } from "@ag-ui/client";
+import { EventType, type BaseEvent, type RunAgentInput } from "@ag-ui/core";
+import { Observable } from "rxjs";
+import { readDemoSession } from "./demo-session";
+
+export const storageKey = "bub-copilotkit-demo";
+
+export class BubHttpAgent extends HttpAgent {
+ protected connect(input: RunAgentInput): Observable {
+ return new Observable((subscriber) => {
+ const saved = readDemoSession(storageKey);
+ // Local UI hydration only; no request or model run is started here.
+ subscriber.next({
+ type: EventType.RUN_STARTED,
+ threadId: input.threadId,
+ runId: input.runId,
+ } as BaseEvent);
+ subscriber.next({ type: EventType.MESSAGES_SNAPSHOT, messages: saved.messages } as BaseEvent);
+ subscriber.next({ type: EventType.STATE_SNAPSHOT, snapshot: saved.state } as BaseEvent);
+ subscriber.next({
+ type: EventType.RUN_FINISHED,
+ threadId: input.threadId,
+ runId: input.runId,
+ } as BaseEvent);
+ subscriber.complete();
+ });
+ }
+}
+```
+
+
+
+Replace `src/main.tsx`. `useFrontendTool` registers the weather tool and returns its result to Bub:
+
+```tsx title="src/main.tsx"
+import { createRoot } from "react-dom/client";
+import { BubHttpAgent, storageKey } from "./BubHttpAgent";
+import { readDemoSession, persistDemoSession } from "./demo-session";
+import { CopilotChat, CopilotKit, useFrontendTool } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-core/v2/styles.css";
+import { z } from "zod";
+import scenario from "./scenario.json";
+
+const saved = readDemoSession(storageKey);
+const threadId = saved.threadId;
+function WeatherChat() {
+ useFrontendTool({
+ name: scenario.tool.name,
+ description: scenario.tool.description,
+ parameters: z.object({ city: z.string() }),
+ handler: async ({ city }) => {
+ console.info("COMPAT_TOOL_EXECUTED", "get_weather", city);
+ return scenario.result;
+ },
+ });
+ return (
+
+
+
+ );
+}
+async function start() {
+ const bub = new BubHttpAgent({
+ agentId: "bub",
+ threadId,
+ url: "/api/agent",
+ initialMessages: saved.messages,
+ initialState: saved.state,
+ });
+ persistDemoSession(storageKey, bub);
+ createRoot(document.getElementById("root")!).render(
+
+
+ ,
+ );
+}
+start().catch((error) => {
+ console.error(error);
+ document.getElementById("root")!.textContent = String(error);
+});
+```
+
+### Start the frontend {#copilotkit-start}
+
+```bash
+npm run dev
+```
+
+
+
+
+OpenUI provides `AgentInterface` and an AG-UI parser. The application code below connects them to Bub and handles browser-tool calls.
+
+### Create the project {#openui-project}
+
+Create a React project and install OpenUI:
+
+```bash
+npm create vite@latest bub-openui -- --template react-ts
+cd bub-openui
+npm install
+npm install @openuidev/react-ui@0.18.5 @openuidev/react-headless@0.18.5 @openuidev/react-lang@1.1.0 @ag-ui/client@1.0.4 zod@4 zustand@4
+```
+
+### Connect to Bub {#openui-connect}
+
+Save the shared files as `src/demo-session.ts` and `src/scenario.json`, then add the shared Vite proxy. Replace `src/main.tsx`:
+
+
+src/main.tsx
+
+```tsx title="src/main.tsx"
+import { createRoot } from "react-dom/client";
+import { AgentInterface } from "@openuidev/react-ui";
+import {
+ agUIAdapter,
+ type ChatLLM,
+ type ChatStorage,
+ type Message as OpenMessage,
+} from "@openuidev/react-headless";
+import { HttpAgent, type Message } from "@ag-ui/client";
+import "@openuidev/react-ui/styles/index.css";
+import scenario from "./scenario.json";
+import { readDemoSession, persistDemoSession } from "./demo-session";
+
+const storageKey = "bub-openui-demo";
+const threadId = readDemoSession(storageKey).threadId;
+const baseThread = { id: threadId, title: "Weekend weather planner", createdAt: Date.now() };
+const storage: ChatStorage = {
+ thread: {
+ listThreads: async () => ({ threads: [baseThread] }),
+ createThread: async () => baseThread,
+ getMessages: async () => readDemoSession(storageKey).messages as OpenMessage[],
+ updateThread: async (thread) => thread,
+ deleteThread: async () => {
+ throw Error("Deletion is not enabled in this compatibility demo");
+ },
+ },
+};
+
+// OpenUI supplies the UI and AG-UI parser. This application bridge owns browser
+// tool execution and continuation; neither package is patched.
+const llm: ChatLLM = {
+ streamProtocol: agUIAdapter(),
+ send: async ({ messages, signal }) => {
+ const agent = new HttpAgent({
+ url: "/api/agent",
+ threadId,
+ initialMessages: messages as Message[],
+ initialState: readDemoSession(storageKey).state,
+ });
+ const subscription = persistDemoSession(storageKey, agent);
+ const encoder = new TextEncoder();
+ const stream = new ReadableStream({
+ start(controller) {
+ const emit = (event: unknown) =>
+ controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
+ const abort = () => agent.abortRun();
+ signal.addEventListener("abort", abort, { once: true });
+ (async () => {
+ try {
+ const executed = new Set();
+ for (let round = 0; round < 4; round++) {
+ await agent.runAgent(
+ { tools: [scenario.tool] },
+ {
+ onEvent: ({ event }) => {
+ emit(event);
+ },
+ },
+ );
+ if (signal.aborted) break;
+ const answered = new Set(
+ agent.messages.filter((m) => m.role === "tool").map((m) => m.toolCallId),
+ );
+ const pending = agent.messages
+ .flatMap((m) => (m.role === "assistant" ? (m.toolCalls ?? []) : []))
+ .filter((t) => !answered.has(t.id));
+ if (!pending.length) break;
+ for (const call of pending) {
+ if (call.function.name !== "get_weather" || executed.has(call.id))
+ throw Error(`Unsupported or repeated browser tool: ${call.function.name}`);
+ const args = JSON.parse(call.function.arguments);
+ if (typeof args.city !== "string" || args.city.toLowerCase() !== "san francisco")
+ throw Error("Demo fixture supports San Francisco only");
+ executed.add(call.id);
+ console.info("COMPAT_TOOL_EXECUTED", "get_weather", args.city);
+ const message = {
+ id: crypto.randomUUID(),
+ role: "tool" as const,
+ toolCallId: call.id,
+ content: JSON.stringify(scenario.result),
+ };
+ agent.addMessage(message);
+ emit({
+ type: "TOOL_CALL_RESULT",
+ messageId: message.id,
+ toolCallId: call.id,
+ content: message.content,
+ role: "tool",
+ });
+ }
+ if (round === 3) throw Error("Browser tool continuation limit exceeded");
+ }
+ controller.close();
+ } catch (error) {
+ console.error(error);
+ controller.error(error);
+ } finally {
+ signal.removeEventListener("abort", abort);
+ subscription.unsubscribe();
+ }
+ })();
+ },
+ cancel() {
+ agent.abortRun();
+ },
+ });
+ return new Response(stream, { headers: { "Content-Type": "text/event-stream" } });
+ },
+};
+createRoot(document.getElementById("root")!).render(
+
+
+
,
+);
+```
+
+
+
+This example keeps one thread in the sidebar and disables deletion. Its default renderer displays Markdown tables as plain text. To customize the UI, see the [OpenUI agent example](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra).
+
+### Start the frontend {#openui-start}
+
+```bash
+npm run dev
+```
+
+
+
+
+AI Elements provides the UI components. The application uses `HttpAgent` to connect them to Bub and handle browser-tool calls.
+
+### Create the project {#ai-elements-project}
+
+Create a React project and install the AG-UI client and Tailwind CSS:
+
+```bash
+npm create vite@latest bub-ai-elements -- --template react-ts
+cd bub-ai-elements
+npm install
+npm install @ag-ui/client@1.0.4 ai@7.0.153
+npm install -D tailwindcss @tailwindcss/vite @types/node
+```
+
+### Connect to Bub {#ai-elements-connect}
+
+Replace `vite.config.ts` to configure React, Tailwind, the `@` alias, and the Bub proxy:
+
+```typescript title="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { fileURLToPath } from "node:url";
+
+export default defineConfig({
+ plugins: [react(), tailwindcss()],
+ resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } },
+ server: {
+ host: "localhost", port: 3000, strictPort: true,
+ proxy: {
+ "/api": {
+ target: "http://127.0.0.1:28201",
+ changeOrigin: true,
+ rewrite: (path) => path.replace(/^\/api/, ""),
+ },
+ },
+ },
+});
+```
+
+Add these properties to `compilerOptions` in both `tsconfig.json` and `tsconfig.app.json`:
+
+```json
+"paths": { "@/*": ["./src/*"] },
+"resolveJsonModule": true
+```
+
+Replace `src/index.css` with the following, then install the UI components with Radix:
+
+```css title="src/index.css"
+@import "tailwindcss";
+```
+
+```bash
+npx shadcn@latest init --base radix
+npx ai-elements@latest add conversation message prompt-input tool suggestion
+```
+
+Save the shared files as `src/demo-session.ts` and `src/scenario.json`, then replace `src/main.tsx`. For component usage, see the [AI Elements guide](https://docs.langchain.com/oss/python/langchain/frontend/integrations/ai-elements).
+
+
+src/main.tsx
+
+```tsx title="src/main.tsx"
+import { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { HttpAgent, type Message as AgMessage } from "@ag-ui/client";
+import {
+ Conversation,
+ ConversationContent,
+ ConversationScrollButton,
+} from "@/components/ai-elements/conversation";
+import { Message, MessageContent, MessageResponse } from "@/components/ai-elements/message";
+import {
+ PromptInput,
+ PromptInputBody,
+ PromptInputTextarea,
+ PromptInputFooter,
+ PromptInputSubmit,
+ PromptInputTools,
+ type PromptInputMessage,
+} from "@/components/ai-elements/prompt-input";
+import {
+ Tool,
+ ToolHeader,
+ ToolContent,
+ ToolInput,
+ ToolOutput,
+} from "@/components/ai-elements/tool";
+import { Suggestion, Suggestions } from "@/components/ai-elements/suggestion";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import type { ChatStatus } from "ai";
+import scenario from "./scenario.json";
+import { readDemoSession, persistDemoSession } from "./demo-session";
+import "./index.css";
+
+const storageKey = "bub-ai-elements-demo";
+function Chat({ agent }: { agent: HttpAgent }) {
+ const [messages, setMessages] = useState(agent.messages);
+ const [status, setStatus] = useState("ready");
+ const [text, setText] = useState("");
+ const [error, setError] = useState("");
+ useEffect(
+ () =>
+ agent.subscribe({
+ onMessagesChanged: ({ messages }) => setMessages([...messages]),
+ onTextMessageContentEvent: () => {
+ setStatus("streaming");
+ },
+ }).unsubscribe,
+ [agent],
+ );
+ async function send(value: string) {
+ if (!value.trim() || status === "submitted" || status === "streaming") return;
+ setText("");
+ setError("");
+ setStatus("submitted");
+ agent.addMessage({ id: crypto.randomUUID(), role: "user", content: value });
+ try {
+ const executed = new Set();
+ for (let round = 0; round < 4; round++) {
+ await agent.runAgent({ tools: [scenario.tool] });
+ const answered = new Set(
+ agent.messages.filter((m) => m.role === "tool").map((m) => m.toolCallId),
+ );
+ const pending = agent.messages
+ .flatMap((m) => (m.role === "assistant" ? (m.toolCalls ?? []) : []))
+ .filter((t) => !answered.has(t.id));
+ if (!pending.length) break;
+ for (const call of pending) {
+ if (call.function.name !== "get_weather" || executed.has(call.id))
+ throw Error(`Unsupported or repeated browser tool: ${call.function.name}`);
+ const args = JSON.parse(call.function.arguments);
+ if (typeof args.city !== "string" || args.city.toLowerCase() !== "san francisco")
+ throw Error("Demo fixture supports San Francisco only");
+ executed.add(call.id);
+ console.info("COMPAT_TOOL_EXECUTED", "get_weather", args.city);
+ agent.addMessage({
+ id: crypto.randomUUID(),
+ role: "tool",
+ toolCallId: call.id,
+ content: JSON.stringify(scenario.result),
+ });
+ }
+ if (round === 3) throw Error("Browser tool continuation limit exceeded");
+ }
+ setStatus("ready");
+ } catch (e) {
+ setError(String(e));
+ setStatus("error");
+ console.error(e);
+ }
+ }
+ const busy = status === "submitted" || status === "streaming";
+ // Conversation / message / composer layout adapted from the official chatbot
+ // example. Mock streaming and unsupported model/search/attachment controls are
+ // removed. AG-UI is an explicit application bridge, not an AI Elements runtime.
+ return (
+
+ );
+}
+async function start() {
+ const saved = readDemoSession(storageKey);
+ const agent = new HttpAgent({
+ url: "/api/agent",
+ threadId: saved.threadId,
+ initialMessages: saved.messages,
+ initialState: saved.state,
+ });
+ persistDemoSession(storageKey, agent);
+ createRoot(document.getElementById("root")!).render(
+
+
+ ,
+ );
+}
+start().catch((error) => {
+ console.error(error);
+ document.getElementById("root")!.textContent = String(error);
+});
+```
+
+
+
+### Start the frontend {#ai-elements-start}
+
+```bash
+npm run dev
+```
+
+
+
+
+## 3. Try the conversation {#verify}
+
+With one frontend running, open `http://localhost:3000` and send this request:
+
+```text
+Call get_weather for San Francisco, then suggest an afternoon plan using the demo forecast.
+```
+
+Bub calls the browser tool and uses its result to suggest an afternoon plan. The forecast is 18°C and partly cloudy; it is demo data, not live weather.
+
+After the reply finishes, reload the same browser tab. Your messages should still be visible. In OpenUI, select the saved thread from the sidebar. Ask which city and temperature you discussed to continue the conversation.
+
+## Conversations and UI history {#tools-and-history}
+
+The examples save the thread ID, messages, and state in `sessionStorage`. Reloading restores the displayed conversation. A new browser tab without saved messages cannot retrieve earlier display history from Bub; the AG-UI service only exposes `POST /agent`.
+
+Bub manages the model's conversation context. Keep the same `threadId` to continue it, and retain Bub's default files or [database storage](/docs/integrations/storage/) across backend restarts. Browser storage restores the UI; it cannot recover deleted Bub context or unfinished tool calls. Keep the backend running until the reply finishes. The default turn timeout is 600 seconds, including time spent waiting for browser tools.
+
+To start a new conversation, clear the example's storage key and reload. Editing earlier messages and regenerating replies are unsupported; disable those actions if your UI template exposes them. For deployment, replace the demo storage with storage and user isolation suitable for your application.
+
+## Use HttpAgent in your own frontend {#connect}
+
+If you are building your own UI, use `@ag-ui/client` for the connection and message state. This plain TypeScript example displays streamed text and creates a new thread on each reload.
+
+
+Minimal browser chat
+
+Create a Vite project:
+
+```bash
+npm create vite@latest bub-chat -- --template vanilla-ts
+cd bub-chat
+npm install
+npm install @ag-ui/client@1.0.4
+```
+
+Replace `src/main.ts`:
+
+```typescript title="src/main.ts"
+import { HttpAgent } from "@ag-ui/client";
+
+const root = document.querySelector("#app")!;
+root.innerHTML = `
+
Bub chat
+
+
+
+`;
+
+const form = root.querySelector("form")!;
+const input = root.querySelector("input")!;
+const button = root.querySelector("button")!;
+const messages = root.querySelector("#messages")!;
+const status = root.querySelector("#status")!;
+const agent = new HttpAgent({
+ url: "http://127.0.0.1:28201/agent",
+ threadId: crypto.randomUUID(),
+});
+
+agent.subscribe({
+ onMessagesChanged: ({ messages: current }) => {
+ messages.textContent = current
+ .map((message) => `${message.role}: ${message.content ?? ""}`)
+ .join("\n\n");
+ },
+});
+
+form.addEventListener("submit", async (event) => {
+ event.preventDefault();
+ const content = input.value.trim();
+ if (!content || button.disabled) return;
+
+ agent.addMessage({ id: crypto.randomUUID(), role: "user", content });
+ input.value = "";
+ button.disabled = true;
+ status.textContent = "Running...";
+ try {
+ await agent.runAgent({}, {
+ onRunErrorEvent: ({ event }) => {
+ status.textContent = event.message;
+ },
+ });
+ if (status.textContent === "Running...") status.textContent = "Ready";
+ } catch (error) {
+ status.textContent = String(error);
+ } finally {
+ button.disabled = false;
+ input.focus();
+ }
+});
+```
+
+Start Vite and open `http://localhost:3000`:
+
+```bash
+npm run dev -- --host localhost --port 3000 --strictPort
+```
+
+
+
+This example calls Bub directly. Bub allows `http://localhost:3000` by default. For another frontend origin, set `BUB_AG_UI_ORIGINS` before starting the backend:
+
+```bash
+export BUB_AG_UI_ORIGINS='["http://localhost:5173"]'
+```
+
+Match the scheme, hostname, and port exactly. `localhost` and `127.0.0.1` are different origins.
+
+## Deploy the service {#hosting}
+
+When listening on a non-loopback address, set `BUB_AG_UI_TOKEN` and send `Authorization: Bearer ` with requests. Keep the token on the application server. Configure `BUB_AG_UI_ORIGINS` if browsers connect to Bub directly.
+
+A shared token represents one user identity. For multi-user authentication and gateway setup, follow the [plugin README](https://github.com/bubbuild/bub-contrib/blob/main/packages/bub-ag-ui/README.md).
+
+## Troubleshooting {#troubleshooting}
+
+| Symptom | Check |
+| --- | --- |
+| `ag-ui` command is missing | Run `bub ag-ui --help` in the environment where the plugin is installed. |
+| Browser requests fail | Check the frontend proxy, or match `BUB_AG_UI_ORIGINS` to the exact origin for direct connections. |
+| Requests return 401 or 403 | Check the Bearer header and authentication configuration. |
+| No reply appears | Test the model with `bub run "Say hello"` and check backend logs. |
+| A tool call has no follow-up reply | Check that the frontend returns the tool result and continues the conversation. |
+| A run returns `RUN_ERROR` | Read the event's error message and check the backend logs. |
diff --git a/website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx b/website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx
new file mode 100644
index 00000000..882c534b
--- /dev/null
+++ b/website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx
@@ -0,0 +1,938 @@
+---
+title: 通过 AG-UI 为 Bub 接入 AI 聊天前端
+description: 尝试 Bub 的实验性 AG-UI 集成,按示例接入 AI 聊天前端,处理流式回复、浏览器工具和应用保存的界面历史。
+sidebar:
+ label: 通过 AG-UI 接入 Web 前端
+ badge: { text: '应用', variant: 'note' }
+tableOfContents:
+ maxHeadingLevel: 2
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+`bub-ag-ui` 插件通过 AG-UI 将 Bub 接入 Web 聊天前端,让你接收流式回复,并让 Bub 调用浏览器中的工具。这项集成仍处于实验阶段。
+
+本指南接入一个聊天界面,再用天气工具规划在旧金山的下午行程。如果还没有选定前端,可以从 assistant-ui 标签页开始。
+
+## 开始之前 {#before-you-start}
+
+- 已[安装 Bub 应用](/zh-cn/docs/getting-started/install/#app-install),并[配置可用模型](/zh-cn/docs/app/configure/)。
+- 安装 Node.js 和 npm,用于运行前端。
+
+## 1. 安装并启动插件 {#install}
+
+将插件安装到运行 Bub 的环境中,然后启动服务:
+
+```bash
+bub install bub-ag-ui@main
+bub ag-ui --help
+bub ag-ui --host 127.0.0.1 --port 28201
+```
+
+保持这个终端运行。前端将向 `http://127.0.0.1:28201/agent` 发送请求并接收流式回复。
+
+## 2. 连接前端 {#choose-ui}
+
+选择下方的一个标签页。每个示例都连接同一个 Bub 服务,在浏览器中执行 `get_weather` 工具,并保存界面中的对话以便刷新后恢复。天气数据是固定的旧金山演示预报。
+
+各标签页用到以下共用文件。创建项目后,复制所选前端需要的文件。
+
+
+共用示例文件
+
+CopilotKit、OpenUI 和 AI Elements 将天气工具及数据保存为 `src/scenario.json`。assistant-ui 示例已在 provider 中包含这些内容。
+
+```json title="src/scenario.json"
+{
+ "name": "Weekend weather planner",
+ "tool": {
+ "name": "get_weather",
+ "description": "Return a fixed demonstration weather forecast for a city. This is sample data for UI compatibility testing, not live weather.",
+ "parameters": {
+ "type": "object",
+ "properties": {"city": {"type": "string", "description": "City to look up"}},
+ "required": ["city"],
+ "additionalProperties": false
+ }
+ },
+ "result": {
+ "city": "San Francisco",
+ "temperature_c": 18,
+ "condition": "Partly cloudy",
+ "source": "Fixed demo forecast; not live weather"
+ },
+ "prompt": "Call get_weather for San Francisco. Using that demo forecast, suggest a relaxed afternoon with a bookstore, coffee, and a sunset walk. Reply in English with the heading 'A slower afternoon', a three-row Markdown table (Time / Plan), and a short weather note. Keep it under 100 words. Use only get_weather; do not delegate or call other tools."
+}
+```
+
+CopilotKit 和 OpenUI 在 `vite.config.ts` 的 `defineConfig({...})` 中添加以下 `server` 属性。前端运行在 3000 端口,代理将 `/api/*` 去掉 `/api` 前缀后转发给 Bub。另外两个标签页包含各自的代理配置。
+
+```typescript title="vite.config.ts (server property)"
+server: {
+ host: "localhost",
+ port: 3000,
+ strictPort: true,
+ proxy: {
+ "/api": {
+ target: "http://127.0.0.1:28201",
+ changeOrigin: true,
+ rewrite: (path) => path.replace(/^\/api/, ""),
+ },
+ },
+},
+```
+
+将存储辅助文件保存为 `app/demo-session.ts`(assistant-ui)或 `src/demo-session.ts`(其他前端)。它通过浏览器的 `sessionStorage` 保存会话 ID、消息和状态。
+
+```typescript title="demo-session.ts"
+import { HttpAgent, type Message } from "@ag-ui/client";
+
+type DemoSession = {
+ threadId: string;
+ messages: Message[];
+ state: HttpAgent["state"];
+};
+
+// Demo storage for one browser tab. A deployed app supplies its own storage.
+export function readDemoSession(key: string): DemoSession {
+ const saved = sessionStorage.getItem(key);
+ if (saved) return JSON.parse(saved) as DemoSession;
+ const session = { threadId: crypto.randomUUID(), messages: [], state: {} };
+ sessionStorage.setItem(key, JSON.stringify(session));
+ return session;
+}
+
+export function persistDemoSession(key: string, agent: HttpAgent) {
+ const save = () =>
+ sessionStorage.setItem(
+ key,
+ JSON.stringify({
+ threadId: agent.threadId,
+ messages: agent.messages,
+ state: agent.state,
+ }),
+ );
+ return agent.subscribe({
+ onRunFinalized: save,
+ });
+}
+```
+
+
+
+
+
+
+assistant-ui 提供 AG-UI runtime,负责连接和浏览器工具调用。
+
+### 创建项目 {#assistant-ui-project}
+
+通过[官方 Starter](https://www.assistant-ui.com/docs/cli)创建项目,选择默认模板,再安装 AG-UI runtime。保留 Starter 安装的 `@assistant-ui/react` 版本。
+
+```bash
+npx assistant-ui@latest create bub-assistant-ui
+cd bub-assistant-ui
+npm install @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4
+```
+
+### 连接 Bub {#assistant-ui-connect}
+
+将共用辅助文件保存为 `app/demo-session.ts`。在 `next.config.ts` 的配置对象中添加以下 rewrite,保留 Starter 原有配置和 `withAui` 包装:
+
+```typescript title="next.config.ts (configuration property)"
+async rewrites() {
+ return [{ source: "/api/:path*", destination: "http://127.0.0.1:28201/:path*" }];
+},
+```
+
+创建 `app/BubRuntimeProvider.tsx`,接入 runtime、恢复界面消息并注册天气工具:
+
+
+app/BubRuntimeProvider.tsx
+
+```tsx title="app/BubRuntimeProvider.tsx"
+"use client";
+
+import { useEffect, useState, type ReactNode } from "react";
+import { HttpAgent } from "@ag-ui/client";
+import { useAgUiRuntime, fromAgUiMessages } from "@assistant-ui/react-ag-ui";
+import {
+ AssistantRuntimeProvider,
+ ExportedMessageRepository,
+ type ThreadHistoryAdapter,
+} from "@assistant-ui/react";
+import { readDemoSession, persistDemoSession } from "./demo-session";
+
+type Session = { agent: HttpAgent; history: ThreadHistoryAdapter };
+
+function ConnectedRuntime({ session, children }: { session: Session; children: ReactNode }) {
+ const runtime = useAgUiRuntime({ agent: session.agent, adapters: { history: session.history } });
+ useEffect(
+ () =>
+ runtime.registerModelContextProvider({
+ getModelContext: () => ({
+ tools: {
+ get_weather: {
+ description: "Return a fixed demo forecast for San Francisco, not live weather.",
+ parameters: {
+ type: "object",
+ properties: { city: { type: "string" } },
+ required: ["city"],
+ },
+ execute: async () => ({
+ city: "San Francisco",
+ temperature_c: 18,
+ condition: "Partly cloudy",
+ source: "Fixed demo forecast; not live weather",
+ }),
+ },
+ },
+ }),
+ }),
+ [runtime],
+ );
+ return {children};
+}
+
+export function BubRuntimeProvider({ children }: { children: ReactNode }) {
+ const [session, setSession] = useState(null);
+ const [error, setError] = useState("");
+ useEffect(() => {
+ try {
+ const key = "bub-assistant-ui-demo";
+ const saved = readDemoSession(key);
+ const agent = new HttpAgent({
+ url: "/api/agent",
+ threadId: saved.threadId,
+ initialMessages: saved.messages,
+ initialState: saved.state,
+ });
+ const subscription = persistDemoSession(key, agent);
+ setSession({
+ agent,
+ history: {
+ load: async () => ({
+ ...ExportedMessageRepository.fromArray(fromAgUiMessages(saved.messages)),
+ state: saved.state,
+ }),
+ // The SDK subscription saves the complete messages/state snapshot.
+ append: async () => {},
+ },
+ });
+ return () => subscription.unsubscribe();
+ } catch (cause) {
+ setError(String(cause));
+ }
+ }, []);
+ if (error) return