From 8cc6f2818450edd395b88f80211a62137f5d0a69 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 11 Nov 2026 02:53:31 +0800 Subject: [PATCH 1/3] docs: add AG-UI frontend integration guide --- website/astro.config.mjs | 1 + .../content/docs/docs/integrations/ag-ui.mdx | 945 ++++++++++++++++++ .../docs/zh-cn/docs/integrations/ag-ui.mdx | 945 ++++++++++++++++++ 3 files changed, 1891 insertions(+) create mode 100644 website/src/content/docs/docs/integrations/ag-ui.mdx create mode 100644 website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx 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..4ce320e1 --- /dev/null +++ b/website/src/content/docs/docs/integrations/ag-ui.mdx @@ -0,0 +1,945 @@ +--- +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' } +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Bub's AG-UI integration is experimental. The `bub-ag-ui` plugin streams replies and tool calls to a web chat frontend. Bub manages model context; your application displays messages, handles browser tools, and saves UI history. + +For a first chat, [start the plugin](#install), then follow the assistant-ui tab below. Each tab includes the setup and application adapter code for that 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 the terminal open. The service accepts AG-UI requests at `http://127.0.0.1:28201/agent` and returns an SSE event stream. The frontend examples below connect to this service. + +## 2. Connect a frontend {#choose-ui} + +Choose a frontend for your project: + +| Frontend | Integration | +| --- | --- | +| assistant-ui | assistant-ui's AG-UI runtime connects to Bub; an application history adapter restores the chat UI. | +| CopilotKit | React chat and frontend-tool APIs connect through an AG-UI agent. | +| OpenUI | `AgentInterface` and its AG-UI parser work with an application adapter for tools and history. | +| AI Elements | UI components render messages and tool state supplied by an `HttpAgent` bridge. | + +The examples use a browser tool named `get_weather`, which returns a fixed San Francisco forecast. The tool definition and data are shared by the three Vite projects. Save the following as `src/scenario.json` after creating your project; the assistant-ui provider includes it inline. + +
+Weather tool and sample data + +```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 the generated `vite.config.ts`. It serves the frontend on port 3000 and forwards `/api/*` to Bub after removing the `/api` prefix. The AI Elements tab includes this proxy in its full Vite configuration; assistant-ui uses a Next.js rewrite. + +
+Vite 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/, ""), + }, + }, +}, +``` + +
+ +Each example keeps a stable `threadId` and saves SDK messages and shared state in `sessionStorage` after each run. Reloading the same browser tab restores the chat UI through `initialMessages` and `initialState`. This is demo storage for the frontend; Bub manages its own session context. A deployed application needs its own UI storage and user isolation. + +These examples support new messages and browser-tool continuation. Editing earlier messages and regenerating replies are unsupported. Disable those actions if your UI template exposes them. + +Save the helper below as `demo-session.ts`: in `app/` for assistant-ui, or in `src/` for the three Vite projects. + +
+demo-session.ts + +```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, + }); +} +``` + +
+ + + + +Create a project with the [official Starter](https://www.assistant-ui.com/docs/cli), select the default template, and install the AG-UI runtime: + +```bash +npx assistant-ui@latest create bub-assistant-ui +cd bub-assistant-ui +npm install @assistant-ui/react@0.15.33 @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4 +``` + +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`. The provider loads messages from the application’s demo storage, supplies them to the history adapter, and registers the weather tool. An SDK subscription saves messages and state when a run ends. + +
+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: + +```bash +npm run dev -- --hostname localhost --port 3000 +``` + +
+ + +For local development, CopilotKit can connect directly through `agents__unsafe_dev_only`. For deployment, use a [CopilotKit runtime](https://docs.copilotkit.ai/backend/self-managed-agents) between the React app and Bub, as illustrated in the [LangChain integration guide](https://docs.langchain.com/oss/python/langchain/frontend/integrations/copilotkit). + +Create the 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 +``` + +Add the shared Vite proxy and `src/scenario.json`. Create `src/BubHttpAgent.ts` to read an application snapshot during CopilotKit’s connect phase. These events restore the UI without making a backend request or starting a model run. + +
+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: + +```bash +npm run dev +``` + +
+ + +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 +``` + +Add the shared Vite proxy and `src/scenario.json`, then replace `src/main.tsx` with the code below. `AgentInterface` renders the chat, and `agUIAdapter()` parses the events. The application supplies `ChatStorage` for demo storage and `ChatLLM.send` for requests and browser-tool continuation. + +
+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 provides one saved thread and disables deletion. Its default renderer displays Markdown tables as plain text. For a different layout, see the [OpenUI agent example](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra). + +Start the frontend: + +```bash +npm run dev +``` + +
+ + +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 +``` + +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. The installer will add theme styles and component dependencies. + +```css title="src/index.css" +@import "tailwindcss"; +``` + +```bash +npx shadcn@latest init +npx ai-elements@latest add conversation message prompt-input tool suggestion +``` + +Save the shared fixture as `src/scenario.json` and replace `src/main.tsx` with the code below. It subscribes to `HttpAgent` messages and maps text and tool calls into AI Elements components. The application also sends tool results and starts continuation runs. See the [AI Elements guide](https://docs.langchain.com/oss/python/langchain/frontend/integrations/ai-elements) for component usage. + +
+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 ( +
+ + + {messages + .filter((m) => m.role === "user" || m.role === "assistant") + .map((message) => ( + +
+ {message.role === "assistant" && + message.toolCalls?.map((call) => { + const result = messages.find( + (m) => m.role === "tool" && m.toolCallId === call.id, + ); + let input: unknown = {}; + try { + input = JSON.parse(call.function.arguments || "{}"); + } catch { + input = call.function.arguments; + } + return ( + + + + + {result && } + + + ); + })} + {typeof message.content === "string" && message.content && ( + + {message.content} + + )} +
+
+ ))} + {error && ( +

+ {error} +

+ )} +
+ +
+
+ {!messages.length && ( + + void send(scenario.prompt)} + /> + + )} +
+ send(message.text)}> + + setText(e.target.value)} value={text} /> + + + + + Bub · AG-UI bridge · Demo forecast + + + agent.abortRun()} + /> + + +
+
+
+ ); +} +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: + +```bash +npm run dev +``` + +
+
+ +## 3. Send a message and continue after a reload {#verify} + +Open `http://localhost:3000` with one frontend running and send the following request: + +```text +Call get_weather for San Francisco, then suggest an afternoon plan using the demo forecast. +``` + +Bub requests the browser tool, receives its result, and streams a reply. The OpenUI and AI Elements examples accept San Francisco only and stop after at most four continuation rounds; these limits belong to the example code. + +After the reply finishes, reload the same browser tab, then ask a follow-up question. The application restores the displayed messages and shared state from `sessionStorage`; the saved `threadId` continues the existing Bub session. A fresh client without saved messages cannot reconstruct the earlier display history from Bub. In OpenUI, select the thread from the sidebar. Clearing the example's storage key starts a new conversation on the next reload. + +A persistent Bub tape store preserves completed conversation context and session settings across backend restarts. Keep the same default files or [database storage](/docs/integrations/storage/) to continue those conversations. Pending tool calls and human-input interrupts require the live execution and cannot resume after a restart. A browser snapshot restores the UI; it cannot recover pending execution or deleted server context. + +## Use HttpAgent in your own frontend {#connect} + +If you are building your own UI, `@ag-ui/client` can manage the AG-UI 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. + +## Tools and session context {#tools-and-history} + +A frontend declares browser tools in the run's `tools` list. When Bub calls one, the frontend executes it, adds a result with the matching `toolCallId`, and starts another AG-UI run on the same thread. Keep the frontend tool definitions unchanged and include results for every pending call. assistant-ui and CopilotKit handle continuation through their runtimes; the OpenUI and AI Elements examples implement the requests in application code. + +`RUN_FINISHED` ends one HTTP run, which can leave Bub waiting for frontend results or human input. The next `POST /agent` attaches to that same live native execution. Tool results or interrupt responses can continue it without resending history or adding a user message. In a batch containing both backend and frontend tools, Bub emits and records the results together after all calls finish. + +Return results or interrupt responses to the same adapter before `max_run_seconds` expires. Its default is 600 seconds for the entire native turn, including time spent waiting for the frontend. Restarting or shutting down the adapter, or reaching the timeout, ends that execution; submitting its results afterward returns `RUN_ERROR`. + +A human-input pause sends `STATE_SNAPSHOT`, then `RUN_FINISHED` with `outcome.type: "interrupt"`. Send a `resume` entry for every pending interrupt; Bub emits the decision result through its native `TOOL_CALL_RESULT` event. Repeating an accepted response does not execute the work again or replay the answer. Its receipt can survive a restart with a persistent tape store, but a pending call cannot. + +Bub executes the conversation through its native stream and selects model context from its tape, preserving session settings, loaded tools, and handoff boundaries. Keep message IDs stable when the SDK sends earlier messages again: accepted input is not appended twice, and echoed assistant messages or old tool results do not replace Bub's records or bring earlier context back across a handoff. + +Changing an accepted user message with the same ID returns `RUN_ERROR`; the adapter does not provide edit or regenerate branches. A request containing only old history and no new input also returns `RUN_ERROR` without running the model. + +Message events update the SDK incrementally at run start and human-input pauses, so sending only new input does not replace messages already held by the client. The adapter exposes only `POST /agent`, with no display-history or replay endpoint. + +`agent.abortRun()` closes an active HTTP request and cancels its execution. Once a paused HTTP run has finished, aborting that old request cannot cancel the waiting native turn. Resolve its tool calls, or cancel its human-input interrupts through `resume`, before the turn timeout. Cancellation does not undo completed tool side effects. + +## Deploy the service {#hosting} + +When listening on a non-loopback address, set `BUB_AG_UI_TOKEN`. Send `Authorization: Bearer ` with `POST /agent` requests. Keep the shared token on the application server, and configure `BUB_AG_UI_ORIGINS` if browsers connect to Bub directly. + +A shared token represents one user identity. For multiple users, embed the service with `create_app(..., authenticate=...)` and return a stable user identity from trusted authentication. Embedding and gateway setup are described in 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 its result carries the matching tool-call ID and that the frontend starts the next run. | +| A run returns `RUN_ERROR` | Read the event’s error message. If another request is executing on the thread, wait for it or close that request before retrying. | 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..c049c03f --- /dev/null +++ b/website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx @@ -0,0 +1,945 @@ +--- +title: 通过 AG-UI 为 Bub 接入 AI 聊天前端 +description: 尝试 Bub 的实验性 AG-UI 集成,按示例接入 AI 聊天前端,处理流式回复、浏览器工具和应用保存的界面历史。 +sidebar: + label: 通过 AG-UI 接入 Web 前端 + badge: { text: '应用', variant: 'note' } +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Bub 的 AG-UI 集成仍处于实验阶段。`bub-ag-ui` 插件将回复和工具调用以事件流发送到 Web 聊天前端。Bub 管理模型上下文,应用负责展示消息、执行浏览器工具并保存界面历史。 + +首次接入可以先[启动插件](#install),再按下方 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` 接收 AG-UI 请求,以 SSE 事件流返回回复。下方各前端示例都连接这个服务。 + +## 2. 连接前端 {#choose-ui} + +根据项目需要选择一个前端: + +| 前端 | 接入方式 | +| --- | --- | +| assistant-ui | 使用 assistant-ui 提供的 AG-UI runtime 连接 Bub,由应用的历史适配器恢复聊天界面。 | +| CopilotKit | 通过 AG-UI Agent 接入 React 聊天组件和前端工具 API。 | +| OpenUI | 使用 `AgentInterface` 和 AG-UI 解析器,由应用适配工具调用和历史记录。 | +| AI Elements | 由 `HttpAgent` 桥接消息和工具状态,交给 UI 组件渲染。 | + +示例使用名为 `get_weather` 的浏览器工具,返回固定的旧金山天气数据。三个 Vite 项目共用下方的工具定义和数据,创建项目后保存为 `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。AI Elements 的完整 Vite 配置已包含这个代理,assistant-ui 则使用 Next.js rewrite。 + +
+Vite 代理配置 + +```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/, ""), + }, + }, +}, +``` + +
+ +每个示例保留稳定的 `threadId`,并在每次 run 结束后将 SDK 消息和共享状态保存到 `sessionStorage`,以便在同一浏览器标签页刷新后,通过 `initialMessages` 和 `initialState` 恢复聊天界面。这是前端的演示存储,Bub 仍自行管理会话上下文。部署时,应用需要自行实现界面数据存储和用户隔离。 + +这些示例支持发送新消息和浏览器工具续跑,不支持编辑旧消息或重新生成回复。如果 UI 模板提供这些操作,请禁用相应入口。 + +将下面的辅助文件保存为 `demo-session.ts`:assistant-ui 放在 `app/` 下,三个 Vite 项目放在 `src/` 下。 + +
+demo-session.ts + +```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, + }); +} +``` + +
+ + + + +通过[官方 Starter](https://www.assistant-ui.com/docs/cli)创建项目,选择默认模板,再安装 AG-UI runtime: + +```bash +npx assistant-ui@latest create bub-assistant-ui +cd bub-assistant-ui +npm install @assistant-ui/react@0.15.33 @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4 +``` + +在 `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`。provider 从应用的演示存储加载消息,交给历史适配器,并注册天气工具。SDK 订阅在 run 结束后保存消息和状态。 + +
+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}; +} +``` + +
+ +用以下内容替换 `app/assistant.tsx`,保留现有的 `app/page.tsx` 入口: + +```tsx title="app/assistant.tsx" +"use client"; + +import { BubRuntimeProvider } from "./BubRuntimeProvider"; +import { Thread } from "@/components/assistant-ui/elements/thread.aui"; + +export const Assistant = () => ( + +
+
+); +``` + +启动前端: + +```bash +npm run dev -- --hostname localhost --port 3000 +``` + +
+ + +本地开发时,可以通过 `agents__unsafe_dev_only` 直连。部署时需要在 React 应用和 Bub 之间配置 [CopilotKit runtime](https://docs.copilotkit.ai/backend/self-managed-agents),连接方式可参考 [LangChain 集成指南](https://docs.langchain.com/oss/python/langchain/frontend/integrations/copilotkit)。 + +创建 React 项目,并安装匹配的 CopilotKit 和 AG-UI 版本: + +```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 +``` + +添加上方的 Vite 代理和 `src/scenario.json`。创建 `src/BubHttpAgent.ts`,在 CopilotKit 的 connect 阶段读取应用保存的快照。这里的事件只用于恢复界面,不会请求后端或启动模型运行。 + +
+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(); + }); + } +} +``` + +
+ +替换 `src/main.tsx`。`useFrontendTool` 注册天气工具,并将执行结果返回给 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); +}); +``` + +启动前端: + +```bash +npm run dev +``` + +
+ + +创建 React 项目并安装 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 +``` + +添加上方的 Vite 代理和 `src/scenario.json`,再用以下代码替换 `src/main.tsx`。`AgentInterface` 展示聊天界面,`agUIAdapter()` 解析事件。应用通过 `ChatStorage` 读取演示存储,通过 `ChatLLM.send` 发起请求、执行浏览器工具并续跑。 + +
+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( +
+ +
, +); +``` + +
+ +此示例提供一个保存的会话,未实现删除功能。默认渲染器会将 Markdown 表格显示为纯文本。调整界面时可参考 [OpenUI Agent 示例](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra)。 + +启动前端: + +```bash +npm run dev +``` + +
+ + +创建 React 项目,安装 AG-UI 客户端和 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 +``` + +替换 `vite.config.ts`,配置 React、Tailwind、`@` 别名和 Bub 代理: + +```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/, ""), + }, + }, + }, +}); +``` + +在 `tsconfig.json` 和 `tsconfig.app.json` 的 `compilerOptions` 中添加以下属性: + +```json +"paths": { "@/*": ["./src/*"] }, +"resolveJsonModule": true +``` + +用以下内容替换 `src/index.css`,然后安装 UI 组件。安装器会添加主题样式和组件依赖。 + +```css title="src/index.css" +@import "tailwindcss"; +``` + +```bash +npx shadcn@latest init +npx ai-elements@latest add conversation message prompt-input tool suggestion +``` + +将共用数据保存为 `src/scenario.json`,再用以下代码替换 `src/main.tsx`。代码订阅 `HttpAgent` 消息,将文本和工具调用映射到 AI Elements 组件,并负责回传工具结果和续跑。组件用法可参考 [AI Elements 指南](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 ( +
+ + + {messages + .filter((m) => m.role === "user" || m.role === "assistant") + .map((message) => ( + +
+ {message.role === "assistant" && + message.toolCalls?.map((call) => { + const result = messages.find( + (m) => m.role === "tool" && m.toolCallId === call.id, + ); + let input: unknown = {}; + try { + input = JSON.parse(call.function.arguments || "{}"); + } catch { + input = call.function.arguments; + } + return ( + + + + + {result && } + + + ); + })} + {typeof message.content === "string" && message.content && ( + + {message.content} + + )} +
+
+ ))} + {error && ( +

+ {error} +

+ )} +
+ +
+
+ {!messages.length && ( + + void send(scenario.prompt)} + /> + + )} +
+ send(message.text)}> + + setText(e.target.value)} value={text} /> + + + + + Bub · AG-UI bridge · Demo forecast + + + agent.abortRun()} + /> + + +
+
+
+ ); +} +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); +}); +``` + +
+ +启动前端: + +```bash +npm run dev +``` + +
+
+ +## 3. 发送消息并在刷新后继续对话 {#verify} + +每次启动一个前端,打开 `http://localhost:3000`,发送以下请求: + +```text +Call get_weather for San Francisco, then suggest an afternoon plan using the demo forecast. +``` + +Bub 会请求调用浏览器工具,收到结果后继续生成回复。OpenUI 和 AI Elements 示例只处理旧金山天气,最多续跑四轮,这些限制由示例代码设置。 + +回复结束后,在同一标签页刷新并继续追问。应用从 `sessionStorage` 恢复界面中的消息和共享状态,保存的 `threadId` 则让请求继续使用原有的 Bub 会话。没有保存消息的新客户端无法从 Bub 获取旧消息来恢复聊天界面。OpenUI 需要从侧栏选择会话。清除对应示例的存储键后再刷新,即可创建新会话。 + +持久化的 Bub tape store 可以在后端重启后保留已完成的对话上下文和会话设置。保留同一份默认文件存储或[数据库存储](/zh-cn/docs/integrations/storage/),即可继续这些对话。等待前端工具结果或人工输入的执行只能在当前适配器进程中继续,无法跨重启恢复。浏览器快照用于恢复 UI,无法恢复待完成的执行或已删除的服务端上下文。 + +## 在自己的前端中使用 HttpAgent {#connect} + +如果自行编写界面,可以用 `@ag-ui/client` 管理 AG-UI 连接和消息状态。下方纯 TypeScript 示例展示流式文本,每次刷新都会创建新会话。 + +
+最小浏览器聊天示例 + +创建 Vite 项目: + +```bash +npm create vite@latest bub-chat -- --template vanilla-ts +cd bub-chat +npm install +npm install @ag-ui/client@1.0.4 +``` + +替换 `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(); + } +}); +``` + +启动 Vite,打开 `http://localhost:3000`: + +```bash +npm run dev -- --host localhost --port 3000 --strictPort +``` + +
+ +此示例直接请求 Bub,默认允许的来源为 `http://localhost:3000`。如果使用其他前端来源,在启动后端前设置 `BUB_AG_UI_ORIGINS`: + +```bash +export BUB_AG_UI_ORIGINS='["http://localhost:5173"]' +``` + +来源中的协议、主机名和端口都需要匹配。`localhost` 和 `127.0.0.1` 属于不同来源。 + +## 工具与会话上下文 {#tools-and-history} + +前端在 run 的 `tools` 列表中声明浏览器工具。Bub 调用工具后,前端执行它,添加带有对应 `toolCallId` 的结果,再在同一个会话上发起下一次 AG-UI run。续跑时保持前端工具定义不变,并为所有待处理调用提供结果。assistant-ui 和 CopilotKit 通过各自的 runtime 完成续跑,OpenUI 和 AI Elements 示例则在应用代码中发起请求。 + +`RUN_FINISHED` 表示一次 HTTP run 结束,此时 Bub 可能仍在等待前端结果或人工输入。下一次 `POST /agent` 连接到这次原生执行,提交工具结果或中断响应后继续运行,无需回传历史或添加用户消息。同一批调用同时包含后端和前端工具时,Bub 会等全部调用完成后统一发送并记录结果。 + +工具结果或中断响应必须在 `max_run_seconds` 到期前发回同一个适配器实例。默认期限为 600 秒,从整个原生 turn 开始计算,包含等待前端的时间。适配器重启、关闭或运行超时都会终止这次执行;之后再提交对应结果会返回 `RUN_ERROR`。 + +等待人工输入时,适配器发送 `STATE_SNAPSHOT`,随后发送 `outcome.type: "interrupt"` 的 `RUN_FINISHED`。为每个待处理中断提供一项 `resume` 后,Bub 通过原生 `TOOL_CALL_RESULT` 事件返回决策结果。重复提交已接受的响应不会再次执行或重放答案。持久化 tape store 可以在重启后保留响应回执,但不能恢复待完成的调用。 + +Bub 通过原生流执行对话,并从 tape 中选择模型上下文,保留会话设置、已加载工具和 handoff 边界。SDK 再次发送旧消息时,应保留原来的消息 ID:已接受的输入不会重复追加,回传的 assistant 消息或旧工具结果也不会替换 Bub 的记录,或把 handoff 之前的内容重新放回上下文。 + +修改已接受的用户消息并沿用同一个 ID 会返回 `RUN_ERROR`;适配器不提供编辑或重新生成分支。只包含旧历史、没有新输入的请求也会返回 `RUN_ERROR`,不会再次调用模型。 + +运行开始和等待人工输入时,消息事件都会增量更新 SDK,因此只发送新输入不会替换客户端已有的消息。适配器只提供 `POST /agent`,不提供用于展示历史消息或回放的接口。 + +`agent.abortRun()` 会关闭仍在进行的 HTTP 请求并取消对应执行。如果暂停的 HTTP run 已经结束,再取消这个旧请求无法终止等待中的原生 turn。应在 turn 超时前返回工具结果,或通过 `resume` 取消人工输入中断。取消不会撤销工具已经产生的副作用。 + +## 部署服务 {#hosting} + +监听非回环地址时,设置 `BUB_AG_UI_TOKEN`,并在 `POST /agent` 请求中发送 `Authorization: Bearer `。共享 token 保存在应用服务器中;如果浏览器直接连接 Bub,还需配置 `BUB_AG_UI_ORIGINS`。 + +共享 token 对应一个用户身份。多用户部署时,通过 `create_app(..., authenticate=...)` 嵌入服务,由可信认证返回稳定的用户标识。嵌入服务与网关配置见[插件 README](https://github.com/bubbuild/bub-contrib/blob/main/packages/bub-ag-ui/README.md)。 + +## 排障 {#troubleshooting} + +| 现象 | 检查方法 | +| --- | --- | +| 没有 `ag-ui` 命令 | 在安装插件的环境中运行 `bub ag-ui --help`。 | +| 浏览器请求失败 | 检查前端代理;直连时,检查 `BUB_AG_UI_ORIGINS` 是否与完整来源一致。 | +| 请求返回 401 或 403 | 检查 Bearer 请求头和认证配置。 | +| 没有回复 | 用 `bub run "Say hello"` 验证模型配置,并查看后端日志。 | +| 工具调用后没有继续回复 | 检查结果是否携带对应的工具调用 ID,以及前端是否发起下一次 run。 | +| 运行返回 `RUN_ERROR` | 查看事件中的错误信息;同一会话有请求执行时,等待它结束或关闭请求后再重试。 | From 567680bad5ae636b94a9708ef8d4e7f567f86549 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 11 Nov 2026 03:17:40 +0800 Subject: [PATCH 2/3] docs: fix verified AG-UI frontend setup --- website/src/content/docs/docs/integrations/ag-ui.mdx | 8 ++++---- .../src/content/docs/zh-cn/docs/integrations/ag-ui.mdx | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/website/src/content/docs/docs/integrations/ag-ui.mdx b/website/src/content/docs/docs/integrations/ag-ui.mdx index 4ce320e1..05c4aa13 100644 --- a/website/src/content/docs/docs/integrations/ag-ui.mdx +++ b/website/src/content/docs/docs/integrations/ag-ui.mdx @@ -140,12 +140,12 @@ export function persistDemoSession(key: string, agent: HttpAgent) { -Create a project with the [official Starter](https://www.assistant-ui.com/docs/cli), select the default template, and install the AG-UI runtime: +Create a project with the [official Starter](https://www.assistant-ui.com/docs/cli), select the default template, keep the Starter's `@assistant-ui/react` version, and install the AG-UI runtime: ```bash npx assistant-ui@latest create bub-assistant-ui cd bub-assistant-ui -npm install @assistant-ui/react@0.15.33 @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4 +npm install @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4 ``` Add this rewrite to the configuration object in `next.config.ts`, keeping the Starter settings and `withAui` wrapper: @@ -574,14 +574,14 @@ Add these properties to `compilerOptions` in both `tsconfig.json` and `tsconfig. "resolveJsonModule": true ``` -Replace `src/index.css` with the following, then install the UI components. The installer will add theme styles and component dependencies. +Replace `src/index.css` with the following, then install the UI components with Radix. The installer will add theme styles and component dependencies. ```css title="src/index.css" @import "tailwindcss"; ``` ```bash -npx shadcn@latest init +npx shadcn@latest init --base radix npx ai-elements@latest add conversation message prompt-input tool suggestion ``` 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 index c049c03f..38b1a122 100644 --- a/website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx +++ b/website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx @@ -140,12 +140,12 @@ export function persistDemoSession(key: string, agent: HttpAgent) { -通过[官方 Starter](https://www.assistant-ui.com/docs/cli)创建项目,选择默认模板,再安装 AG-UI runtime: +通过[官方 Starter](https://www.assistant-ui.com/docs/cli)创建项目,选择默认模板,保留 Starter 安装的 `@assistant-ui/react` 版本,再安装 AG-UI runtime: ```bash npx assistant-ui@latest create bub-assistant-ui cd bub-assistant-ui -npm install @assistant-ui/react@0.15.33 @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4 +npm install @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4 ``` 在 `next.config.ts` 的配置对象中添加以下 rewrite,保留 Starter 原有配置和 `withAui` 包装: @@ -574,14 +574,14 @@ export default defineConfig({ "resolveJsonModule": true ``` -用以下内容替换 `src/index.css`,然后安装 UI 组件。安装器会添加主题样式和组件依赖。 +用以下内容替换 `src/index.css`,然后选择 Radix 安装 UI 组件。安装器会添加主题样式和组件依赖。 ```css title="src/index.css" @import "tailwindcss"; ``` ```bash -npx shadcn@latest init +npx shadcn@latest init --base radix npx ai-elements@latest add conversation message prompt-input tool suggestion ``` From a8eb0d2a4058e25013adab10771c18e36f3ac976 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 11 Nov 2026 03:27:06 +0800 Subject: [PATCH 3/3] docs: streamline AG-UI frontend guide --- .../content/docs/docs/integrations/ag-ui.mdx | 135 +++++++++--------- .../docs/zh-cn/docs/integrations/ag-ui.mdx | 133 ++++++++--------- 2 files changed, 127 insertions(+), 141 deletions(-) diff --git a/website/src/content/docs/docs/integrations/ag-ui.mdx b/website/src/content/docs/docs/integrations/ag-ui.mdx index 05c4aa13..e3cd00cf 100644 --- a/website/src/content/docs/docs/integrations/ag-ui.mdx +++ b/website/src/content/docs/docs/integrations/ag-ui.mdx @@ -4,13 +4,15 @@ description: Try Bub's experimental AG-UI support. Connect an AI chat frontend w sidebar: label: Web frontends with AG-UI badge: { text: 'App', variant: 'note' } +tableOfContents: + maxHeadingLevel: 2 --- import { Tabs, TabItem } from '@astrojs/starlight/components'; -Bub's AG-UI integration is experimental. The `bub-ag-ui` plugin streams replies and tool calls to a web chat frontend. Bub manages model context; your application displays messages, handles browser tools, and saves UI history. +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. -For a first chat, [start the plugin](#install), then follow the assistant-ui tab below. Each tab includes the setup and application adapter code for that frontend. +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} @@ -27,23 +29,18 @@ bub ag-ui --help bub ag-ui --host 127.0.0.1 --port 28201 ``` -Keep the terminal open. The service accepts AG-UI requests at `http://127.0.0.1:28201/agent` and returns an SSE event stream. The frontend examples below connect to this service. +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 a frontend for your project: +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. -| Frontend | Integration | -| --- | --- | -| assistant-ui | assistant-ui's AG-UI runtime connects to Bub; an application history adapter restores the chat UI. | -| CopilotKit | React chat and frontend-tool APIs connect through an AG-UI agent. | -| OpenUI | `AgentInterface` and its AG-UI parser work with an application adapter for tools and history. | -| AI Elements | UI components render messages and tool state supplied by an `HttpAgent` bridge. | - -The examples use a browser tool named `get_weather`, which returns a fixed San Francisco forecast. The tool definition and data are shared by the three Vite projects. Save the following as `src/scenario.json` after creating your project; the assistant-ui provider includes it inline. +The tabs use these shared files. Copy the files needed by your frontend after creating its project.
-Weather tool and sample data +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" { @@ -68,12 +65,7 @@ The examples use a browser tool named `get_weather`, which returns a fixed San F } ``` -
- -For CopilotKit and OpenUI, add this `server` property to `defineConfig({...})` in the generated `vite.config.ts`. It serves the frontend on port 3000 and forwards `/api/*` to Bub after removing the `/api` prefix. The AI Elements tab includes this proxy in its full Vite configuration; assistant-ui uses a Next.js rewrite. - -
-Vite proxy configuration +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: { @@ -90,16 +82,7 @@ server: { }, ``` -
- -Each example keeps a stable `threadId` and saves SDK messages and shared state in `sessionStorage` after each run. Reloading the same browser tab restores the chat UI through `initialMessages` and `initialState`. This is demo storage for the frontend; Bub manages its own session context. A deployed application needs its own UI storage and user isolation. - -These examples support new messages and browser-tool continuation. Editing earlier messages and regenerating replies are unsupported. Disable those actions if your UI template exposes them. - -Save the helper below as `demo-session.ts`: in `app/` for assistant-ui, or in `src/` for the three Vite projects. - -
-demo-session.ts +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"; @@ -140,7 +123,11 @@ export function persistDemoSession(key: string, agent: HttpAgent) { -Create a project with the [official Starter](https://www.assistant-ui.com/docs/cli), select the default template, keep the Starter's `@assistant-ui/react` version, and install the AG-UI runtime: +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 @@ -148,7 +135,9 @@ cd bub-assistant-ui npm install @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4 ``` -Add this rewrite to the configuration object in `next.config.ts`, keeping the Starter settings and `withAui` wrapper: +### 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() { @@ -156,7 +145,7 @@ async rewrites() { }, ``` -Create `app/BubRuntimeProvider.tsx`. The provider loads messages from the application’s demo storage, supplies them to the history adapter, and registers the weather tool. An SDK subscription saves messages and state when a run ends. +Create `app/BubRuntimeProvider.tsx` to connect the runtime, restore displayed messages, and register the weather tool:
app/BubRuntimeProvider.tsx @@ -258,7 +247,7 @@ export const Assistant = () => ( ); ``` -Start the frontend: +### Start the frontend {#assistant-ui-start} ```bash npm run dev -- --hostname localhost --port 3000 @@ -267,9 +256,11 @@ npm run dev -- --hostname localhost --port 3000 -For local development, CopilotKit can connect directly through `agents__unsafe_dev_only`. For deployment, use a [CopilotKit runtime](https://docs.copilotkit.ai/backend/self-managed-agents) between the React app and Bub, as illustrated in the [LangChain integration guide](https://docs.langchain.com/oss/python/langchain/frontend/integrations/copilotkit). +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 React project and install the matching CopilotKit and AG-UI versions: +### 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 @@ -278,7 +269,9 @@ 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 ``` -Add the shared Vite proxy and `src/scenario.json`. Create `src/BubHttpAgent.ts` to read an application snapshot during CopilotKit’s connect phase. These events restore the UI without making a backend request or starting a model run. +### 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 @@ -373,7 +366,7 @@ start().catch((error) => { }); ``` -Start the frontend: +### Start the frontend {#copilotkit-start} ```bash npm run dev @@ -382,6 +375,10 @@ 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 @@ -391,7 +388,9 @@ 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 ``` -Add the shared Vite proxy and `src/scenario.json`, then replace `src/main.tsx` with the code below. `AgentInterface` renders the chat, and `agUIAdapter()` parses the events. The application supplies `ChatStorage` for demo storage and `ChatLLM.send` for requests and browser-tool continuation. +### 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 @@ -522,9 +521,9 @@ createRoot(document.getElementById("root")!).render(
-This example provides one saved thread and disables deletion. Its default renderer displays Markdown tables as plain text. For a different layout, see the [OpenUI agent example](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra). +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: +### Start the frontend {#openui-start} ```bash npm run dev @@ -533,6 +532,10 @@ 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 @@ -543,6 +546,8 @@ 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" @@ -574,7 +579,7 @@ Add these properties to `compilerOptions` in both `tsconfig.json` and `tsconfig. "resolveJsonModule": true ``` -Replace `src/index.css` with the following, then install the UI components with Radix. The installer will add theme styles and component dependencies. +Replace `src/index.css` with the following, then install the UI components with Radix: ```css title="src/index.css" @import "tailwindcss"; @@ -585,7 +590,7 @@ npx shadcn@latest init --base radix npx ai-elements@latest add conversation message prompt-input tool suggestion ``` -Save the shared fixture as `src/scenario.json` and replace `src/main.tsx` with the code below. It subscribes to `HttpAgent` messages and maps text and tool calls into AI Elements components. The application also sends tool results and starts continuation runs. See the [AI Elements guide](https://docs.langchain.com/oss/python/langchain/frontend/integrations/ai-elements) for component usage. +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 @@ -795,7 +800,7 @@ start().catch((error) => {
-Start the frontend: +### Start the frontend {#ai-elements-start} ```bash npm run dev @@ -804,23 +809,29 @@ npm run dev
-## 3. Send a message and continue after a reload {#verify} +## 3. Try the conversation {#verify} -Open `http://localhost:3000` with one frontend running and send the following request: +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 requests the browser tool, receives its result, and streams a reply. The OpenUI and AI Elements examples accept San Francisco only and stop after at most four continuation rounds; these limits belong to the example code. +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`. -After the reply finishes, reload the same browser tab, then ask a follow-up question. The application restores the displayed messages and shared state from `sessionStorage`; the saved `threadId` continues the existing Bub session. A fresh client without saved messages cannot reconstruct the earlier display history from Bub. In OpenUI, select the thread from the sidebar. Clearing the example's storage key starts a new conversation on the next reload. +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. -A persistent Bub tape store preserves completed conversation context and session settings across backend restarts. Keep the same default files or [database storage](/docs/integrations/storage/) to continue those conversations. Pending tool calls and human-input interrupts require the live execution and cannot resume after a restart. A browser snapshot restores the UI; it cannot recover pending execution or deleted server context. +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, `@ag-ui/client` can manage the AG-UI connection and message state. This plain TypeScript example displays streamed text and creates a new thread on each reload. +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 @@ -909,29 +920,11 @@ export BUB_AG_UI_ORIGINS='["http://localhost:5173"]' Match the scheme, hostname, and port exactly. `localhost` and `127.0.0.1` are different origins. -## Tools and session context {#tools-and-history} - -A frontend declares browser tools in the run's `tools` list. When Bub calls one, the frontend executes it, adds a result with the matching `toolCallId`, and starts another AG-UI run on the same thread. Keep the frontend tool definitions unchanged and include results for every pending call. assistant-ui and CopilotKit handle continuation through their runtimes; the OpenUI and AI Elements examples implement the requests in application code. - -`RUN_FINISHED` ends one HTTP run, which can leave Bub waiting for frontend results or human input. The next `POST /agent` attaches to that same live native execution. Tool results or interrupt responses can continue it without resending history or adding a user message. In a batch containing both backend and frontend tools, Bub emits and records the results together after all calls finish. - -Return results or interrupt responses to the same adapter before `max_run_seconds` expires. Its default is 600 seconds for the entire native turn, including time spent waiting for the frontend. Restarting or shutting down the adapter, or reaching the timeout, ends that execution; submitting its results afterward returns `RUN_ERROR`. - -A human-input pause sends `STATE_SNAPSHOT`, then `RUN_FINISHED` with `outcome.type: "interrupt"`. Send a `resume` entry for every pending interrupt; Bub emits the decision result through its native `TOOL_CALL_RESULT` event. Repeating an accepted response does not execute the work again or replay the answer. Its receipt can survive a restart with a persistent tape store, but a pending call cannot. - -Bub executes the conversation through its native stream and selects model context from its tape, preserving session settings, loaded tools, and handoff boundaries. Keep message IDs stable when the SDK sends earlier messages again: accepted input is not appended twice, and echoed assistant messages or old tool results do not replace Bub's records or bring earlier context back across a handoff. - -Changing an accepted user message with the same ID returns `RUN_ERROR`; the adapter does not provide edit or regenerate branches. A request containing only old history and no new input also returns `RUN_ERROR` without running the model. - -Message events update the SDK incrementally at run start and human-input pauses, so sending only new input does not replace messages already held by the client. The adapter exposes only `POST /agent`, with no display-history or replay endpoint. - -`agent.abortRun()` closes an active HTTP request and cancels its execution. Once a paused HTTP run has finished, aborting that old request cannot cancel the waiting native turn. Resolve its tool calls, or cancel its human-input interrupts through `resume`, before the turn timeout. Cancellation does not undo completed tool side effects. - ## Deploy the service {#hosting} -When listening on a non-loopback address, set `BUB_AG_UI_TOKEN`. Send `Authorization: Bearer ` with `POST /agent` requests. Keep the shared token on the application server, and configure `BUB_AG_UI_ORIGINS` if browsers connect to Bub directly. +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 multiple users, embed the service with `create_app(..., authenticate=...)` and return a stable user identity from trusted authentication. Embedding and gateway setup are described in the [plugin README](https://github.com/bubbuild/bub-contrib/blob/main/packages/bub-ag-ui/README.md). +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} @@ -941,5 +934,5 @@ A shared token represents one user identity. For multiple users, embed the servi | 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 its result carries the matching tool-call ID and that the frontend starts the next run. | -| A run returns `RUN_ERROR` | Read the event’s error message. If another request is executing on the thread, wait for it or close that request before retrying. | +| 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 index 38b1a122..882c534b 100644 --- a/website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx +++ b/website/src/content/docs/zh-cn/docs/integrations/ag-ui.mdx @@ -4,13 +4,15 @@ 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 集成仍处于实验阶段。`bub-ag-ui` 插件将回复和工具调用以事件流发送到 Web 聊天前端。Bub 管理模型上下文,应用负责展示消息、执行浏览器工具并保存界面历史。 +`bub-ag-ui` 插件通过 AG-UI 将 Bub 接入 Web 聊天前端,让你接收流式回复,并让 Bub 调用浏览器中的工具。这项集成仍处于实验阶段。 -首次接入可以先[启动插件](#install),再按下方 assistant-ui 标签页操作。每个标签页都包含相应前端的准备步骤和应用适配代码。 +本指南接入一个聊天界面,再用天气工具规划在旧金山的下午行程。如果还没有选定前端,可以从 assistant-ui 标签页开始。 ## 开始之前 {#before-you-start} @@ -27,23 +29,18 @@ bub ag-ui --help bub ag-ui --host 127.0.0.1 --port 28201 ``` -保持终端运行。服务通过 `http://127.0.0.1:28201/agent` 接收 AG-UI 请求,以 SSE 事件流返回回复。下方各前端示例都连接这个服务。 +保持这个终端运行。前端将向 `http://127.0.0.1:28201/agent` 发送请求并接收流式回复。 ## 2. 连接前端 {#choose-ui} -根据项目需要选择一个前端: +选择下方的一个标签页。每个示例都连接同一个 Bub 服务,在浏览器中执行 `get_weather` 工具,并保存界面中的对话以便刷新后恢复。天气数据是固定的旧金山演示预报。 -| 前端 | 接入方式 | -| --- | --- | -| assistant-ui | 使用 assistant-ui 提供的 AG-UI runtime 连接 Bub,由应用的历史适配器恢复聊天界面。 | -| CopilotKit | 通过 AG-UI Agent 接入 React 聊天组件和前端工具 API。 | -| OpenUI | 使用 `AgentInterface` 和 AG-UI 解析器,由应用适配工具调用和历史记录。 | -| AI Elements | 由 `HttpAgent` 桥接消息和工具状态,交给 UI 组件渲染。 | - -示例使用名为 `get_weather` 的浏览器工具,返回固定的旧金山天气数据。三个 Vite 项目共用下方的工具定义和数据,创建项目后保存为 `src/scenario.json`;assistant-ui 的 provider 已内嵌这些内容。 +各标签页用到以下共用文件。创建项目后,复制所选前端需要的文件。
-天气工具与示例数据 +共用示例文件 + +CopilotKit、OpenUI 和 AI Elements 将天气工具及数据保存为 `src/scenario.json`。assistant-ui 示例已在 provider 中包含这些内容。 ```json title="src/scenario.json" { @@ -68,12 +65,7 @@ bub ag-ui --host 127.0.0.1 --port 28201 } ``` -
- -CopilotKit 和 OpenUI 项目创建后,在生成的 `vite.config.ts` 的 `defineConfig({...})` 中添加以下 `server` 属性。前端运行在 3000 端口,代理将 `/api/*` 去掉 `/api` 前缀后转发给 Bub。AI Elements 的完整 Vite 配置已包含这个代理,assistant-ui 则使用 Next.js rewrite。 - -
-Vite 代理配置 +CopilotKit 和 OpenUI 在 `vite.config.ts` 的 `defineConfig({...})` 中添加以下 `server` 属性。前端运行在 3000 端口,代理将 `/api/*` 去掉 `/api` 前缀后转发给 Bub。另外两个标签页包含各自的代理配置。 ```typescript title="vite.config.ts (server property)" server: { @@ -90,16 +82,7 @@ server: { }, ``` -
- -每个示例保留稳定的 `threadId`,并在每次 run 结束后将 SDK 消息和共享状态保存到 `sessionStorage`,以便在同一浏览器标签页刷新后,通过 `initialMessages` 和 `initialState` 恢复聊天界面。这是前端的演示存储,Bub 仍自行管理会话上下文。部署时,应用需要自行实现界面数据存储和用户隔离。 - -这些示例支持发送新消息和浏览器工具续跑,不支持编辑旧消息或重新生成回复。如果 UI 模板提供这些操作,请禁用相应入口。 - -将下面的辅助文件保存为 `demo-session.ts`:assistant-ui 放在 `app/` 下,三个 Vite 项目放在 `src/` 下。 - -
-demo-session.ts +将存储辅助文件保存为 `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"; @@ -140,7 +123,11 @@ export function persistDemoSession(key: string, agent: HttpAgent) { -通过[官方 Starter](https://www.assistant-ui.com/docs/cli)创建项目,选择默认模板,保留 Starter 安装的 `@assistant-ui/react` 版本,再安装 AG-UI runtime: +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 @@ -148,7 +135,9 @@ cd bub-assistant-ui npm install @assistant-ui/react-ag-ui@0.1.2 @ag-ui/client@1.0.4 ``` -在 `next.config.ts` 的配置对象中添加以下 rewrite,保留 Starter 原有配置和 `withAui` 包装: +### 连接 Bub {#assistant-ui-connect} + +将共用辅助文件保存为 `app/demo-session.ts`。在 `next.config.ts` 的配置对象中添加以下 rewrite,保留 Starter 原有配置和 `withAui` 包装: ```typescript title="next.config.ts (configuration property)" async rewrites() { @@ -156,7 +145,7 @@ async rewrites() { }, ``` -创建 `app/BubRuntimeProvider.tsx`。provider 从应用的演示存储加载消息,交给历史适配器,并注册天气工具。SDK 订阅在 run 结束后保存消息和状态。 +创建 `app/BubRuntimeProvider.tsx`,接入 runtime、恢复界面消息并注册天气工具:
app/BubRuntimeProvider.tsx @@ -258,7 +247,7 @@ export const Assistant = () => ( ); ``` -启动前端: +### 启动前端 {#assistant-ui-start} ```bash npm run dev -- --hostname localhost --port 3000 @@ -267,7 +256,9 @@ npm run dev -- --hostname localhost --port 3000 -本地开发时,可以通过 `agents__unsafe_dev_only` 直连。部署时需要在 React 应用和 Bub 之间配置 [CopilotKit runtime](https://docs.copilotkit.ai/backend/self-managed-agents),连接方式可参考 [LangChain 集成指南](https://docs.langchain.com/oss/python/langchain/frontend/integrations/copilotkit)。 +此示例使用 `CopilotChat` 和 `useFrontendTool`,通过仅供开发使用的 `agents__unsafe_dev_only` 连接 Bub。部署时使用 [CopilotKit runtime](https://docs.copilotkit.ai/backend/self-managed-agents),接法可参考 [LangChain 集成指南](https://docs.langchain.com/oss/python/langchain/frontend/integrations/copilotkit)。 + +### 创建项目 {#copilotkit-project} 创建 React 项目,并安装匹配的 CopilotKit 和 AG-UI 版本: @@ -278,7 +269,9 @@ 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 ``` -添加上方的 Vite 代理和 `src/scenario.json`。创建 `src/BubHttpAgent.ts`,在 CopilotKit 的 connect 阶段读取应用保存的快照。这里的事件只用于恢复界面,不会请求后端或启动模型运行。 +### 连接 Bub {#copilotkit-connect} + +将共用文件保存为 `src/demo-session.ts` 和 `src/scenario.json`,添加共用的 Vite 代理。创建 `src/BubHttpAgent.ts`,从浏览器存储恢复界面消息,无需向 Bub 请求历史:
src/BubHttpAgent.ts @@ -373,7 +366,7 @@ start().catch((error) => { }); ``` -启动前端: +### 启动前端 {#copilotkit-start} ```bash npm run dev @@ -382,6 +375,10 @@ npm run dev +OpenUI 提供 `AgentInterface` 和 AG-UI 解析器。下方应用代码将它们接入 Bub,并处理浏览器工具调用。 + +### 创建项目 {#openui-project} + 创建 React 项目并安装 OpenUI: ```bash @@ -391,7 +388,9 @@ 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 ``` -添加上方的 Vite 代理和 `src/scenario.json`,再用以下代码替换 `src/main.tsx`。`AgentInterface` 展示聊天界面,`agUIAdapter()` 解析事件。应用通过 `ChatStorage` 读取演示存储,通过 `ChatLLM.send` 发起请求、执行浏览器工具并续跑。 +### 连接 Bub {#openui-connect} + +将共用文件保存为 `src/demo-session.ts` 和 `src/scenario.json`,添加共用的 Vite 代理,再替换 `src/main.tsx`:
src/main.tsx @@ -522,9 +521,9 @@ createRoot(document.getElementById("root")!).render(
-此示例提供一个保存的会话,未实现删除功能。默认渲染器会将 Markdown 表格显示为纯文本。调整界面时可参考 [OpenUI Agent 示例](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra)。 +此示例在侧栏保留一个会话,并禁用删除功能。默认渲染器会将 Markdown 表格显示为纯文本。调整界面时可参考 [OpenUI Agent 示例](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra)。 -启动前端: +### 启动前端 {#openui-start} ```bash npm run dev @@ -533,6 +532,10 @@ npm run dev
+AI Elements 提供 UI 组件,应用通过 `HttpAgent` 将它们接入 Bub,并处理浏览器工具调用。 + +### 创建项目 {#ai-elements-project} + 创建 React 项目,安装 AG-UI 客户端和 Tailwind CSS: ```bash @@ -543,6 +546,8 @@ npm install @ag-ui/client@1.0.4 ai@7.0.153 npm install -D tailwindcss @tailwindcss/vite @types/node ``` +### 连接 Bub {#ai-elements-connect} + 替换 `vite.config.ts`,配置 React、Tailwind、`@` 别名和 Bub 代理: ```typescript title="vite.config.ts" @@ -574,7 +579,7 @@ export default defineConfig({ "resolveJsonModule": true ``` -用以下内容替换 `src/index.css`,然后选择 Radix 安装 UI 组件。安装器会添加主题样式和组件依赖。 +用以下内容替换 `src/index.css`,然后选择 Radix 安装 UI 组件: ```css title="src/index.css" @import "tailwindcss"; @@ -585,7 +590,7 @@ npx shadcn@latest init --base radix npx ai-elements@latest add conversation message prompt-input tool suggestion ``` -将共用数据保存为 `src/scenario.json`,再用以下代码替换 `src/main.tsx`。代码订阅 `HttpAgent` 消息,将文本和工具调用映射到 AI Elements 组件,并负责回传工具结果和续跑。组件用法可参考 [AI Elements 指南](https://docs.langchain.com/oss/python/langchain/frontend/integrations/ai-elements)。 +将共用文件保存为 `src/demo-session.ts` 和 `src/scenario.json`,再替换 `src/main.tsx`。组件用法可参考 [AI Elements 指南](https://docs.langchain.com/oss/python/langchain/frontend/integrations/ai-elements)。
src/main.tsx @@ -795,7 +800,7 @@ start().catch((error) => {
-启动前端: +### 启动前端 {#ai-elements-start} ```bash npm run dev @@ -804,23 +809,29 @@ npm run dev
-## 3. 发送消息并在刷新后继续对话 {#verify} +## 3. 开始对话 {#verify} -每次启动一个前端,打开 `http://localhost:3000`,发送以下请求: +启动一个前端后,打开 `http://localhost:3000`,发送以下请求: ```text Call get_weather for San Francisco, then suggest an afternoon plan using the demo forecast. ``` -Bub 会请求调用浏览器工具,收到结果后继续生成回复。OpenUI 和 AI Elements 示例只处理旧金山天气,最多续跑四轮,这些限制由示例代码设置。 +Bub 会调用浏览器工具,再根据结果建议下午的行程。预报为 18°C、局部多云,使用的是演示数据,不是实时天气。 + +回复结束后,在同一浏览器标签页刷新,消息应仍然可见。OpenUI 需要从侧栏选择保存的会话。继续询问刚才讨论的是哪个城市、多少度,即可接着聊下去。 + +## 会话与界面历史 {#tools-and-history} + +示例将会话 ID、消息和状态保存在 `sessionStorage` 中,刷新后恢复界面中的对话。没有保存消息的新浏览器标签页无法向 Bub 获取旧的界面历史;AG-UI 服务只提供 `POST /agent`。 -回复结束后,在同一标签页刷新并继续追问。应用从 `sessionStorage` 恢复界面中的消息和共享状态,保存的 `threadId` 则让请求继续使用原有的 Bub 会话。没有保存消息的新客户端无法从 Bub 获取旧消息来恢复聊天界面。OpenUI 需要从侧栏选择会话。清除对应示例的存储键后再刷新,即可创建新会话。 +Bub 自行管理模型的会话上下文。保留同一个 `threadId` 可以继续对话;后端重启时,需保留 Bub 的默认文件或[数据库存储](/zh-cn/docs/integrations/storage/)。浏览器存储用于恢复界面,无法恢复已删除的 Bub 上下文或未完成的工具调用。回复完成前应保持后端运行。每轮默认超时为 600 秒,包含等待浏览器工具的时间。 -持久化的 Bub tape store 可以在后端重启后保留已完成的对话上下文和会话设置。保留同一份默认文件存储或[数据库存储](/zh-cn/docs/integrations/storage/),即可继续这些对话。等待前端工具结果或人工输入的执行只能在当前适配器进程中继续,无法跨重启恢复。浏览器快照用于恢复 UI,无法恢复待完成的执行或已删除的服务端上下文。 +清除示例的存储键并刷新,即可开始新会话。不支持编辑旧消息或重新生成回复;如果 UI 模板提供这些操作,请禁用相应入口。部署时,将演示存储替换为适合应用的数据存储和用户隔离方案。 ## 在自己的前端中使用 HttpAgent {#connect} -如果自行编写界面,可以用 `@ag-ui/client` 管理 AG-UI 连接和消息状态。下方纯 TypeScript 示例展示流式文本,每次刷新都会创建新会话。 +如果自行编写界面,可以用 `@ag-ui/client` 管理连接和消息状态。下方纯 TypeScript 示例展示流式文本,每次刷新都会创建新会话。
最小浏览器聊天示例 @@ -909,29 +920,11 @@ export BUB_AG_UI_ORIGINS='["http://localhost:5173"]' 来源中的协议、主机名和端口都需要匹配。`localhost` 和 `127.0.0.1` 属于不同来源。 -## 工具与会话上下文 {#tools-and-history} - -前端在 run 的 `tools` 列表中声明浏览器工具。Bub 调用工具后,前端执行它,添加带有对应 `toolCallId` 的结果,再在同一个会话上发起下一次 AG-UI run。续跑时保持前端工具定义不变,并为所有待处理调用提供结果。assistant-ui 和 CopilotKit 通过各自的 runtime 完成续跑,OpenUI 和 AI Elements 示例则在应用代码中发起请求。 - -`RUN_FINISHED` 表示一次 HTTP run 结束,此时 Bub 可能仍在等待前端结果或人工输入。下一次 `POST /agent` 连接到这次原生执行,提交工具结果或中断响应后继续运行,无需回传历史或添加用户消息。同一批调用同时包含后端和前端工具时,Bub 会等全部调用完成后统一发送并记录结果。 - -工具结果或中断响应必须在 `max_run_seconds` 到期前发回同一个适配器实例。默认期限为 600 秒,从整个原生 turn 开始计算,包含等待前端的时间。适配器重启、关闭或运行超时都会终止这次执行;之后再提交对应结果会返回 `RUN_ERROR`。 - -等待人工输入时,适配器发送 `STATE_SNAPSHOT`,随后发送 `outcome.type: "interrupt"` 的 `RUN_FINISHED`。为每个待处理中断提供一项 `resume` 后,Bub 通过原生 `TOOL_CALL_RESULT` 事件返回决策结果。重复提交已接受的响应不会再次执行或重放答案。持久化 tape store 可以在重启后保留响应回执,但不能恢复待完成的调用。 - -Bub 通过原生流执行对话,并从 tape 中选择模型上下文,保留会话设置、已加载工具和 handoff 边界。SDK 再次发送旧消息时,应保留原来的消息 ID:已接受的输入不会重复追加,回传的 assistant 消息或旧工具结果也不会替换 Bub 的记录,或把 handoff 之前的内容重新放回上下文。 - -修改已接受的用户消息并沿用同一个 ID 会返回 `RUN_ERROR`;适配器不提供编辑或重新生成分支。只包含旧历史、没有新输入的请求也会返回 `RUN_ERROR`,不会再次调用模型。 - -运行开始和等待人工输入时,消息事件都会增量更新 SDK,因此只发送新输入不会替换客户端已有的消息。适配器只提供 `POST /agent`,不提供用于展示历史消息或回放的接口。 - -`agent.abortRun()` 会关闭仍在进行的 HTTP 请求并取消对应执行。如果暂停的 HTTP run 已经结束,再取消这个旧请求无法终止等待中的原生 turn。应在 turn 超时前返回工具结果,或通过 `resume` 取消人工输入中断。取消不会撤销工具已经产生的副作用。 - ## 部署服务 {#hosting} -监听非回环地址时,设置 `BUB_AG_UI_TOKEN`,并在 `POST /agent` 请求中发送 `Authorization: Bearer `。共享 token 保存在应用服务器中;如果浏览器直接连接 Bub,还需配置 `BUB_AG_UI_ORIGINS`。 +监听非回环地址时,设置 `BUB_AG_UI_TOKEN`,并在请求中发送 `Authorization: Bearer `。token 保存在应用服务器中。如果浏览器直接连接 Bub,还需配置 `BUB_AG_UI_ORIGINS`。 -共享 token 对应一个用户身份。多用户部署时,通过 `create_app(..., authenticate=...)` 嵌入服务,由可信认证返回稳定的用户标识。嵌入服务与网关配置见[插件 README](https://github.com/bubbuild/bub-contrib/blob/main/packages/bub-ag-ui/README.md)。 +共享 token 对应一个用户身份。多用户认证与网关配置见[插件 README](https://github.com/bubbuild/bub-contrib/blob/main/packages/bub-ag-ui/README.md)。 ## 排障 {#troubleshooting} @@ -941,5 +934,5 @@ Bub 通过原生流执行对话,并从 tape 中选择模型上下文,保留 | 浏览器请求失败 | 检查前端代理;直连时,检查 `BUB_AG_UI_ORIGINS` 是否与完整来源一致。 | | 请求返回 401 或 403 | 检查 Bearer 请求头和认证配置。 | | 没有回复 | 用 `bub run "Say hello"` 验证模型配置,并查看后端日志。 | -| 工具调用后没有继续回复 | 检查结果是否携带对应的工具调用 ID,以及前端是否发起下一次 run。 | -| 运行返回 `RUN_ERROR` | 查看事件中的错误信息;同一会话有请求执行时,等待它结束或关闭请求后再重试。 | +| 工具调用后没有继续回复 | 检查前端是否返回工具结果并继续对话。 | +| 运行返回 `RUN_ERROR` | 查看事件中的错误信息和后端日志。 |