Skip to content

The Open Standard for Generative UI

docs(build-agents): restructure the section and teach how OpenUI agents work (#1334)

abhithesys053f6f006d3f
diff --git a/docs/app/(home)/integrations/data.ts b/docs/app/(home)/integrations/data.ts
index 0946d81d2..75180d09b 100644
--- a/docs/app/(home)/integrations/data.ts
+++ b/docs/app/(home)/integrations/data.ts
@@ -260,7 +260,7 @@ const integrationCatalog: Integration[] = [
},
{
label: "Integration guide",
- href: "/docs/agent/agent-runtimes/langgraph-platform",
+ href: "/docs/build-agents/frameworks/langgraph",
kind: "Guide",
},
exampleLink("agent-frameworks/langgraph-platform"),
@@ -302,7 +302,7 @@ const integrationCatalog: Integration[] = [
},
{
label: "Integration guide",
- href: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ href: "/docs/build-agents/frameworks/vercel-ai-sdk",
kind: "Guide",
},
...packageLinks("@openuidev/react-headless", "react-headless"),
@@ -520,7 +520,7 @@ const integrationCatalog: Integration[] = [
links: [
{
label: "Integration guide",
- href: "/docs/agent/agent-runtimes/vercel-eve",
+ href: "/docs/build-agents/frameworks/vercel-eve",
kind: "Guide",
},
exampleLink("agent-frameworks/vercel-eve", "OpenUI harness"),
@@ -557,7 +557,7 @@ const integrationCatalog: Integration[] = [
links: [
{
label: "Integration guide",
- href: "/docs/agent/agent-runtimes/pi",
+ href: "/docs/build-agents/frameworks/pi",
kind: "Guide",
},
exampleLink("harnesses/pi", "OpenUI harness"),
diff --git a/docs/app/(home)/sections/StackDiagramSection/StackDiagramSection.tsx b/docs/app/(home)/sections/StackDiagramSection/StackDiagramSection.tsx
index 71976517d..2f14458d1 100644
--- a/docs/app/(home)/sections/StackDiagramSection/StackDiagramSection.tsx
+++ b/docs/app/(home)/sections/StackDiagramSection/StackDiagramSection.tsx
@@ -199,7 +199,7 @@ const DESCRIPTIONS: Record<
title: "Bring your agent backend",
description: "Use any framework, tools, APIs, and data sources.",
cloud: ["Data persistence", "Reliability", "Observability", "Inbuilt tools"],
- docsHref: "/docs/agent/core-concepts/tools",
+ docsHref: "/docs/build-agents/tools",
worksWith: FRAMEWORK_BADGES,
},
model: {
diff --git a/docs/components/agent-turn-diagram.tsx b/docs/components/agent-turn-diagram.tsx
new file mode 100644
index 000000000..be7574535
--- /dev/null
+++ b/docs/components/agent-turn-diagram.tsx
@@ -0,0 +1,265 @@
+import { AppWindow, Bot, Server, Wrench, type LucideIcon } from "lucide-react";
+
+type Box = {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ icon: LucideIcon;
+ title: string;
+ lines: string[];
+ footer?: string;
+ compact?: boolean;
+};
+
+const boxes: Box[] = [
+ {
+ x: 10,
+ y: 20,
+ width: 200,
+ height: 270,
+ icon: AppWindow,
+ title: "Chat UI",
+ lines: ["Renders the stream", "with your components"],
+ footer: "Your frontend",
+ },
+ {
+ x: 410,
+ y: 20,
+ width: 200,
+ height: 270,
+ icon: Server,
+ title: "Agent backend",
+ lines: ["Adds OpenUI", "instructions to", "the system prompt"],
+ footer: "Your code",
+ },
+ {
+ x: 810,
+ y: 20,
+ width: 200,
+ height: 270,
+ icon: Bot,
+ title: "Model",
+ lines: ["Any provider,", "or OpenUI Gateway"],
+ },
+ {
+ x: 410,
+ y: 370,
+ width: 200,
+ height: 110,
+ icon: Wrench,
+ title: "Tools",
+ lines: ["Run by your agent"],
+ compact: true,
+ },
+];
+
+const label = "fill-fd-foreground font-mono text-[13px] font-bold uppercase tracking-[0.1em]";
+// Approximate advance of one label character, used to place the step badge beside centered text.
+const labelCharWidth = 9.2;
+
+function BoxNode({ box }: { box: Box }) {
+ const center = box.x + box.width / 2;
+ const Icon = box.icon;
+ const iconY = box.compact ? box.y + 16 : box.y + 72;
+ const titleY = iconY + (box.compact ? 54 : 62);
+ return (
+ <g>
+ <rect
+ x={box.x}
+ y={box.y}
+ width={box.width}
+ height={box.height}
+ rx={12}
+ strokeWidth={1.75}
+ className="fill-fd-background stroke-fd-foreground"
+ />
+ <Icon
+ x={center - 15}
+ y={iconY}
+ width={30}
+ height={30}
+ strokeWidth={1.6}
+ className="text-fd-foreground"
+ aria-hidden="true"
+ />
+ <text
+ x={center}
+ y={titleY}
+ textAnchor="middle"
+ className="fill-fd-foreground font-mono text-[16px] font-bold uppercase tracking-[0.05em]"
+ >
+ {box.title}
+ </text>
+ {box.lines.map((line, index) => (
+ <text
+ key={line}
+ x={center}
+ y={titleY + (box.compact ? 26 : 30) + index * 24}
+ textAnchor="middle"
+ className="fill-fd-muted-foreground font-sans text-[15.5px]"
+ >
+ {line}
+ </text>
+ ))}
+ {box.footer && (
+ <text
+ x={center}
+ y={box.y + box.height - 16}
+ textAnchor="middle"
+ className="fill-fd-muted-foreground font-mono text-[12px] font-semibold uppercase tracking-[0.12em]"
+ >
+ {box.footer}
+ </text>
+ )}
+ </g>
+ );
+}
+
+function Arrow({ x1, y1, x2, y2 }: { x1: number; y1: number; x2: number; y2: number }) {
+ return (
+ <line
+ x1={x1}
+ y1={y1}
+ x2={x2}
+ y2={y2}
+ stroke="currentColor"
+ strokeWidth={1.6}
+ markerEnd="url(#agent-turn-arrow)"
+ />
+ );
+}
+
+// A label placed at x, led by a numbered badge matching the steps under the diagram.
+// Without a step, it's a plain label.
+function Step({
+ x,
+ y,
+ step,
+ text,
+ anchor = "middle",
+}: {
+ x: number;
+ y: number;
+ step?: number;
+ text: string;
+ anchor?: "middle" | "start" | "end";
+}) {
+ if (step === undefined) {
+ return (
+ <text x={x} y={y} textAnchor={anchor} className={label}>
+ {text}
+ </text>
+ );
+ }
+
+ const badge = 22;
+ const gap = 8;
+ const textWidth = text.length * labelCharWidth;
+ const total = badge + gap + textWidth;
+ const left = anchor === "middle" ? x - total / 2 : anchor === "start" ? x : x - total;
+ return (
+ <g>
+ <circle cx={left + badge / 2} cy={y - 5} r={badge / 2} className="fill-fd-foreground" />
+ <text
+ x={left + badge / 2}
+ y={y - 1}
+ textAnchor="middle"
+ className="fill-fd-background font-mono text-[12px] font-bold"
+ >
+ {step}
+ </text>
+ <text x={left + badge + gap} y={y} className={label}>
+ {text}
+ </text>
+ </g>
+ );
+}
+
+/** Pass `showSteps={false}` where the numbered steps aren't listed alongside the diagram. */
+export function AgentTurnDiagram({ showSteps = true }: { showSteps?: boolean }) {
+ const step = (n: number) => (showSteps ? n : undefined);
+ return (
+ <figure className="not-prose my-8 overflow-x-auto">
+ <svg
+ viewBox="0 0 1020 500"
+ role="img"
+ aria-labelledby="agent-turn-title agent-turn-description"
+ className="h-auto w-full min-w-[640px] text-fd-foreground"
+ >
+ <title id="agent-turn-title">One turn of an OpenUI agent</title>
+ <desc id="agent-turn-description">
+ The chat UI sends the user&apos;s message to the agent backend. The backend sends the
+ model a system prompt that includes OpenUI instructions, along with the messages. The
+ model may call tools, which the backend runs and returns results for. The model streams
+ OpenUI Lang to the backend, which forwards the stream to the chat UI, where the renderer
+ draws components as lines arrive. When the user clicks a button in the generated
+ interface, the chat UI sends the action and form values to the backend as a new turn.
+ </desc>
+ <defs>
+ <marker
+ id="agent-turn-arrow"
+ viewBox="0 0 10 10"
+ refX="9"
+ refY="5"
+ markerWidth="11"
+ markerHeight="11"
+ markerUnits="userSpaceOnUse"
+ orient="auto-start-reverse"
+ >
+ <path
+ d="M1 1 L9 5 L1 9"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="1.6"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </marker>
+ </defs>
+
+ {/* Requests read left to right above their arrows, replies right to left below. */}
+ {/* 1. The message goes to the backend; 2. the backend prompts the model. */}
+ <Arrow x1={214} y1={90} x2={404} y2={90} />
+ <Step x={310} y={76} step={step(1)} text="Message" />
+ <Arrow x1={614} y1={90} x2={804} y2={90} />
+ <Step x={710} y={76} step={step(2)} text="Prompt" />
+
+ {/* 3. Tools run in the backend between model calls. */}
+ <Arrow x1={490} y1={294} x2={490} y2={364} />
+ <Arrow x1={530} y1={366} x2={530} y2={296} />
+ <Step x={478} y={336} step={step(3)} text="Tool call" anchor="end" />
+ <text x={542} y={336} className={label}>
+ Result
+ </text>
+
+ {/* 4. OpenUI Lang streams back through the backend to the chat UI. */}
+ <Arrow x1={806} y1={140} x2={616} y2={140} />
+ <Step x={710} y={168} step={step(4)} text="OpenUI Lang" />
+ <Arrow x1={406} y1={140} x2={216} y2={140} />
+ <text x={310} y={168} textAnchor="middle" className={label}>
+ Stream
+ </text>
+
+ {/* 6. A click in the generated interface becomes a new turn. */}
+ <Arrow x1={214} y1={240} x2={404} y2={240} />
+ <Step x={310} y={226} step={step(6)} text="Action" />
+ <text
+ x={310}
+ y={264}
+ textAnchor="middle"
+ className="fill-fd-muted-foreground font-sans text-[14px]"
+ >
+ with form values
+ </text>
+
+ {boxes.map((box) => (
+ <BoxNode key={box.title} box={box} />
+ ))}
+
+ {/* 5. Rendering happens inside the chat UI. */}
+ {showSteps && <Step x={26} y={47} step={5} text="Render" anchor="start" />}
+ </svg>
+ </figure>
+ );
+}
diff --git a/docs/components/docs-route-layout.tsx b/docs/components/docs-route-layout.tsx
index 98763a49b..4aa5d7639 100644
--- a/docs/components/docs-route-layout.tsx
+++ b/docs/components/docs-route-layout.tsx
@@ -55,9 +55,35 @@ function GlobalSidebarItem({ item }: { item: PageTree.Item }) {
);
}
+function isOtherSectionEntry(url: string, root: NestedDocsRoot): boolean {
+ const target = getNestedRootForEntryUrl(url);
+ return target !== undefined && target !== root;
+}
+
+// Inside a nested sidebar, links into another nested section get the same chevron as global entries.
+function withSectionChevrons(tree: PageTree.Root, root: NestedDocsRoot): PageTree.Root {
+ return {
+ ...tree,
+ children: tree.children.map((node) =>
+ node.type === "page" && isOtherSectionEntry(node.url, root)
+ ? {
+ ...node,
+ name: (
+ <span className="flex flex-1 items-center gap-2">
+ <span className="min-w-0 flex-1">{node.name}</span>
+ <ChevronRight aria-hidden className="ms-auto" size={16} />
+ </span>
+ ),
+ }
+ : node,
+ ),
+ };
+}
+
function NestedSidebarHeader({ root }: { root: NestedDocsRoot }) {
- const { showGlobal } = useDocsNavigation();
+ const { enterNested, showGlobal } = useDocsNavigation();
const { setOpen } = useSidebar();
+ const parent = NESTED_DOCS_SECTIONS[root].parent;
return (
<div className="flex flex-col gap-4">
@@ -65,12 +91,16 @@ function NestedSidebarHeader({ root }: { root: NestedDocsRoot }) {
type="button"
className="flex items-center gap-2 rounded-lg p-2 text-sm text-fd-muted-foreground transition-colors hover:bg-fd-accent/50 hover:text-fd-accent-foreground"
onClick={() => {
+ if (parent) {
+ enterNested(parent);
+ return;
+ }
showGlobal();
setOpen(false);
}}
>
<ChevronLeft aria-hidden className="size-4" />
- All docs
+ {parent ? NESTED_DOCS_SECTIONS[parent].title : "All docs"}
</button>
<p className="px-2 text-sm font-semibold text-fd-foreground">
{NESTED_DOCS_SECTIONS[root].title}
@@ -107,7 +137,9 @@ export function DocsRouteLayout({ tree, children }: DocsRouteLayoutProps) {
sidebarMode.kind === "global" || sidebarMode.kind === "nested" ? undefined : sidebarMode.kind;
const activeTree = useMemo(() => {
if (tabFolder) return getTabTree(tree, tabFolder);
- return nestedRoot ? getNestedDocsTree(tree, nestedRoot) : GLOBAL_DOCS_TREE;
+ return nestedRoot
+ ? withSectionChevrons(getNestedDocsTree(tree, nestedRoot), nestedRoot)
+ : GLOBAL_DOCS_TREE;
}, [tabFolder, nestedRoot, tree]);
return (
diff --git a/docs/content/docs/agent/core-concepts/tools.mdx b/docs/content/docs/agent/core-concepts/tools.mdx
deleted file mode 100644
index 50a9632b4..000000000
--- a/docs/content/docs/agent/core-concepts/tools.mdx
+++ /dev/null
@@ -1,57 +0,0 @@
----
-title: Tools
-description: Let the agent call functions to fetch data and take actions.
----
-
-A chat model can only produce text. A **tool** is a function you give the agent so it can do more: fetch the weather, query your database, file a ticket. The result folds back into the conversation.
-
-The loop:
-
-1. The model proposes a tool: a **name** plus **arguments**.
-2. **Your code runs it.** It calls an API, reads a database, or does whatever the tool does.
-3. The **result returns to the conversation**, and the agent continues, usually turning it into a final answer.
-
-```
-user: "What's the weather in Tokyo?"
- └─ model proposes: get_weather({ city: "Tokyo" })
- └─ your code runs it → { tempC: 22, sky: "clear" }
- └─ result returns to the agent
- └─ agent: "It's 22°C and clear in Tokyo right now."
-```
-
-The trust boundary stays in your code. The model only proposes which tool to call and with what arguments. Execution, provider keys, and the tool implementations live on the server and never reach the browser.
-
-<video
- src="/videos/agent/tool-call-web-search.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-## Integrate your own tool
-
-A tool is a **name**, a **description**, and a **JSON Schema** for its arguments. The model uses the description and schema to decide when and how to call it, so write them like prompts.
-
-```ts
-const tools = [
- {
- type: "function",
- name: "get_weather",
- description: "Get the current weather for a city.",
- parameters: {
- type: "object",
- properties: {
- city: { type: "string", description: "City name, e.g. 'Tokyo'" },
- },
- required: ["city"],
- additionalProperties: false,
- },
- },
-];
-```
-
-That declaration is what the model sees. The implementation, the code that actually fetches the weather, stays private and runs only when the agent calls the tool.
-
-Your application runs these functions on the server and returns their results to the agent.
diff --git a/docs/content/docs/agent/getting-started/introduction.mdx b/docs/content/docs/agent/getting-started/introduction.mdx
index dc23e1894..14bac6e32 100644
--- a/docs/content/docs/agent/getting-started/introduction.mdx
+++ b/docs/content/docs/agent/getting-started/introduction.mdx
@@ -7,6 +7,22 @@ Agent Interface is OpenUI's optional React SDK for teams that want a complete ch
It provides conversation layout, threads, streaming messages, tool activity, and generated OpenUI components in one customizable interface. OpenUI Lang remains the interchange format, and you can connect Agent Interface to your existing agent backend.
+<div className="not-prose my-6 overflow-hidden rounded-xl border border-fd-border">
+ <video
+ src="/videos/openui-introduction.mp4"
+ poster="/videos/openui-introduction-poster.jpg"
+ aria-label="An OpenUI agent answering a question with a generated interface of stat cards and tables"
+ autoPlay
+ muted
+ loop
+ playsInline
+ preload="metadata"
+ className="block h-auto w-full"
+ />
+</div>
+
+[Try the live demo →](/chat)
+
## When to use Agent Interface
Choose Agent Interface when you want OpenUI to provide the complete agent UI shell. If an application already has a conversation framework, follow the [Build Agents guides](/docs/build-agents) to add the OpenUI Lang renderer instead.
diff --git a/docs/content/docs/agent/meta.json b/docs/content/docs/agent/meta.json
index b26f12262..d6a095cbf 100644
--- a/docs/content/docs/agent/meta.json
+++ b/docs/content/docs/agent/meta.json
@@ -21,11 +21,6 @@
"reference/hooks",
"reference/adapters-and-formats",
"reference/define-artifact-renderer",
- "reference/self-hosting",
- "---Examples---",
- "agent-runtimes/vercel-ai-sdk",
- "agent-runtimes/langgraph-platform",
- "agent-runtimes/pi",
- "agent-runtimes/vercel-eve"
+ "reference/self-hosting"
]
}
diff --git a/docs/content/docs/agent/reference/adapters-and-formats.mdx b/docs/content/docs/agent/reference/adapters-and-formats.mdx
index e417aa9b4..5a2cd697f 100644
--- a/docs/content/docs/agent/reference/adapters-and-formats.mdx
+++ b/docs/content/docs/agent/reference/adapters-and-formats.mdx
@@ -507,7 +507,7 @@ const llm: ChatLLM = {
- **What it handles:** `actions.requested` → `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END`; `action.result` → `TOOL_CALL_RESULT`; `message.appended` → `TEXT_MESSAGE_CONTENT` (with `message.completed` as the fallback for steps that streamed no deltas); `input.requested` → a `CUSTOM` event named `eve.input.requested` (exported as `EVE_INPUT_REQUESTED_EVENT`); `turn.failed` / `session.failed` → `RUN_ERROR`. Tool calls and text share one assistant message id. Parsing stops at the turn boundary (`session.completed`, `session.waiting`, `session.failed`).
- **Options** (`EveAdapterOptions`):
- `onEvent?: (event: EveStreamEvent) => void` — receives every raw Eve event before translation, including types the adapter does not map (`session.started`, `reasoning.appended`, …).
-- **When to use:** Your browser talks to an Eve session directly (or through a same-origin proxy such as `withEve()`) and you want Eve's turns rendered by `AgentInterface`. Eve keeps the conversation server-side, so there is no paired message format: `send` delivers only the latest user turn and returns the session stream. See [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) for the complete bridge.
+- **When to use:** Your browser talks to an Eve session directly (or through a same-origin proxy such as `withEve()`) and you want Eve's turns rendered by `AgentInterface`. Eve keeps the conversation server-side, so there is no paired message format: `send` delivers only the latest user turn and returns the session stream. See [Vercel Eve](/docs/build-agents/frameworks/vercel-eve) for the complete bridge.
### AG-UI event vocabulary
diff --git a/docs/content/docs/agent/reference/self-hosting.mdx b/docs/content/docs/agent/reference/self-hosting.mdx
index 3cb4122bb..2c6865cc7 100644
--- a/docs/content/docs/agent/reference/self-hosting.mdx
+++ b/docs/content/docs/agent/reference/self-hosting.mdx
@@ -184,7 +184,7 @@ const llm = fetchLLM({
});
```
-To let the model call tools, declare provider-format tools on the request, run the ones it asks for, and emit the matching `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END` / `TOOL_CALL_RESULT` events between the text events, looping back to the provider with each result until it returns a turn with no tool calls. (`TOOL_CALL_RESULT.content` is always a string.) See [Tools](/docs/agent/core-concepts/tools).
+To let the model call tools, declare provider-format tools on the request, run the ones it asks for, and emit the matching `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END` / `TOOL_CALL_RESULT` events between the text events, looping back to the provider with each result until it returns a turn with no tool calls. (`TOOL_CALL_RESULT.content` is always a string.) See [Tools](/docs/build-agents/tools).
## 2. Stream — your route must stream
diff --git a/docs/content/docs/build-agents/assistant-ui.mdx b/docs/content/docs/build-agents/assistant-ui.mdx
index 01f7ed235..cdde384b8 100644
--- a/docs/content/docs/build-agents/assistant-ui.mdx
+++ b/docs/content/docs/build-agents/assistant-ui.mdx
@@ -3,32 +3,113 @@ title: assistant-ui
description: Render OpenUI Lang in an existing assistant-ui chat.
---
-This guide assumes the application already has a working assistant-ui chat. First, follow the [backend setup guide](/docs/build-agents/backend-setup) to configure the agent to return OpenUI Lang.
+This guide assumes the application already has a working [assistant-ui](https://www.assistant-ui.com) chat, and that its backend responds with OpenUI Lang. If it doesn't yet, follow [Set up UI generation](/docs/build-agents/ui-generation) first.
-In the existing `AssistantMessage` component, replace the Markdown text renderer passed to [`MessagePrimitive.Parts`](https://www.assistant-ui.com/docs/primitives/message) with the OpenUI Lang renderer. The thread shell, composer, runtime, and message layout remain unchanged.
+The change is in one place: the assistant message's text part. The thread, composer, runtime, and message layout stay the same.
+
+## Install
+
+Skip this step if the chat UI and the backend share a package and you already installed these in [Set up UI generation](/docs/build-agents/ui-generation#1-install-the-packages).
+
+```bash tab="pnpm" tab-group="pkg"
+pnpm add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="bun" tab-group="pkg"
+bun add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="yarn" tab-group="pkg"
+yarn add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="npm" tab-group="pkg"
+npm install @openuidev/react-lang @openuidev/react-ui
+```
+
+`@openuidev/react-lang` renders OpenUI Lang. `@openuidev/react-ui` provides the built-in component library and its styles; if the agent uses only your own components, skip it and the styles import below.
+
+When using the built-in library, import its styles once, from the application's global stylesheet:
+
+```css title="app/globals.css"
+@import "@openuidev/react-ui/styles/index.css";
+```
+
+The examples below import `library` from `src/lib/openui.tsx`, the file created in [Set up UI generation](/docs/build-agents/ui-generation#2-define-a-component-library). If the chat UI lives in a separate package, define the same library there so it renders every component the agent can write.
## Render OpenUI Lang
+In the existing `AssistantMessage` component, replace the Markdown text renderer passed to [`MessagePrimitive.Parts`](https://www.assistant-ui.com/docs/primitives/message) with the OpenUI renderer:
+
```tsx title="src/components/assistant-message.tsx"
"use client";
-import { type TextMessagePartProps } from "@assistant-ui/react";
+import { MessagePrimitive, type TextMessagePartProps } from "@assistant-ui/react";
import { Renderer } from "@openuidev/react-lang";
-import { openuiLibrary } from "@openuidev/react-ui";
+import { library } from "@/lib/openui";
+
+function OpenUIText({ text, status }: TextMessagePartProps) {
+ return <Renderer response={text} library={library} isStreaming={status.type === "running"} />;
+}
-function OpenUIRenderer({ text, status }: TextMessagePartProps) {
+export function AssistantMessage() {
return (
- <Renderer response={text} library={openuiLibrary} isStreaming={status.type === "running"} />
+ <MessagePrimitive.Root>
+ <MessagePrimitive.Parts components={{ Text: OpenUIText }} />
+ </MessagePrimitive.Root>
);
}
```
-Then update the existing message-parts configuration:
+`text` is the accumulated response supplied by assistant-ui, and `status.type` stays `"running"` until the stream closes, so the renderer draws each component as it arrives.
-```tsx
-<MessagePrimitive.Parts components={{ Text: OpenUIRenderer }} />
-```
+See [The Renderer](/docs/openui-lang/renderer) for all of its props, including error handling.
+
+## Handle actions
+
+Buttons, follow-ups, and forms in a generated interface report clicks through the renderer's `onAction` callback. Without it, they do nothing. Handle the two built-in action types:
+
+- `continue_conversation`: send a new user turn. Include the form values so the model knows what the user entered, as described in [Conversation history](/docs/build-agents/conversation-history#user-actions).
+- `open_url`: open `event.params.url` in a new tab.
+
+Append the user turn with assistant-ui's `useAui()` API:
+
+```tsx title="src/components/assistant-message.tsx"
+"use client";
+
+import { useAui, type TextMessagePartProps } from "@assistant-ui/react";
+import { BuiltinActionType, Renderer, type ActionEvent } from "@openuidev/react-lang";
+import { library } from "@/lib/openui";
-`text` is the accumulated agent response supplied by assistant-ui.
+function toModelMessage(event: ActionEvent) {
+ const lines = [`User clicked: ${event.humanFriendlyMessage}`];
+ if (event.formState) lines.push(`Form values: ${JSON.stringify(event.formState)}`);
+ return lines.join("\n");
+}
+
+function OpenUIText({ text, status }: TextMessagePartProps) {
+ const aui = useAui();
+
+ const onAction = (event: ActionEvent) => {
+ if (event.type === BuiltinActionType.ContinueConversation) {
+ aui.thread.append({
+ role: "user",
+ content: [{ type: "text", text: toModelMessage(event) }],
+ });
+ } else if (event.type === BuiltinActionType.OpenUrl) {
+ window.open(String(event.params?.url), "_blank", "noopener,noreferrer");
+ }
+ };
+
+ return (
+ <Renderer
+ response={text}
+ library={library}
+ isStreaming={status.type === "running"}
+ onAction={onAction}
+ />
+ );
+}
+```
-Continue with [The Renderer](/docs/openui-lang/renderer) for the complete API.
+The appended message starts a new run, just like a message typed in the composer.
diff --git a/docs/content/docs/build-agents/backend-setup.mdx b/docs/content/docs/build-agents/backend-setup.mdx
deleted file mode 100644
index 9f28768ba..000000000
--- a/docs/content/docs/build-agents/backend-setup.mdx
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: Backend setup
-description: Configure an existing agent backend to generate reliable OpenUI Lang.
----
-
-Keep the existing agent framework, model tools, and streaming transport. To generate OpenUI Lang, define the components the agent can use and add their generated instructions to its system prompt.
-
-## 1. Define a component library
-
-Create a custom library for the application's design system, or start with OpenUI's built-in library:
-
-```tsx title="src/lib/openui.tsx" tab="Custom" tab-group="component-library"
-import { createLibrary } from "@openuidev/react-lang";
-import { Chart, Metric, Stack } from "./components";
-
-export const library = createLibrary({
- root: "Stack",
- components: [Stack, Metric, Chart],
-});
-```
-
-```tsx title="src/lib/openui.tsx" tab="OpenUI Lang" tab-group="component-library"
-export {
- openuiLibrary as library,
- openuiPromptOptions as promptOptions,
-} from "@openuidev/react-ui";
-```
-
-See [Defining Components](/docs/openui-lang/defining-components) to create a custom component library.
-
-## 2. Export the prompt specification
-
-Use the OpenUI CLI to serialize the component library for the backend:
-
-```bash
-npx @openuidev/cli@latest generate src/lib/openui.tsx --spec --out src/lib/openui.spec.json
-```
-
-Regenerate the specification whenever the component library changes.
-
-## 3. Update the system prompt
-
-Generate the OpenUI Lang instructions from the exported specification:
-
-```ts title="server.ts"
-import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";
-import library from "./openui.spec.json";
-
-const openuiInstructions = generateSystemPrompt({
- library: library as LibrarySpec,
-});
-```
-
-Pass `openuiInstructions` directly through the framework's system-instruction option. The agent will respond with OpenUI Lang instead of plain text or Markdown.
-
-## 4. Add reliability with Gateway
-
-Route model requests through Gateway to correct invalid OpenUI Lang and automatically fall back to another provider when one is unavailable:
-
-```ts title="server.ts"
-import OpenAI from "openai";
-
-const gatewayInstructions = generateSystemPrompt({
- cloud: true,
- library: library as LibrarySpec,
-});
-
-const gateway = new OpenAI({
- apiKey: process.env.THESYS_API_KEY,
- baseURL: "https://api.thesys.dev/v1/embed",
-});
-
-const response = await gateway.chat.completions.create({
- model: "openai/gpt-5",
- messages: [{ role: "system", content: gatewayInstructions }, ...messages],
- stream: true,
-});
-```
-
-Use this client with the existing agent framework. Continue with the [Gateway documentation](/docs/gateway) for supported models and API options.
diff --git a/docs/content/docs/build-agents/chat-ui.mdx b/docs/content/docs/build-agents/chat-ui.mdx
new file mode 100644
index 000000000..e44d70cdf
--- /dev/null
+++ b/docs/content/docs/build-agents/chat-ui.mdx
@@ -0,0 +1,53 @@
+---
+title: Choose a chat UI
+description: Compare the chat UIs that can render OpenUI Lang and pick one for your agent.
+---
+
+The chat UI has two jobs in an OpenUI agent:
+
+1. **Render responses.** Pass the streamed OpenUI Lang to the renderer instead of a Markdown renderer.
+2. **Send actions back.** When the user clicks a button or submits a form in a generated interface, send it to the agent as a new user turn.
+
+Everything else, such as the message list, the composer, threads, and the transport, works as it did before. Use OpenUI's own chat UI, or keep the one you have.
+
+## Compare the options
+
+| | [Agent Interface](/docs/agent/getting-started/introduction) | [assistant-ui](/docs/build-agents/assistant-ui) | [CopilotKit](/docs/build-agents/copilotkit) | [Custom chat UI](/docs/build-agents/custom-chat-ui) |
+| :---------------------- | :---------------------------------------------------------- | :---------------------------------------------- | :------------------------------------------ | :-------------------------------------------------- |
+| **You start with** | No chat UI | An assistant-ui chat | A CopilotKit chat | A chat you built yourself |
+| **What OpenUI adds** | The whole chat UI | The assistant message's text part | The assistant message's Markdown renderer | The assistant message component |
+| **Actions** | Built in | `onAction` with `useAui()` | `onAction` with `useAgent()` | `onAction` with your send function |
+| **Threads and history** | Built in, with a storage adapter for your backend | assistant-ui's runtime | CopilotKit's runtime | Yours |
+| **Tool activity** | Built in | assistant-ui's tool UIs | CopilotKit's tool rendering | Yours |
+| **Best when** | You want a complete chat UI and don't have one yet | You already use assistant-ui | You already use CopilotKit | You own the chat UI and want full control |
+
+If you're starting a new chat UI, use Agent Interface. If you already have one, keep it: adding OpenUI changes a single component.
+
+## What every chat UI needs
+
+Whichever chat UI you pick, these pieces come up:
+
+- **The same component library as the agent.** Import `library` from the file created in [Set up UI generation](/docs/build-agents/ui-generation#2-define-a-component-library), so the renderer knows every component the agent can write.
+- **The component styles.** Import `@openuidev/react-ui/styles/index.css` once when using the built-in components.
+- **`isStreaming`.** Keep it true until the response stream closes, so the interface builds up as lines arrive.
+- **`onAction`.** Send `continue_conversation` events back as a user turn with the form values, and open `open_url` events in a new tab. See [Conversation history](/docs/build-agents/conversation-history#user-actions).
+- **`toolProvider` (optional).** Pass it when generated interfaces load live data with `Query()`. See [Tools](/docs/build-agents/tools#ui-side-tools).
+
+Agent Interface handles streaming and actions for you; pass it the library through its `componentLibrary` prop. The other guides show each piece in that chat UI's own API.
+
+## Guides
+
+<Cards>
+ <Card title="Agent Interface" href="/docs/agent/getting-started/introduction">
+ OpenUI's complete React chat UI, with threads, streaming, tool activity, and actions built in.
+ </Card>
+ <Card title="assistant-ui" href="/docs/build-agents/assistant-ui">
+ Keep assistant-ui in charge of the conversation while OpenUI renders the assistant's responses.
+ </Card>
+ <Card title="CopilotKit" href="/docs/build-agents/copilotkit">
+ Add OpenUI rendering to an application whose chat is built with CopilotKit.
+ </Card>
+ <Card title="Custom chat UI" href="/docs/build-agents/custom-chat-ui">
+ Connect an existing message list and composer directly to the OpenUI renderer.
+ </Card>
+</Cards>
diff --git a/docs/content/docs/build-agents/conversation-history.mdx b/docs/content/docs/build-agents/conversation-history.mdx
new file mode 100644
index 000000000..e3847d685
--- /dev/null
+++ b/docs/content/docs/build-agents/conversation-history.mdx
@@ -0,0 +1,76 @@
+---
+title: Conversation history
+description: Send earlier turns, tool results, and user actions back to the model.
+---
+
+Each model request contains the whole conversation so far. With OpenUI, earlier assistant turns are OpenUI Lang instead of Markdown, and some user turns come from clicks in a generated interface instead of the composer. This page covers what to send for each.
+
+## Earlier assistant turns
+
+Send each earlier assistant response back **as the OpenUI Lang it was generated as**, not as a summary or the rendered text:
+
+```ts
+const messages = [
+ { role: "user", content: "Show revenue by region" },
+ {
+ role: "assistant",
+ content: `root = Stack([CardHeader("Revenue by region"), chart])
+chart = BarChart(["NA", "EU", "APAC"], [Series("Revenue", [420, 310, 180])])`,
+ },
+ { role: "user", content: "Make it a pie chart" },
+];
+```
+
+The model then knows exactly which interface the user is looking at and can change it ("make it a pie chart", "add Q3") instead of starting over.
+
+Most chat UIs already store the assistant's raw text and resend it, so this usually needs no change.
+
+## Tool calls and results
+
+Keep agent-side tool calls and their results in the history the way the agent framework stores them. On later turns, the model can reuse the data instead of calling the tool again.
+
+UI-side tools are different: `Query()` and `Mutation()` run in the browser and their results never enter the conversation. The model sees the OpenUI Lang that declares the query, not the rows it loaded. If the agent needs that data to answer a follow-up, give it an agent-side tool that returns the same data.
+
+## User actions
+
+Buttons and follow-ups in a generated interface send a new user turn. The renderer reports them through `onAction` with a `continue_conversation` event:
+
+| Field | Contains |
+| :--------------------- | :----------------------------------------------------------- |
+| `humanFriendlyMessage` | The button or follow-up label, such as `"Book this flight"`. |
+| `formState` | The values of the form fields when the user clicked. |
+| `formName` | The form that scoped the action, if any. |
+
+Show `humanFriendlyMessage` in the chat as the user's message, but send the model the form values too. A label like "Submit" means nothing to the model without the data behind it:
+
+```ts
+function toModelMessage(event: ActionEvent) {
+ const lines = [`User clicked: ${event.humanFriendlyMessage}`];
+ if (event.formState) lines.push(`Form values: ${JSON.stringify(event.formState)}`);
+ return lines.join("\n");
+}
+```
+
+Each chat UI guide shows where to call this: [assistant-ui](/docs/build-agents/assistant-ui#handle-actions), [CopilotKit](/docs/build-agents/copilotkit#handle-actions), and [custom chat UI](/docs/build-agents/custom-chat-ui#handle-actions). [Agent Interface](/docs/agent/getting-started/introduction) does this automatically.
+
+## Form values on earlier turns
+
+When the user fills in a form and reloads the thread, the form would render empty again. To keep the values, save them with the message and restore them when rendering:
+
+```tsx
+<Renderer
+ response={message.content}
+ library={library}
+ initialState={message.formState}
+ onStateUpdate={(state) => saveFormState(message.id, state)}
+/>
+```
+
+`saveFormState` is your own persistence, for example a field on the message in your thread store. See [Interactivity](/docs/openui-lang/interactivity#form-state) for details.
+
+## Long conversations
+
+Generated interfaces are longer than typical chat replies, so long threads grow quickly. To keep requests small:
+
+- **Cache the prefix.** The system prompt and earlier turns rarely change. See [prompt caching](/docs/gateway/prompt-caching).
+- **Trim old turns.** For very long threads, keep the latest few interfaces in full and replace older assistant turns with a one-line summary of what they showed.
diff --git a/docs/content/docs/build-agents/copilotkit.mdx b/docs/content/docs/build-agents/copilotkit.mdx
index 85be2f93d..d777733d6 100644
--- a/docs/content/docs/build-agents/copilotkit.mdx
+++ b/docs/content/docs/build-agents/copilotkit.mdx
@@ -3,19 +3,53 @@ title: CopilotKit
description: Render OpenUI Lang in an existing CopilotKit chat.
---
-This guide assumes the application already has a working CopilotKit chat. First, follow the [backend setup guide](/docs/build-agents/backend-setup) to configure the agent to return OpenUI Lang. Then replace CopilotKit's [`assistantMessage.markdownRenderer`](https://docs.copilotkit.ai/custom-look-and-feel/slots#assistantmessage-sub-slots) slot with the OpenUI Lang renderer.
+This guide assumes the application already has a working [CopilotKit](https://docs.copilotkit.ai) chat built with `CopilotChat`, and that its agent responds with OpenUI Lang. If it doesn't yet, follow [Set up UI generation](/docs/build-agents/ui-generation) first.
+
+The change is in one place: CopilotKit's [`assistantMessage.markdownRenderer`](https://docs.copilotkit.ai/custom-look-and-feel/slots#assistantmessage-sub-slots) slot. The chat, agent, and runtime stay the same.
+
+## Install
+
+Skip this step if the chat UI and the backend share a package and you already installed these in [Set up UI generation](/docs/build-agents/ui-generation#1-install-the-packages).
+
+```bash tab="pnpm" tab-group="pkg"
+pnpm add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="bun" tab-group="pkg"
+bun add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="yarn" tab-group="pkg"
+yarn add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="npm" tab-group="pkg"
+npm install @openuidev/react-lang @openuidev/react-ui
+```
+
+`@openuidev/react-lang` renders OpenUI Lang. `@openuidev/react-ui` provides the built-in component library and its styles; if the agent uses only your own components, skip it and the styles import below.
+
+When using the built-in library, import its styles once, from the application's global stylesheet:
+
+```css title="app/globals.css"
+@import "@openuidev/react-ui/styles/index.css";
+```
+
+The examples below import `library` from `src/lib/openui.tsx`, the file created in [Set up UI generation](/docs/build-agents/ui-generation#2-define-a-component-library). If the chat UI lives in a separate package, define the same library there so it renders every component the agent can write.
## Render OpenUI Lang
+Pass the OpenUI renderer as the assistant message's Markdown renderer:
+
```tsx title="src/components/chat.tsx"
"use client";
import { CopilotChat } from "@copilotkit/react-core/v2";
import { Renderer } from "@openuidev/react-lang";
-import { openuiLibrary } from "@openuidev/react-ui";
+import { library } from "@/lib/openui";
function OpenUIRenderer({ content }: { content: string }) {
- return <Renderer response={content} library={openuiLibrary} />;
+ return <Renderer response={content} library={library} />;
}
export function Chat() {
@@ -31,6 +65,59 @@ export function Chat() {
}
```
-`content` is the accumulated agent response supplied by CopilotKit.
+`content` is the accumulated response supplied by CopilotKit. The renderer re-parses it as it grows, so the interface builds up while the response streams.
+
+See [The Renderer](/docs/openui-lang/renderer) for all of its props, including error handling.
+
+## Handle actions
+
+Buttons, follow-ups, and forms in a generated interface report clicks through the renderer's `onAction` callback. Without it, they do nothing. Handle the two built-in action types:
+
+- `continue_conversation`: send a new user turn. Include the form values so the model knows what the user entered, as described in [Conversation history](/docs/build-agents/conversation-history#user-actions).
+- `open_url`: open `event.params.url` in a new tab.
+
+Add the user turn to the agent and run it, as described in CopilotKit's [programmatic control](https://docs.copilotkit.ai/programmatic-control) guide:
+
+```tsx title="src/components/chat.tsx"
+"use client";
+
+import { CopilotChat, useAgent, useCopilotKit } from "@copilotkit/react-core/v2";
+import { BuiltinActionType, Renderer, type ActionEvent } from "@openuidev/react-lang";
+import { library } from "@/lib/openui";
+
+function toModelMessage(event: ActionEvent) {
+ const lines = [`User clicked: ${event.humanFriendlyMessage}`];
+ if (event.formState) lines.push(`Form values: ${JSON.stringify(event.formState)}`);
+ return lines.join("\n");
+}
+
+function OpenUIRenderer({ content }: { content: string }) {
+ const { agent } = useAgent();
+ const { copilotkit } = useCopilotKit();
+
+ const onAction = (event: ActionEvent) => {
+ if (event.type === BuiltinActionType.ContinueConversation) {
+ agent.addMessage({ id: crypto.randomUUID(), role: "user", content: toModelMessage(event) });
+ void copilotkit.runAgent({ agent });
+ } else if (event.type === BuiltinActionType.OpenUrl) {
+ window.open(String(event.params?.url), "_blank", "noopener,noreferrer");
+ }
+ };
+
+ return <Renderer response={content} library={library} onAction={onAction} />;
+}
+
+export function Chat() {
+ return (
+ <CopilotChat
+ messageView={{
+ assistantMessage: {
+ markdownRenderer: OpenUIRenderer,
+ },
+ }}
+ />
+ );
+}
+```
-Continue with [The Renderer](/docs/openui-lang/renderer) for the complete API.
+`copilotkit.runAgent` is the same entry point `CopilotChat` uses when the user sends a message, so the new turn streams into the chat as usual.
diff --git a/docs/content/docs/build-agents/custom-chat-ui.mdx b/docs/content/docs/build-agents/custom-chat-ui.mdx
index 0dce263b7..b3b6d0ce4 100644
--- a/docs/content/docs/build-agents/custom-chat-ui.mdx
+++ b/docs/content/docs/build-agents/custom-chat-ui.mdx
@@ -1,23 +1,109 @@
---
-title: Custom Chat UI
-description: Render OpenUI Lang in an existing chat interface.
+title: Custom chat UI
+description: Render OpenUI Lang in a chat interface you built yourself.
---
-This guide assumes the application already has a working chat interface that renders text or Markdown, and that the backend already returns streamed OpenUI Lang. The message list, composer, conversation state, and transport remain unchanged.
+This guide assumes the application already has a working chat interface that renders text or Markdown, and that its backend streams OpenUI Lang. If it doesn't yet, follow [Set up UI generation](/docs/build-agents/ui-generation) first.
+
+The message list, composer, conversation state, and transport stay the same. Only the assistant message changes.
+
+## Install
+
+Skip this step if the chat UI and the backend share a package and you already installed these in [Set up UI generation](/docs/build-agents/ui-generation#1-install-the-packages).
+
+```bash tab="pnpm" tab-group="pkg"
+pnpm add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="bun" tab-group="pkg"
+bun add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="yarn" tab-group="pkg"
+yarn add @openuidev/react-lang @openuidev/react-ui
+```
+
+```bash tab="npm" tab-group="pkg"
+npm install @openuidev/react-lang @openuidev/react-ui
+```
+
+`@openuidev/react-lang` renders OpenUI Lang. `@openuidev/react-ui` provides the built-in component library and its styles; if the agent uses only your own components, skip it and the styles import below.
+
+When using the built-in library, import its styles once, from the application's global stylesheet:
+
+```css title="app/globals.css"
+@import "@openuidev/react-ui/styles/index.css";
+```
+
+The examples below import `library` from `src/lib/openui.tsx`, the file created in [Set up UI generation](/docs/build-agents/ui-generation#2-define-a-component-library). If the chat UI lives in a separate package, define the same library there so it renders every component the agent can write.
## Render OpenUI Lang
-In the assistant-message component, render the streamed response with `<Renderer />` instead of the Markdown renderer:
+In the assistant message component, render the streamed response with `<Renderer />` instead of the Markdown renderer:
```tsx title="src/components/assistant-message.tsx"
+"use client";
+
import { Renderer } from "@openuidev/react-lang";
import { library } from "@/lib/openui";
-export function AssistantMessage({ content, isStreaming }) {
+export function AssistantMessage({
+ content,
+ isStreaming,
+}: {
+ content: string;
+ isStreaming: boolean;
+}) {
return <Renderer response={content} library={library} isStreaming={isStreaming} />;
}
```
-`content` is the accumulated agent response. Keep `isStreaming` true until the response stream closes so the renderer can display the interface progressively.
+`content` is the accumulated response text. Keep `isStreaming` true until the response stream closes so the renderer displays the interface progressively.
+
+See [The Renderer](/docs/openui-lang/renderer) for all of its props, including error handling.
+
+## Handle actions
+
+Buttons, follow-ups, and forms in a generated interface report clicks through the renderer's `onAction` callback. Without it, they do nothing. Handle the two built-in action types:
+
+- `continue_conversation`: send a new user turn. Include the form values so the model knows what the user entered, as described in [Conversation history](/docs/build-agents/conversation-history#user-actions).
+- `open_url`: open `event.params.url` in a new tab.
+
+Pass the chat's existing send function to the assistant message, and call it from `onAction`:
+
+```tsx title="src/components/assistant-message.tsx"
+"use client";
+
+import { BuiltinActionType, Renderer, type ActionEvent } from "@openuidev/react-lang";
+import { library } from "@/lib/openui";
+
+function toModelMessage(event: ActionEvent) {
+ const lines = [`User clicked: ${event.humanFriendlyMessage}`];
+ if (event.formState) lines.push(`Form values: ${JSON.stringify(event.formState)}`);
+ return lines.join("\n");
+}
+
+export function AssistantMessage({
+ content,
+ isStreaming,
+ onSend,
+}: {
+ content: string;
+ isStreaming: boolean;
+ onSend: (message: { display: string; content: string }) => void;
+}) {
+ const onAction = (event: ActionEvent) => {
+ if (event.type === BuiltinActionType.ContinueConversation) {
+ onSend({ display: event.humanFriendlyMessage, content: toModelMessage(event) });
+ } else if (event.type === BuiltinActionType.OpenUrl) {
+ window.open(String(event.params?.url), "_blank", "noopener,noreferrer");
+ }
+ };
+
+ return (
+ <Renderer response={content} library={library} isStreaming={isStreaming} onAction={onAction} />
+ );
+}
+```
-Continue with [The Renderer](/docs/openui-lang/renderer) for the complete API.
+`onSend` stands in for however the chat sends a message today. Show `display` in the message list, and send `content` to the backend so the model sees the form values.
diff --git a/docs/content/docs/agent/agent-runtimes/langgraph-platform.mdx b/docs/content/docs/build-agents/frameworks/langgraph.mdx
similarity index 91%
rename from docs/content/docs/agent/agent-runtimes/langgraph-platform.mdx
rename to docs/content/docs/build-agents/frameworks/langgraph.mdx
index 411baf3d1..f5688883f 100644
--- a/docs/content/docs/agent/agent-runtimes/langgraph-platform.mdx
+++ b/docs/content/docs/build-agents/frameworks/langgraph.mdx
@@ -124,11 +124,7 @@ const llm = fetchLLM({
streamAdapter: agUIAdapter(),
});
-<AgentInterface
- llm={llm}
- componentLibrary={openuiLibrary}
- agentName="OpenUI + DeepAgents Chat"
-/>;
+<AgentInterface llm={llm} componentLibrary={openuiLibrary} agentName="OpenUI + DeepAgents Chat" />;
```
## Project layout
@@ -206,3 +202,13 @@ LANGSMITH_API_KEY=lsv2-...
`LANGSMITH_API_KEY` is sent as `x-api-key` only from the server route. Restart
the app after changing the environment.
+
+## Use a different chat UI
+
+This guide renders the agent with Agent Interface. The backend doesn't depend on it: to use another chat UI, keep the backend from this guide, connect the chat UI to LangGraph with that chat UI's own integration, then follow its OpenUI guide to render responses and handle actions.
+
+<Cards>
+ <Card title="assistant-ui" href="/docs/build-agents/assistant-ui" />
+ <Card title="CopilotKit" href="/docs/build-agents/copilotkit" />
+ <Card title="Custom chat UI" href="/docs/build-agents/custom-chat-ui" />
+</Cards>
diff --git a/docs/content/docs/build-agents/frameworks/meta.json b/docs/content/docs/build-agents/frameworks/meta.json
new file mode 100644
index 000000000..54a398fac
--- /dev/null
+++ b/docs/content/docs/build-agents/frameworks/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Agent frameworks",
+ "defaultOpen": false,
+ "pages": ["vercel-ai-sdk", "langgraph", "vercel-eve", "pi"]
+}
diff --git a/docs/content/docs/agent/agent-runtimes/pi.mdx b/docs/content/docs/build-agents/frameworks/pi.mdx
similarity index 93%
rename from docs/content/docs/agent/agent-runtimes/pi.mdx
rename to docs/content/docs/build-agents/frameworks/pi.mdx
index 261d3a16f..661e15420 100644
--- a/docs/content/docs/agent/agent-runtimes/pi.mdx
+++ b/docs/content/docs/build-agents/frameworks/pi.mdx
@@ -1,5 +1,5 @@
---
-title: Pi Agent Harness
+title: Pi
description: Connect Agent Interface to the pi coding agent over an OpenAI-compatible stream.
---
@@ -186,3 +186,13 @@ pnpm dev -- /path/to/your/project
```
Open [http://localhost:3000](http://localhost:3000) and try "Summarize the files in this project as a card" or "Read package.json and list its scripts". pi's tools run and the result renders as generative UI.
+
+## Use a different chat UI
+
+This guide renders the agent with Agent Interface. The backend doesn't depend on it: to use another chat UI, keep the backend from this guide, connect the chat UI to pi with that chat UI's own integration, then follow its OpenUI guide to render responses and handle actions.
+
+<Cards>
+ <Card title="assistant-ui" href="/docs/build-agents/assistant-ui" />
+ <Card title="CopilotKit" href="/docs/build-agents/copilotkit" />
+ <Card title="Custom chat UI" href="/docs/build-agents/custom-chat-ui" />
+</Cards>
diff --git a/docs/content/docs/agent/agent-runtimes/vercel-ai-sdk.mdx b/docs/content/docs/build-agents/frameworks/vercel-ai-sdk.mdx
similarity index 86%
rename from docs/content/docs/agent/agent-runtimes/vercel-ai-sdk.mdx
rename to docs/content/docs/build-agents/frameworks/vercel-ai-sdk.mdx
index dbb765e31..47f0a8430 100644
--- a/docs/content/docs/agent/agent-runtimes/vercel-ai-sdk.mdx
+++ b/docs/content/docs/build-agents/frameworks/vercel-ai-sdk.mdx
@@ -134,3 +134,13 @@ yarn dev
```bash tab="npm" tab-group="pkg"
npm run dev
```
+
+## Use a different chat UI
+
+This guide renders the agent with Agent Interface. The backend doesn't depend on it: to use another chat UI, keep the backend from this guide, connect the chat UI to the Vercel AI SDK with that chat UI's own integration, then follow its OpenUI guide to render responses and handle actions.
+
+<Cards>
+ <Card title="assistant-ui" href="/docs/build-agents/assistant-ui" />
+ <Card title="CopilotKit" href="/docs/build-agents/copilotkit" />
+ <Card title="Custom chat UI" href="/docs/build-agents/custom-chat-ui" />
+</Cards>
diff --git a/docs/content/docs/agent/agent-runtimes/vercel-eve.mdx b/docs/content/docs/build-agents/frameworks/vercel-eve.mdx
similarity index 94%
rename from docs/content/docs/agent/agent-runtimes/vercel-eve.mdx
rename to docs/content/docs/build-agents/frameworks/vercel-eve.mdx
index 574229169..eb9e92d64 100644
--- a/docs/content/docs/agent/agent-runtimes/vercel-eve.mdx
+++ b/docs/content/docs/build-agents/frameworks/vercel-eve.mdx
@@ -246,3 +246,13 @@ npm run eve:dev
npm run eve:build
npm run eve:start
```
+
+## Use a different chat UI
+
+This guide renders the agent with Agent Interface. The backend doesn't depend on it: to use another chat UI, keep the backend from this guide, connect the chat UI to Vercel Eve with that chat UI's own integration, then follow its OpenUI guide to render responses and handle actions.
+
+<Cards>
+ <Card title="assistant-ui" href="/docs/build-agents/assistant-ui" />
+ <Card title="CopilotKit" href="/docs/build-agents/copilotkit" />
+ <Card title="Custom chat UI" href="/docs/build-agents/custom-chat-ui" />
+</Cards>
diff --git a/docs/content/docs/build-agents/how-it-works.mdx b/docs/content/docs/build-agents/how-it-works.mdx
new file mode 100644
index 000000000..6b581c144
--- /dev/null
+++ b/docs/content/docs/build-agents/how-it-works.mdx
@@ -0,0 +1,31 @@
+---
+title: How it works
+description: What happens in one turn of an agent that responds with OpenUI Lang.
+---
+
+import { AgentTurnDiagram } from "@/components/agent-turn-diagram";
+
+An OpenUI agent is a regular agent with one change: it writes its responses in OpenUI Lang instead of Markdown. Everything else, from the agent loop and tools to the transport and the chat UI, stays the way it was.
+
+## One turn, end to end
+
+<AgentTurnDiagram />
+
+1. **The user sends a message.** The chat UI sends the conversation to the agent backend, as it would for any agent.
+2. **The agent prompts the model.** Its system prompt includes instructions generated from your component library, so the model knows which components exist and how to write OpenUI Lang. See [Set up UI generation](/docs/build-agents/ui-generation).
+3. **The model calls tools if it needs data.** The agent runs them and returns the results, exactly as before. See [Tools](/docs/build-agents/tools).
+4. **The model streams OpenUI Lang.** Instead of a Markdown answer, it writes OpenUI Lang that composes your components:
+
+ ```text
+ root = Stack([CardHeader("Q3 revenue", "Up 18% on Q2"), chart])
+ chart = BarChart(["Jul", "Aug", "Sep"], [Series("Revenue", [380, 410, 440])])
+ ```
+
+5. **The chat UI renders it.** The chat UI passes the accumulated text to the OpenUI renderer, which draws each component as soon as its line arrives. The renderer uses the same component library as the agent's prompt, so every component the agent writes is one the chat UI can draw.
+6. **The user interacts.** The chat UI sends user interactions in the generated interface, such as button clicks, follow-ups, and form submissions, back to the agent as a new user turn, and the loop continues. See [Conversation history](/docs/build-agents/conversation-history).
+
+## Where Gateway fits
+
+Models occasionally write invalid OpenUI Lang, such as an unknown component or a missing required prop. [Gateway](/docs/gateway) sits between the agent and the model provider: it corrects invalid output as it streams and fails over to another provider when one is unavailable. It's OpenAI-compatible, so most agent frameworks can use it by changing the base URL.
+
+To keep calling your provider directly, repair responses with [Autofix](/docs/autofix) instead. Gateway is optional either way: the turn above works the same without it.
diff --git a/docs/content/docs/build-agents/index.mdx b/docs/content/docs/build-agents/index.mdx
index bfd13db82..48450c676 100644
--- a/docs/content/docs/build-agents/index.mdx
+++ b/docs/content/docs/build-agents/index.mdx
@@ -1,46 +1,85 @@
---
title: Overview
-description: Add OpenUI Lang to an existing agent framework or chat UI.
+description: Build agents that respond with interactive interfaces made from your components.
---
-Add Generative UI to an agent built with any chat framework. Keep the existing conversation experience and render agent responses with OpenUI Lang.
+import { AgentTurnDiagram } from "@/components/agent-turn-diagram";
-OpenUI works with all agent frameworks and chat UIs. Instead of returning plain text or Markdown, the agent returns OpenUI Lang. The chat application passes that response to the OpenUI Lang renderer, which turns it into an interactive interface.
+Build an agent that answers with charts, forms, tables, and dashboards made from your own components, instead of plain text or Markdown.
-Every integration has two parts:
+<div className="not-prose my-6 overflow-hidden rounded-xl border border-fd-border">
+ <video
+ src="/videos/openui-introduction.mp4"
+ poster="/videos/openui-introduction-poster.jpg"
+ aria-label="An OpenUI agent answering a question with a generated interface of stat cards and tables"
+ autoPlay
+ muted
+ loop
+ playsInline
+ preload="metadata"
+ className="block h-auto w-full"
+ />
+</div>
-1. Add the instructions generated from the component library to the agent's system prompt.
-2. Render the streamed OpenUI Lang response in the chat UI.
+[Try the live demo →](/chat)
-<img
- src="/images/build-agents-architecture.svg"
- alt="Architecture diagram showing an existing chat UI sending a request to its backend, which calls model providers directly. The model returns OpenUI Lang, which the renderer displays in the chat UI."
-/>
+## Quickstart
-The backend can route model requests through the [Gateway](/docs/gateway) to correct invalid OpenUI Lang and fall back to another provider when a model provider is unavailable.
+To create a new agent app, run the OpenUI CLI and customize the project it generates. You need Node.js 20 or later:
+
+```bash
+npx @openuidev/cli@latest create
+```
+
+## How it works
+
+OpenUI works with any agent framework and chat UI. The agent writes its responses in [OpenUI Lang](/docs/openui-lang), and the chat UI renders them with the OpenUI renderer. The agent loop, tools, and conversation stay the way they are.
+
+<AgentTurnDiagram showSteps={false} />
+
+Every agent needs two changes:
+
+1. **The backend** adds instructions generated from the component library to the agent's system prompt, so the model writes OpenUI Lang.
+2. **The chat UI** renders the streamed OpenUI Lang with the renderer, and sends user interactions in the generated interface back to the agent.
+
+For a step-by-step walkthrough of one turn, read the [full explanation](/docs/build-agents/how-it-works).
## Set up the backend
<Cards>
- <Card title="Backend setup" href="/docs/build-agents/backend-setup">
- Define the component library, add its generated instructions to the agent, and improve
- reliability with Gateway.
+ <Card title="Set up UI generation" href="/docs/build-agents/ui-generation">
+ Define the component library and add its generated instructions to the agent.
+ </Card>
+ <Card title="Tools: agent-side vs. UI-side" href="/docs/build-agents/tools">
+ Fetch data in the agent before it responds, or let the generated UI fetch it live.
+ </Card>
+ <Card title="Conversation history" href="/docs/build-agents/conversation-history">
+ Send earlier turns, tool results, and user actions back to the model.
+ </Card>
+ <Card title="Agent frameworks" href="/docs/build-agents/frameworks/vercel-ai-sdk">
+ Complete guides for the Vercel AI SDK, LangGraph Platform, Vercel Eve, and Pi.
</Card>
</Cards>
## Choose a chat UI
+[Compare the options](/docs/build-agents/chat-ui) to see what each one handles for you.
+
<Cards>
+ <Card title="Agent Interface" href="/docs/agent/getting-started/introduction">
+ OpenUI's complete React chat UI, with threads, streaming, tool activity, and actions built in.
+ </Card>
<Card title="assistant-ui" href="/docs/build-agents/assistant-ui">
- Keep assistant-ui in charge of the conversation and tool lifecycle while OpenUI renders its
- generated interfaces.
+ Keep assistant-ui in charge of the conversation while OpenUI renders the assistant's responses.
</Card>
<Card title="CopilotKit" href="/docs/build-agents/copilotkit">
- Add OpenUI rendering to an application whose agent experience is built with CopilotKit.
+ Add OpenUI rendering to an application whose chat is built with CopilotKit.
</Card>
- <Card title="Custom Chat UI" href="/docs/build-agents/custom-chat-ui">
- Connect an existing message list and composer directly to the OpenUI Lang renderer.
+ <Card title="Custom chat UI" href="/docs/build-agents/custom-chat-ui">
+ Connect an existing message list and composer directly to the OpenUI renderer.
</Card>
</Cards>
-Starting without an existing chat UI? Use [Agent Interface](/docs/agent/getting-started/introduction) for a complete React chat experience.
+## Run it in production
+
+Route model requests through [Gateway](/docs/gateway) to correct invalid OpenUI Lang as it streams and fail over to another provider when one is unavailable. See [OpenUI in production](/docs/production) for Autofix, Reliability Monitoring, and deployment.
diff --git a/docs/content/docs/build-agents/meta.json b/docs/content/docs/build-agents/meta.json
index 025af1f10..2f360c65c 100644
--- a/docs/content/docs/build-agents/meta.json
+++ b/docs/content/docs/build-agents/meta.json
@@ -3,10 +3,18 @@
"root": true,
"pages": [
"index",
- "backend-setup",
- "---Chat UIs---",
+ "how-it-works",
+ "---Backend---",
+ "ui-generation",
+ "tools",
+ "conversation-history",
+ "frameworks",
+ "---Chat UI---",
+ "chat-ui",
"assistant-ui",
"copilotkit",
- "custom-chat-ui"
+ "custom-chat-ui",
+ "---Production---",
+ "[Production overview](/docs/production)"
]
}
diff --git a/docs/content/docs/build-agents/tools.mdx b/docs/content/docs/build-agents/tools.mdx
new file mode 100644
index 000000000..15a611606
--- /dev/null
+++ b/docs/content/docs/build-agents/tools.mdx
@@ -0,0 +1,67 @@
+---
+title: "Tools: agent-side vs. UI-side"
+description: Fetch data in the agent before it responds, or let the generated UI fetch it live.
+---
+
+With OpenUI, a tool can run in one of two places: in the agent, before it writes the response, or in the generated interface, after it renders. Your existing agent tools keep working unchanged. UI-side tools are an optional addition.
+
+## Which to use
+
+Ask one question: does the user need the data to change without asking the agent again?
+
+- **Agent-side**, when a snapshot is enough. The agent fetches the data, answers with an interface, and the user asks a follow-up for anything new. Good for answers, summaries, and one-off lookups.
+- **UI-side**, when the user should filter, refresh, or edit the data in place. The interface calls the tool itself, so each change is a function call instead of a new model turn. Good for dashboards, filterable tables, and forms that create or update records.
+
+Most agents start with agent-side tools and add UI-side tools for the interfaces users keep working in.
+
+## Agent-side tools
+
+The model calls the tool during its turn, your backend runs it, and the result returns to the model. The model then writes its OpenUI Lang response with the data filled in:
+
+```text title="Tool call and result"
+get_weather({ city: "Tokyo" }) → { tempC: 22, sky: "Clear" }
+```
+
+```text title="OpenUI Lang response"
+root = Card([CardHeader("Tokyo", "Clear"), TextContent("22°C", "large-heavy")])
+```
+
+The values are written into the response, so the card shows the weather at the time of the answer.
+
+Agent-side tools need nothing OpenUI-specific: the agent framework declares and runs them as it already does, and the implementations and provider keys stay on the server. The [agent framework guides](/docs/build-agents/frameworks/vercel-ai-sdk) show this for each framework.
+
+## UI-side tools
+
+The model doesn't fetch the data. It writes OpenUI Lang that calls the tool from the interface: `Query()` to read and `Mutation()` to write. The renderer runs those calls in the browser and feeds the results into components.
+
+```text
+tickets = Query("list_tickets", {}, {rows: []})
+tbl = Table([Col("Title", tickets.rows.title), Col("Priority", tickets.rows.priority)])
+root = Stack([CardHeader("Open tickets"), tbl])
+```
+
+`Query` takes the tool name, its arguments, and a default value. The table renders immediately with the default (`{rows: []}`) and fills in when `list_tickets` responds.
+
+To filter or write data, the model binds the query to a `$variable` and adds a `Mutation` that a button runs:
+
+```text
+$priority = "high"
+$title = ""
+tickets = Query("list_tickets", {priority: $priority}, {rows: []})
+createTicket = Mutation("create_ticket", {title: $title, priority: $priority})
+filter = Select("priority", $priority, [SelectItem("high", "High"), SelectItem("low", "Low")])
+addBtn = Button("Add", Action([@Run(createTicket), @Run(tickets), @Reset($title)]))
+form = Form("create", addBtn, [FormControl("Title", Input("title", $title))])
+tbl = Table([Col("Title", tickets.rows.title), Col("Priority", tickets.rows.priority)])
+root = Stack([CardHeader("Tickets"), filter, form, tbl])
+```
+
+Changing the filter re-runs `list_tickets` with the new priority. Clicking **Add** runs `create_ticket`, re-fetches the list, and clears the title. None of this involves the model. See [Queries & Mutations](/docs/openui-lang/queries-mutations) for auto-refresh, error states, and the rest of the language.
+
+UI-side tools live in two places. The system prompt describes each tool's name, input, and output, so the model can write the calls. The renderer's `toolProvider` implements them and runs them in the browser. See [System Prompts](/docs/openui-lang/system-prompts#2-generatesystemprompt-recommended-backend-integration) and [Queries & Mutations](/docs/openui-lang/queries-mutations#how-tools-connect-to-the-runtime) for setup.
+
+Treat their arguments as untrusted. The model chooses them, and the calls come from the browser, so validate them in your API routes like any client request.
+
+## Using both
+
+The two kinds combine well. Ask "How is the Acme account doing?" and the agent calls an agent-side `find_account` tool to work out which account the user means. It then responds with a dashboard whose `Query("account_metrics", {id: "acc_123"}, ...)` loads that account's live data, so the user can change the date range or refresh the numbers without another turn.
diff --git a/docs/content/docs/build-agents/ui-generation.mdx b/docs/content/docs/build-agents/ui-generation.mdx
new file mode 100644
index 000000000..c24f3b6fd
--- /dev/null
+++ b/docs/content/docs/build-agents/ui-generation.mdx
@@ -0,0 +1,160 @@
+---
+title: Set up UI generation
+description: Configure an agent backend to respond with OpenUI Lang built from your components.
+---
+
+Keep the existing agent framework, tools, and streaming transport. To make the agent respond with generated UI, give it a component library to build from and the instructions for writing OpenUI Lang with that library.
+
+If you followed [Getting Started](/docs/getting-started), steps 2 to 4 will look familiar. This page covers the same setup from the point of view of an agent backend.
+
+## 1. Install the packages
+
+```bash tab="pnpm" tab-group="pkg"
+pnpm add @openuidev/react-lang @openuidev/react-ui @openuidev/lang-core
+```
+
+```bash tab="bun" tab-group="pkg"
+bun add @openuidev/react-lang @openuidev/react-ui @openuidev/lang-core
+```
+
+```bash tab="yarn" tab-group="pkg"
+yarn add @openuidev/react-lang @openuidev/react-ui @openuidev/lang-core
+```
+
+```bash tab="npm" tab-group="pkg"
+npm install @openuidev/react-lang @openuidev/react-ui @openuidev/lang-core
+```
+
+`@openuidev/react-lang` renders OpenUI Lang, `@openuidev/react-ui` provides the built-in component library, and `@openuidev/lang-core` generates the system prompt on the server. If the agent uses only your own components, you can leave out `@openuidev/react-ui`.
+
+## 2. Define a component library
+
+The component library is the set of components the agent can use. Create one for the application's design system, or start with OpenUI's built-in library:
+
+```tsx title="src/lib/openui.tsx" tab="Custom" tab-group="component-library"
+import { createLibrary } from "@openuidev/react-lang";
+import { Chart, Metric, Stack } from "./components";
+
+export const library = createLibrary({
+ root: "Stack",
+ components: [Stack, Metric, Chart],
+});
+```
+
+```tsx title="src/lib/openui.tsx" tab="Built-in" tab-group="component-library"
+export {
+ openuiLibrary as library,
+ openuiPromptOptions as promptOptions,
+} from "@openuidev/react-ui";
+```
+
+The chat UI imports `library` from this file to render responses, so the agent and the renderer always share the same components. See [Defining Components](/docs/openui-lang/defining-components) to build a custom library.
+
+## 3. Export the library specification
+
+The backend doesn't need the React components, only a description of them. Use the OpenUI CLI to serialize the library:
+
+```bash
+npx @openuidev/cli@latest generate src/lib/openui.tsx --spec --out src/lib/openui.spec.json
+```
+
+The specification lists each component and its props. Regenerate it whenever the library changes, for example in a `prebuild` script.
+
+## 4. Generate the system prompt
+
+`generateSystemPrompt` turns the specification into the instructions the agent needs to write OpenUI Lang. It produces one of two forms, depending on where the model request goes:
+
+```ts title="server.ts" tab="OpenUI Gateway (recommended)" tab-group="call-model"
+import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";
+import library from "./lib/openui.spec.json";
+
+// A compact configuration block. Gateway expands it into the full prompt.
+const openuiInstructions = generateSystemPrompt({
+ cloud: true,
+ library: library as LibrarySpec,
+});
+```
+
+```ts title="server.ts" tab="Your own provider" tab-group="call-model"
+import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";
+import library from "./lib/openui.spec.json";
+
+// The complete prompt, ready to send to any model.
+const openuiInstructions = generateSystemPrompt({
+ library: library as LibrarySpec,
+});
+```
+
+With `cloud: true`, Gateway assembles the prompt on its side and keeps it up to date with the language. Without it, the full prompt is generated locally and works with any provider.
+
+Pass `openuiInstructions` through the agent framework's system-instruction option. If the agent already has a system prompt, append the OpenUI instructions after it.
+
+## 5. Call the model
+
+Route model requests through Gateway to correct invalid OpenUI Lang as it streams and fall back to another provider when one is unavailable. To keep your own provider, repair the output with [Autofix](/docs/autofix) instead.
+
+```ts title="server.ts" tab="OpenUI Gateway (recommended)" tab-group="call-model"
+import OpenAI from "openai";
+
+const gateway = new OpenAI({
+ apiKey: process.env.THESYS_API_KEY,
+ baseURL: "https://api.thesys.dev/v1/embed",
+});
+
+const completion = await gateway.chat.completions.create({
+ model: "openai/gpt-5",
+ messages: [{ role: "system", content: openuiInstructions }, ...messages],
+ stream: true,
+});
+```
+
+```ts title="server.ts" tab="Your own provider" tab-group="call-model"
+import OpenAI from "openai";
+import { createAutofix } from "@openuidev/server/openai";
+
+const model = new OpenAI();
+const autofix = createAutofix({ apiKey: process.env.THESYS_API_KEY!, library });
+
+const source = await model.chat.completions.create({
+ model: "gpt-5",
+ messages: [{ role: "system", content: openuiInstructions }, ...messages],
+ stream: true,
+});
+
+// Autofix adds the library itself, so pass only the conversation.
+const response = autofix.completions.stream({ stream: source, messages }).toResponse();
+```
+
+Both options use a `THESYS_API_KEY`. Create one and write it to `.env` with:
+
+```bash
+npx @openuidev/cli@latest generate-api-key
+```
+
+Gateway is OpenAI-compatible, so agent frameworks that accept an OpenAI client or base URL can use it without other changes. See the [Gateway documentation](/docs/gateway) for supported models and APIs.
+
+## 6. Stream the response to the chat UI
+
+The agent's response is now OpenUI Lang text instead of Markdown. If the agent framework already streams text to its chat UI, keep that transport: nothing about it changes.
+
+When writing the route by hand, stream the text deltas:
+
+```ts title="app/api/chat/route.ts"
+const encoder = new TextEncoder();
+
+const body = new ReadableStream({
+ async start(controller) {
+ for await (const chunk of completion) {
+ const text = chunk.choices[0]?.delta?.content;
+ if (text) controller.enqueue(encoder.encode(text));
+ }
+ controller.close();
+ },
+});
+
+return new Response(body, {
+ headers: { "Content-Type": "text/plain; charset=utf-8" },
+});
+```
+
+The chat UI accumulates the text and passes it to the renderer, which draws each component as its line arrives.
diff --git a/docs/content/docs/cookbooks/booking-assistant.mdx b/docs/content/docs/cookbooks/booking-assistant.mdx
index 1fa81d3eb..cb6d74c64 100644
--- a/docs/content/docs/cookbooks/booking-assistant.mdx
+++ b/docs/content/docs/cookbooks/booking-assistant.mdx
@@ -284,7 +284,7 @@ To use another MCP server, keep the `search_stays` contract and replace `searchA
The form pattern carries over to anything that needs a few details before an action: a restaurant reservation, a support ticket, a travel request. Describe the details, their controls, and which are required, and keep the action behind a summary. Before relying on a third-party MCP server in production, check its terms and plan for it being slow or unavailable.
-This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
+This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/build-agents/frameworks/langgraph), [Vercel AI SDK](/docs/build-agents/frameworks/vercel-ai-sdk), and [Vercel Eve](/docs/build-agents/frameworks/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
This example runs locally without authentication. Before deploying it, add [authentication](/docs/gateway/authentication), limits on request size, and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/booking-assistant) for the implementation notes.
diff --git a/docs/content/docs/cookbooks/conversational-analytics.mdx b/docs/content/docs/cookbooks/conversational-analytics.mdx
index 1ce9b4d4a..ad362b455 100644
--- a/docs/content/docs/cookbooks/conversational-analytics.mdx
+++ b/docs/content/docs/cookbooks/conversational-analytics.mdx
@@ -248,7 +248,7 @@ Generated layouts can vary. Check values against the race data in `data/f1.sqlit
Replace `queryLapTimes` with a query to your database or API. Update the tool's arguments and description, then add any components your answers need to `src/library.ts` and regenerate the specification.
-This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
+This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/build-agents/frameworks/langgraph), [Vercel AI SDK](/docs/build-agents/frameworks/vercel-ai-sdk), and [Vercel Eve](/docs/build-agents/frameworks/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
This example runs locally without authentication. Before deploying it, add [authentication](/docs/gateway/authentication), limits on request size, and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/conversational-analytics) for the implementation notes.
@@ -262,6 +262,6 @@ This example runs locally without authentication. Before deploying it, add [auth
- [OpenAI SDK](https://github.com/openai/openai-node): `runTools()` and `toReadableStream()`.
- [Gateway Chat Completions API](/docs/gateway/api/chat-completions).
- [Agent Interface quickstart](/docs/agent/getting-started/quickstart).
-- [Agent tools](/docs/agent/core-concepts/tools).
+- [Agent tools](/docs/build-agents/tools).
Data source: [OpenF1](https://openf1.org/docs/), race session `9507`. OpenF1 is an independent project, unaffiliated with Formula 1.
diff --git a/docs/content/docs/cookbooks/document-comparison.mdx b/docs/content/docs/cookbooks/document-comparison.mdx
index a8fb6254b..3e64f050e 100644
--- a/docs/content/docs/cookbooks/document-comparison.mdx
+++ b/docs/content/docs/cookbooks/document-comparison.mdx
@@ -334,7 +334,7 @@ Add your own PDFs to the example's `documents/` folder and run `npm run prepare:
The importer reads a PDF's text layer, so run OCR on scanned documents first. For large collections, store the embeddings in a vector database and keep the `search_documents` tool's contract.
-This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
+This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/build-agents/frameworks/langgraph), [Vercel AI SDK](/docs/build-agents/frameworks/vercel-ai-sdk), and [Vercel Eve](/docs/build-agents/frameworks/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
This example runs locally without authentication. Before deploying it, add [authentication](/docs/gateway/authentication), limits on request size, and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/document-comparison) for the implementation notes.
@@ -349,7 +349,7 @@ This example runs locally without authentication. Before deploying it, add [auth
- [`unpdf`](https://github.com/unjs/unpdf): PDF text extraction.
- [Gateway Chat Completions API](/docs/gateway/api/chat-completions).
- [Agent Interface quickstart](/docs/agent/getting-started/quickstart).
-- [Agent tools](/docs/agent/core-concepts/tools).
+- [Agent tools](/docs/build-agents/tools).
- [Connect a backend](/docs/agent/reference/self-hosting).
Documents: the Form 10-K annual reports of NVIDIA, AMD, and Intel, downloaded from each company's investor relations site during setup. They are not included in this repository.
diff --git a/docs/content/docs/openui-lang/quickstart.mdx b/docs/content/docs/openui-lang/quickstart.mdx
index 9954c8b21..37685b0c2 100644
--- a/docs/content/docs/openui-lang/quickstart.mdx
+++ b/docs/content/docs/openui-lang/quickstart.mdx
@@ -319,8 +319,8 @@ Remove the unused `chatLibrary` import, then update the `componentLibrary` prop:
<Callout type="info">
`recipeLibrary` extends the standard `openuiLibrary` from `@openuidev/react-ui`, using `Stack` as
its root. The standard components are available alongside `RecipeRemix`. Gateway's search tools
- and artifact renderers also remain available. See [Using the Standard
- Library](/docs/openui-lang/standard-library).
+ and artifact renderers also remain available. See the [built-in component
+ libraries](/docs/api-reference/react-ui#component-library-exports).
</Callout>
## 5. Try it
@@ -331,6 +331,6 @@ recipe cards. Click **Remix this** to start a follow-up turn.
## Next steps
-- [Add more tools](/docs/agent/core-concepts/tools)
+- [Add more tools](/docs/build-agents/tools)
- [Define more components](/docs/openui-lang/defining-components)
- [Add component interactions](/docs/openui-lang/interactivity)
diff --git a/docs/lib/docs-navigation.test.ts b/docs/lib/docs-navigation.test.ts
index 71eb930ac..6f6b56a69 100644
--- a/docs/lib/docs-navigation.test.ts
+++ b/docs/lib/docs-navigation.test.ts
@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
import { describe, it } from "node:test";
import {
GLOBAL_DOCS_TREE,
+ NESTED_DOCS_SECTIONS,
getDefaultSidebarMode,
getGlobalActiveItemUrl,
getNestedDocsTree,
@@ -67,7 +68,10 @@ describe("global docs navigation", () => {
it("treats nested roots as navigation sections rather than products", () => {
assert.equal(getNestedRootForEntryUrl("/docs/openui-lang"), "openui-lang");
assert.equal(getNestedRootForEntryUrl("/docs/build-agents"), "build-agents");
- assert.equal(getNestedRootForEntryUrl("/docs/agent/getting-started/introduction"), undefined);
+ assert.equal(
+ getNestedRootForEntryUrl("/docs/agent/getting-started/introduction"),
+ "agent-interface",
+ );
assert.equal(getNestedRootForEntryUrl("/docs/gateway"), "gateway");
assert.equal(getNestedRootForEntryUrl("/docs/autofix"), undefined);
assert.equal(getNestedRootForEntryUrl("/docs/production"), undefined);
@@ -87,15 +91,15 @@ describe("global docs navigation", () => {
kind: "nested",
root: "openui-lang",
});
- assert.deepEqual(getDefaultSidebarMode("/docs/agent/core-concepts/tools"), {
+ assert.deepEqual(getDefaultSidebarMode("/docs/agent/core-concepts/artifacts"), {
kind: "nested",
- root: "build-agents",
+ root: "agent-interface",
});
assert.deepEqual(getDefaultSidebarMode("/docs/build-agents/assistant-ui"), {
kind: "nested",
root: "build-agents",
});
- assert.deepEqual(getDefaultSidebarMode("/docs/agent/agent-runtimes/vercel-ai-sdk"), {
+ assert.deepEqual(getDefaultSidebarMode("/docs/build-agents/frameworks/vercel-ai-sdk"), {
kind: "nested",
root: "build-agents",
});
@@ -150,7 +154,10 @@ describe("global docs navigation", () => {
);
assert.equal(getGlobalActiveItemUrl("/docs/openui-lang/quickstart"), "/docs/openui-lang");
assert.equal(getGlobalActiveItemUrl("/docs/openui-lang/renderer"), "/docs/openui-lang");
- assert.equal(getGlobalActiveItemUrl("/docs/agent/core-concepts/tools"), "/docs/build-agents");
+ assert.equal(
+ getGlobalActiveItemUrl("/docs/agent/core-concepts/artifacts"),
+ "/docs/build-agents",
+ );
assert.equal(getGlobalActiveItemUrl("/docs/build-agents/copilotkit"), "/docs/build-agents");
assert.equal(getGlobalActiveItemUrl("/docs/gateway/api/responses"), "/docs/gateway");
assert.equal(getGlobalActiveItemUrl("/docs/reliability/dashboard"), "/docs/reliability");
@@ -209,8 +216,26 @@ describe("nested docs navigation", () => {
$ref: { folder: "build-agents" },
children: [
{ type: "page", name: "Overview", url: "/docs/build-agents" },
- { type: "page", name: "Backend Setup", url: "/docs/build-agents/backend-setup" },
- { type: "separator", name: "Chat UIs" },
+ { type: "separator", name: "Backend" },
+ {
+ type: "page",
+ name: "Set up UI generation",
+ url: "/docs/build-agents/ui-generation",
+ },
+ {
+ type: "folder",
+ name: "Agent frameworks",
+ defaultOpen: false,
+ children: [
+ {
+ type: "page",
+ name: "Vercel AI SDK",
+ url: "/docs/build-agents/frameworks/vercel-ai-sdk",
+ },
+ ],
+ },
+ { type: "separator", name: "Chat UI" },
+ { type: "page", name: "Choose a chat UI", url: "/docs/build-agents/chat-ui" },
{ type: "page", name: "assistant-ui", url: "/docs/build-agents/assistant-ui" },
],
},
@@ -231,8 +256,6 @@ describe("nested docs navigation", () => {
{ type: "page", name: "Custom artifacts", url: "/docs/agent/guides/custom-artifacts" },
{ type: "separator", name: "Reference" },
{ type: "page", name: "Props", url: "/docs/agent/reference/agentinterface-props" },
- { type: "separator", name: "Examples" },
- { type: "page", name: "Vercel AI SDK", url: "/docs/agent/agent-runtimes/vercel-ai-sdk" },
],
},
],
@@ -301,60 +324,62 @@ describe("nested docs navigation", () => {
});
});
- it("combines Agent Interface and existing chat integrations under Build Agents", () => {
+ it("links to Agent Interface after the Build Agents chat UI comparison page", () => {
assert.deepEqual(getNestedDocsTree(fullTree, "build-agents"), {
type: "root",
$id: "docs:nested:build-agents",
name: "Build Agents",
children: [
{ type: "page", name: "Overview", url: "/docs/build-agents" },
- { type: "page", name: "Backend Setup", url: "/docs/build-agents/backend-setup" },
+ { type: "separator", name: "Backend" },
+ {
+ type: "page",
+ name: "Set up UI generation",
+ url: "/docs/build-agents/ui-generation",
+ },
{
type: "folder",
- name: "Agent Interface",
- defaultOpen: true,
+ name: "Agent frameworks",
+ defaultOpen: false,
children: [
{
type: "page",
- name: "Introduction",
- url: "/docs/agent/getting-started/introduction",
- },
- { type: "separator", name: "Core Concepts" },
- { type: "page", name: "Artifacts", url: "/docs/agent/core-concepts/artifacts" },
- { type: "separator", name: "Guides" },
- {
- type: "page",
- name: "Custom artifacts",
- url: "/docs/agent/guides/custom-artifacts",
- },
- { type: "separator", name: "Reference" },
- {
- type: "page",
- name: "Props",
- url: "/docs/agent/reference/agentinterface-props",
+ name: "Vercel AI SDK",
+ url: "/docs/build-agents/frameworks/vercel-ai-sdk",
},
],
},
+ { type: "separator", name: "Chat UI" },
+ { type: "page", name: "Choose a chat UI", url: "/docs/build-agents/chat-ui" },
{
- type: "folder",
- name: "Existing Chat UIs",
- defaultOpen: true,
- children: [
- { type: "page", name: "assistant-ui", url: "/docs/build-agents/assistant-ui" },
- ],
+ type: "page",
+ name: "Agent Interface",
+ url: "/docs/agent/getting-started/introduction",
},
+ { type: "page", name: "assistant-ui", url: "/docs/build-agents/assistant-ui" },
+ ],
+ });
+ });
+
+ it("gives Agent Interface its own sidebar, entered from Build Agents", () => {
+ assert.equal(NESTED_DOCS_SECTIONS["agent-interface"].parent, "build-agents");
+ assert.deepEqual(getNestedDocsTree(fullTree, "agent-interface"), {
+ type: "root",
+ $id: "docs:nested:agent-interface",
+ name: "Agent Interface",
+ children: [
+ { type: "separator", name: "Getting Started" },
{
- type: "folder",
- name: "Agent Runtime Examples",
- defaultOpen: true,
- children: [
- {
- type: "page",
- name: "Vercel AI SDK",
- url: "/docs/agent/agent-runtimes/vercel-ai-sdk",
- },
- ],
+ type: "page",
+ name: "Introduction",
+ url: "/docs/agent/getting-started/introduction",
},
+ { type: "separator", name: "Core Concepts" },
+ { type: "page", name: "Artifacts", url: "/docs/agent/core-concepts/artifacts" },
+ { type: "separator", name: "Guides" },
+ { type: "page", name: "Custom artifacts", url: "/docs/agent/guides/custom-artifacts" },
+ { type: "separator", name: "Reference" },
+ { type: "page", name: "Props", url: "/docs/agent/reference/agentinterface-props" },
],
});
});
@@ -362,7 +387,7 @@ describe("nested docs navigation", () => {
it("maps any page within a nested section to its root", () => {
assert.equal(getNestedRootForPathname("/docs/openui-lang/renderer"), "openui-lang");
assert.equal(getNestedRootForPathname("/docs/api-reference"), undefined);
- assert.equal(getNestedRootForPathname("/docs/agent/customize/sidebar"), "build-agents");
+ assert.equal(getNestedRootForPathname("/docs/agent/customize/sidebar"), "agent-interface");
assert.equal(getNestedRootForPathname("/docs/build-agents/custom-chat-ui"), "build-agents");
assert.equal(getNestedRootForPathname("/docs"), undefined);
});
diff --git a/docs/lib/docs-navigation.ts b/docs/lib/docs-navigation.ts
index 257127d44..399ef3370 100644
--- a/docs/lib/docs-navigation.ts
+++ b/docs/lib/docs-navigation.ts
@@ -2,7 +2,8 @@ import type * as PageTree from "fumadocs-core/page-tree";
export type TabFolder = "cookbooks" | "examples" | "demos" | "api-reference";
-export type NestedDocsRoot = "openui-lang" | "build-agents" | "gateway" | "reliability";
+export type NestedDocsRoot =
+ "openui-lang" | "build-agents" | "agent-interface" | "gateway" | "reliability";
export type SidebarMode =
| { kind: "global" }
@@ -22,6 +23,8 @@ type NestedSection = {
entryUrl: string;
pathPrefix: string;
treeFolder: string;
+ /** The section this one is entered from. Its sidebar's back link returns there instead of to all docs. */
+ parent?: NestedDocsRoot;
};
export const NESTED_DOCS_SECTIONS: Record<NestedDocsRoot, NestedSection> = {
@@ -37,6 +40,13 @@ export const NESTED_DOCS_SECTIONS: Record<NestedDocsRoot, NestedSection> = {
pathPrefix: "/docs/build-agents",
treeFolder: "build-agents",
},
+ "agent-interface": {
+ title: "Agent Interface",
+ entryUrl: "/docs/agent/getting-started/introduction",
+ pathPrefix: "/docs/agent",
+ treeFolder: "agent",
+ parent: "build-agents",
+ },
gateway: {
title: "Gateway",
entryUrl: "/docs/gateway",
@@ -119,8 +129,6 @@ export function getNestedRootForEntryUrl(url: string): NestedDocsRoot | undefine
}
export function getNestedRootForPathname(pathname: string): NestedDocsRoot | undefined {
- if (isPathWithin(pathname, "/docs/agent")) return "build-agents";
-
return (Object.entries(NESTED_DOCS_SECTIONS) as [NestedDocsRoot, NestedSection][])
.sort(([, a], [, b]) => b.pathPrefix.length - a.pathPrefix.length)
.find(([, section]) => isPathWithin(pathname, section.pathPrefix))?.[0];
@@ -150,7 +158,9 @@ export function getSidebarModeForPathname(
export function getGlobalActiveItemUrl(pathname: string): string | undefined {
if (promotedGlobalUrls.has(pathname)) return pathname;
- const root = getNestedRootForPathname(pathname);
+ let root = getNestedRootForPathname(pathname);
+ // A section entered from another one highlights its parent in the global sidebar.
+ while (root && NESTED_DOCS_SECTIONS[root].parent) root = NESTED_DOCS_SECTIONS[root].parent;
return root ? NESTED_DOCS_SECTIONS[root].entryUrl : undefined;
}
@@ -184,43 +194,26 @@ export function getNestedDocsTree(tree: PageTree.Root, root: NestedDocsRoot): Pa
if (!folder) throw new Error(`Nested docs root "${root}" was not found in the page tree.`);
if (root === "build-agents") {
- const agentFolder = findNestedFolder(tree.children, "agent");
- if (!agentFolder) throw new Error('Nested docs folder "agent" was not found in the page tree.');
-
- const chatUIsIndex = folder.children.findIndex(
- (node) => node.type === "separator" && node.name === "Chat UIs",
- );
- const examplesIndex = agentFolder.children.findIndex(
- (node) => node.type === "separator" && node.name === "Examples",
+ const chatUIIndex = folder.children.findIndex(
+ (node) => node.type === "separator" && node.name === "Chat UI",
);
- if (chatUIsIndex < 0 || examplesIndex < 0) {
- throw new Error("Build Agents navigation groups were not found in the page tree.");
+ if (chatUIIndex < 0 || folder.children[chatUIIndex + 1]?.type !== "page") {
+ throw new Error('Build Agents "Chat UI" group was not found in the page tree.');
}
+ // The Chat UI group opens with its "Choose a chat UI" page.
+ const insertIndex = chatUIIndex + 2;
+ const agentInterface = NESTED_DOCS_SECTIONS["agent-interface"];
+ // Agent Interface is the first chat UI option, right after the page that compares them.
+ // It has its own sidebar, so it appears here as an entry into that section.
return {
type: "root",
$id: "docs:nested:build-agents",
name: "Build Agents",
children: [
- ...folder.children.slice(0, chatUIsIndex),
- {
- type: "folder",
- name: "Agent Interface",
- defaultOpen: true,
- children: agentFolder.children.slice(1, examplesIndex),
- },
- {
- type: "folder",
- name: "Existing Chat UIs",
- defaultOpen: true,
- children: folder.children.slice(chatUIsIndex + 1),
- },
- {
- type: "folder",
- name: "Agent Runtime Examples",
- defaultOpen: true,
- children: agentFolder.children.slice(examplesIndex + 1),
- },
+ ...folder.children.slice(0, insertIndex),
+ { type: "page", name: agentInterface.title, url: agentInterface.entryUrl },
+ ...folder.children.slice(insertIndex),
],
};
}
diff --git a/docs/lib/examples-catalog.ts b/docs/lib/examples-catalog.ts
index a497dd1bd..30ae3a6c9 100644
--- a/docs/lib/examples-catalog.ts
+++ b/docs/lib/examples-catalog.ts
@@ -10,12 +10,12 @@ export const EXAMPLES_REPO_URL = "https://github.com/thesysdev/openui/tree/main/
/** Docs pages that walk through an example, keyed by its path in `examples/`. */
const EXAMPLE_GUIDES: Record<string, string> = {
- "agent-frameworks/langgraph-platform": "/docs/agent/agent-runtimes/langgraph-platform",
- "agent-frameworks/vercel-ai-sdk": "/docs/agent/agent-runtimes/vercel-ai-sdk",
- "agent-frameworks/vercel-eve": "/docs/agent/agent-runtimes/vercel-eve",
+ "agent-frameworks/langgraph-platform": "/docs/build-agents/frameworks/langgraph",
+ "agent-frameworks/vercel-ai-sdk": "/docs/build-agents/frameworks/vercel-ai-sdk",
+ "agent-frameworks/vercel-eve": "/docs/build-agents/frameworks/vercel-eve",
"app-frameworks/angular": "/docs/api-reference/angular-lang",
"design-systems/shadcn": "/docs/openui-lang/examples/design-systems/shadcn",
- "harnesses/pi": "/docs/agent/agent-runtimes/pi",
+ "harnesses/pi": "/docs/build-agents/frameworks/pi",
"miscellaneous/html-artifact": "/docs/agent/guides/open-ended-html",
"miscellaneous/react-email": "/docs/openui-lang/examples/miscellaneous/react-email",
};
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index 47d9b6f4b..15851e065 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -128,17 +128,38 @@ const config = {
},
{
source: "/docs/agent/vercel-ai-sdk",
- destination: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ destination: "/docs/build-agents/frameworks/vercel-ai-sdk",
permanent: true,
},
{
source: "/docs/agent/langchain",
- destination: "/docs/agent/agent-runtimes/langgraph-platform",
+ destination: "/docs/build-agents/frameworks/langgraph",
permanent: true,
},
{
source: "/docs/agent/harnesses/:path*",
- destination: "/docs/agent/agent-runtimes/:path*",
+ destination: "/docs/build-agents/frameworks/:path*",
+ permanent: true,
+ },
+ // Agent framework guides moved out of Agent Interface into Build Agents.
+ {
+ source: "/docs/agent/agent-runtimes/langgraph-platform",
+ destination: "/docs/build-agents/frameworks/langgraph",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent/agent-runtimes/:path*",
+ destination: "/docs/build-agents/frameworks/:path*",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent/core-concepts/tools",
+ destination: "/docs/build-agents/tools",
+ permanent: true,
+ },
+ {
+ source: "/docs/build-agents/backend-setup",
+ destination: "/docs/build-agents/ui-generation",
permanent: true,
},
{
@@ -158,42 +179,42 @@ const config = {
},
{
source: "/docs/integrations/vercel-ai-sdk",
- destination: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ destination: "/docs/build-agents/frameworks/vercel-ai-sdk",
permanent: true,
},
{
source: "/docs/integrations/langchain",
- destination: "/docs/agent/agent-runtimes/langgraph-platform",
+ destination: "/docs/build-agents/frameworks/langgraph",
permanent: true,
},
{
source: "/docs/integrations/harnesses/:path*",
- destination: "/docs/agent/agent-runtimes/:path*",
+ destination: "/docs/build-agents/frameworks/:path*",
permanent: true,
},
{
source: "/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk",
- destination: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ destination: "/docs/build-agents/frameworks/vercel-ai-sdk",
permanent: true,
},
{
source: "/docs/openui-lang/examples/agent-frameworks/langchain",
- destination: "/docs/agent/agent-runtimes/langgraph-platform",
+ destination: "/docs/build-agents/frameworks/langgraph",
permanent: true,
},
{
source: "/docs/openui-lang/examples/agent-frameworks/langgraph-platform",
- destination: "/docs/agent/agent-runtimes/langgraph-platform",
+ destination: "/docs/build-agents/frameworks/langgraph",
permanent: true,
},
{
source: "/docs/openui-lang/examples/agent-frameworks/vercel-eve",
- destination: "/docs/agent/agent-runtimes/vercel-eve",
+ destination: "/docs/build-agents/frameworks/vercel-eve",
permanent: true,
},
{
source: "/docs/openui-lang/examples/harnesses/pi",
- destination: "/docs/agent/agent-runtimes/pi",
+ destination: "/docs/build-agents/frameworks/pi",
permanent: true,
},
{
diff --git a/docs/public/images/build-agents-architecture.svg b/docs/public/images/build-agents-architecture.svg
deleted file mode 100644
index fbe383e09..000000000
--- a/docs/public/images/build-agents-architecture.svg
+++ /dev/null
@@ -1,133 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg"
- viewBox="0 0 1600 650"
- role="img"
- aria-labelledby="build-agents-architecture-title build-agents-architecture-description"
->
- <title id="build-agents-architecture-title">How an agent generates an interactive interface with OpenUI Lang</title>
- <desc id="build-agents-architecture-description">
- A user request travels from an existing chat UI to its backend and directly to a model provider. The model returns an OpenUI Lang stream, which the renderer displays as an interactive interface in the chat UI.
- </desc>
-
- <defs>
- <linearGradient id="build-agents-architecture-bg" x1="0" y1="0" x2="1" y2="1">
- <stop offset="0" stop-color="#020303" />
- <stop offset="0.55" stop-color="#080a0a" />
- <stop offset="1" stop-color="#030404" />
- </linearGradient>
- <radialGradient id="build-agents-architecture-glow" cx="0.76" cy="0.3" r="0.7">
- <stop offset="0" stop-color="#38bdf8" stop-opacity="0.08" />
- <stop offset="0.5" stop-color="#8b5cf6" stop-opacity="0.035" />
- <stop offset="1" stop-color="#000000" stop-opacity="0" />
- </radialGradient>
- <linearGradient id="build-agents-architecture-card" x1="0" y1="0" x2="1" y2="1">
- <stop offset="0" stop-color="#242626" stop-opacity="0.9" />
- <stop offset="1" stop-color="#111313" stop-opacity="0.96" />
- </linearGradient>
- <linearGradient id="build-agents-architecture-phone" x1="0" y1="0" x2="0" y2="1">
- <stop offset="0" stop-color="#171919" stop-opacity="0.74" />
- <stop offset="1" stop-color="#090a0a" stop-opacity="0.88" />
- </linearGradient>
- <filter id="build-agents-architecture-shadow" x="-30%" y="-30%" width="160%" height="160%">
- <feDropShadow dx="0" dy="10" stdDeviation="18" flood-color="#000000" flood-opacity="0.55" />
- </filter>
- <filter id="build-agents-architecture-soft-glow" x="-30%" y="-30%" width="160%" height="160%">
- <feGaussianBlur stdDeviation="10" result="blur" />
- <feMerge>
- <feMergeNode in="blur" />
- <feMergeNode in="SourceGraphic" />
- </feMerge>
- </filter>
- <filter id="build-agents-architecture-logo-light" color-interpolation-filters="sRGB">
- <feFlood flood-color="#e5e7eb" result="logo-color" />
- <feComposite in="logo-color" in2="SourceAlpha" operator="in" />
- </filter>
- <marker id="build-agents-architecture-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
- <path d="M 0 0 L 10 5 L 0 10 z" fill="#8b9292" />
- </marker>
- </defs>
-
- <rect width="1600" height="650" rx="24" fill="url(#build-agents-architecture-bg)" />
- <rect width="1600" height="650" rx="24" fill="url(#build-agents-architecture-glow)" />
-
- <g font-family="ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif">
- <g filter="url(#build-agents-architecture-shadow)">
- <rect x="35" y="42" width="365" height="565" rx="58" fill="url(#build-agents-architecture-phone)" stroke="#3f4444" stroke-width="2" vector-effect="non-scaling-stroke" />
- <rect x="48" y="55" width="339" height="539" rx="49" fill="none" stroke="#272b2b" stroke-width="1" vector-effect="non-scaling-stroke" />
- <rect x="170" y="68" width="94" height="26" rx="13" fill="#242727" />
-
- <text x="70" y="135" fill="#c8cccc" font-size="24">What did I spend last month?</text>
-
- <rect x="68" y="165" width="305" height="380" rx="26" fill="url(#build-agents-architecture-card)" stroke="#333737" stroke-width="1" vector-effect="non-scaling-stroke" />
- <text x="92" y="205" fill="#8f9696" font-size="22">Total expenses</text>
- <text x="92" y="247" fill="#f4f7f7" font-size="36" font-weight="600">$5,432</text>
-
- <rect x="94" y="275" width="253" height="240" rx="20" fill="#0d0f0f" stroke="#262929" stroke-width="1" vector-effect="non-scaling-stroke" />
- <g transform="rotate(-90 220 388)" filter="url(#build-agents-architecture-soft-glow)">
- <circle cx="220" cy="388" r="66" fill="none" stroke="#7c3aed" stroke-width="62" pathLength="100" stroke-dasharray="30 70" strokeDashoffset="0" />
- <circle cx="220" cy="388" r="66" fill="none" stroke="#06b6d4" stroke-width="62" pathLength="100" stroke-dasharray="23 77" strokeDashoffset="-30" />
- <circle cx="220" cy="388" r="66" fill="none" stroke="#3b82f6" stroke-width="62" pathLength="100" stroke-dasharray="18 82" strokeDashoffset="-53" />
- <circle cx="220" cy="388" r="66" fill="none" stroke="#a855f7" stroke-width="62" pathLength="100" stroke-dasharray="14 86" strokeDashoffset="-71" />
- <circle cx="220" cy="388" r="66" fill="none" stroke="#84cc16" stroke-width="62" pathLength="100" stroke-dasharray="15 85" strokeDashoffset="-85" />
- </g>
- <circle cx="220" cy="388" r="34" fill="#111313" />
- <text x="220" y="383" text-anchor="middle" fill="#cfd4d4" font-size="18" font-weight="600">Monthly</text>
- <text x="220" y="407" text-anchor="middle" fill="#8d9494" font-size="16">expenses</text>
- <text x="120" y="490" fill="#737b7b" font-size="17">Food</text>
- <text x="204" y="490" fill="#737b7b" font-size="17">Travel</text>
- <text x="292" y="490" fill="#737b7b" font-size="17">Rent</text>
- </g>
-
- <g stroke="#757d7d" stroke-width="1.5" fill="none" vector-effect="non-scaling-stroke">
- <path d="M 387 135 H 600" markerEnd="url(#build-agents-architecture-arrow)" />
- <path d="M 770 175 H 1260" markerEnd="url(#build-agents-architecture-arrow)" />
- <path d="M 1410 265 V 300" markerEnd="url(#build-agents-architecture-arrow)" />
- <path d="M 1200 420 H 770" markerEnd="url(#build-agents-architecture-arrow)" />
- <path d="M 685 460 V 540" markerEnd="url(#build-agents-architecture-arrow)" />
- <path d="M 540 575 H 400" markerEnd="url(#build-agents-architecture-arrow)" />
- </g>
-
- <g>
- <rect x="455" y="111" width="120" height="42" rx="21" fill="#222626" stroke="#343a3a" vector-effect="non-scaling-stroke" />
- <text x="515" y="139" text-anchor="middle" fill="#b1b7b7" font-size="20">User query</text>
- </g>
-
- <g filter="url(#build-agents-architecture-shadow)">
- <rect x="600" y="130" width="170" height="330" rx="22" fill="url(#build-agents-architecture-card)" stroke="#3a4040" stroke-width="1.5" vector-effect="non-scaling-stroke" />
- <text x="625" y="175" fill="#f1f4f4" font-size="30" font-weight="500">Backend</text>
- <text x="625" y="210" fill="#858d8d" font-size="22">Data and logic</text>
- <rect x="652" y="405" width="46" height="11" rx="5.5" fill="#7f8787" />
- <rect x="652" y="425" width="46" height="11" rx="5.5" fill="#525959" />
- </g>
-
- <g filter="url(#build-agents-architecture-shadow)">
- <rect x="1260" y="60" width="300" height="205" rx="26" fill="url(#build-agents-architecture-card)" stroke="#404545" stroke-width="1.5" vector-effect="non-scaling-stroke" />
- <rect x="1278" y="78" width="264" height="169" rx="19" fill="none" stroke="#343939" stroke-width="1" vector-effect="non-scaling-stroke" />
- <text x="1295" y="120" fill="#f1f3f3" font-size="30" font-weight="500">Model providers</text>
- <text x="1295" y="155" fill="#858c8c" font-size="20">Models across providers</text>
- <image href="/brand-icons/openai.svg" x="1292" y="188" width="36" height="36" filter="url(#build-agents-architecture-logo-light)" aria-label="OpenAI" />
- <image href="/brand-icons/anthropic.svg" x="1350" y="188" width="36" height="36" filter="url(#build-agents-architecture-logo-light)" aria-label="Anthropic" />
- <image href="/brand-icons/gemini.svg" x="1408" y="188" width="36" height="36" filter="url(#build-agents-architecture-logo-light)" aria-label="Google Gemini" />
- <image href="/brand-icons/meta.svg" x="1466" y="188" width="36" height="36" filter="url(#build-agents-architecture-logo-light)" aria-label="Meta" />
- </g>
-
- <text x="1015" y="130" text-anchor="middle" fill="#a7adad" font-size="20">Components</text>
- <text x="1015" y="156" text-anchor="middle" fill="#a7adad" font-size="20">and context</text>
-
- <g filter="url(#build-agents-architecture-shadow)">
- <rect x="1200" y="300" width="360" height="250" rx="28" fill="url(#build-agents-architecture-card)" stroke="#48404f" stroke-width="1.5" vector-effect="non-scaling-stroke" />
- <rect x="1220" y="320" width="320" height="210" rx="20" fill="none" stroke="#3c3541" stroke-width="1" vector-effect="non-scaling-stroke" />
- <text x="1245" y="365" fill="#f1eafb" font-size="32" font-weight="500">OpenUI Lang</text>
- <text x="1245" y="402" fill="#94899d" font-size="22">Compact interface format</text>
- <text x="1245" y="458" fill="#a89dae" font-size="24" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">root = Stack(...)</text>
- <text x="1245" y="496" fill="#807785" font-size="24" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">chart = PieChart(...)</text>
- </g>
-
- <text x="1015" y="365" text-anchor="middle" fill="#c1b8c8" font-size="22">OpenUI Lang stream</text>
- <text x="1015" y="393" text-anchor="middle" fill="#827a88" font-size="19">compact and stream-friendly</text>
-
- <g filter="url(#build-agents-architecture-shadow)">
- <rect x="540" y="540" width="300" height="70" rx="18" fill="url(#build-agents-architecture-card)" stroke="#3f5b5d" stroke-width="1.5" vector-effect="non-scaling-stroke" />
- <text x="690" y="584" text-anchor="middle" fill="#bcecf0" font-size="26" font-weight="500">OpenUI Lang renderer</text>
- </g>
- </g>
-</svg>
diff --git a/examples/cookbooks/booking-assistant/README.md b/examples/cookbooks/booking-assistant/README.md
index 8bc3f4eeb..67664b991 100644
--- a/examples/cookbooks/booking-assistant/README.md
+++ b/examples/cookbooks/booking-assistant/README.md
@@ -72,7 +72,7 @@ Agent Interface stores the thread list with Gateway's [Conversations API](https:
The chat route uses only the new message from the browser. `loadChatCompletionHistory()` in `src/lib/gateway-history.ts` loads the earlier turns from the thread's Gateway conversation, including their searches and results, and the response ends once the turn is stored, so the next step finds it. Each stay card's value is the stay's booking link, so choosing a card sends the link back with the form, and the summary's **Continue to booking** button opens it. A submitted form arrives as one message with the form's values.
-The route runs the tool with the OpenAI SDK's [`runTools()`](https://github.com/openai/openai-node#automated-function-calls) and returns the runner's `toReadableStream()`, one JSON chunk per line, which `openAIReadableStreamAdapter()` reads. Chat Completions has no chunk for a tool result, so in a live answer **Behind the scenes** shows each call's arguments but not its result. The tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK; see the [agent runtime integrations](https://www.openui.com/docs/agent/agent-runtimes/langgraph-platform) and the [agent framework examples](../../agent-frameworks).
+The route runs the tool with the OpenAI SDK's [`runTools()`](https://github.com/openai/openai-node#automated-function-calls) and returns the runner's `toReadableStream()`, one JSON chunk per line, which `openAIReadableStreamAdapter()` reads. Chat Completions has no chunk for a tool result, so in a live answer **Behind the scenes** shows each call's arguments but not its result. The tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK; see the [agent framework guides](https://www.openui.com/docs/build-agents/frameworks/langgraph) and the [agent framework examples](../../agent-frameworks).
The app binds to loopback, and every browser shares one local user's threads. For deployment, add [authentication](https://www.openui.com/docs/gateway/authentication), mint each frontend token for the signed-in user, check that each `threadId` belongs to that user before storing a turn in it, and add request-size and rate limits to both routes.