Skip to content

The Open Standard for Generative UI

Documentation reorganise (#1126)

abhithesys641f658cf074
diff --git a/docs/README.md b/docs/README.md
index a09742a0e..0a53ee943 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -63,7 +63,7 @@ docs/
│ │ └── components/ # Accordion, Button, StackChip, TweetWall, etc.
│ │
│ ├── docs/ # Fumadocs documentation pages
-│ │ ├── layout.tsx # DocsLayout (sidebar, nav)
+│ │ ├── layout.tsx # DocsLayout (global/nested sidebar, nav)
│ │ └── [[...slug]]/page.tsx # Catch-all rendering MDX from content/docs/
│ │
│ ├── components/ # Component / Design System pages
@@ -98,9 +98,11 @@ docs/
│
├── content/
│ ├── docs/ # MDX content (Fumadocs source)
-│ │ ├── meta.json # Root sidebar config
+│ │ ├── index.mdx # Global docs overview at /docs
+│ │ ├── meta.json # Root content order
│ │ ├── openui-lang/ # OpenUI Lang docs
│ │ ├── agent/ # Agent Interface docs
+│ │ ├── build-agents/ # Existing chat UI and agent framework guides
│ │ ├── api-reference/ # API reference
│ │ └── mcp/ # MCP docs
│ └── blog/ # Blog MDX content
@@ -155,7 +157,14 @@ Active component-preview specific modules are located under `app/components/` an
### Navigation
-A custom `DocsNavbar` component (`components/docs-navbar.tsx`) provides top-level horizontal tabs: Overview, OpenUI, Agent Interface, OpenUI Cloud, and API Reference. It replaces Fumadocs' default nav and is used across the docs pages.
+The docs use two sidebar modes. The global sidebar introduces the documentation through Start,
+Build, Production, and Reference groups. Links with chevrons enter a nested section sidebar for
+OpenUI Lang, Build Agents, Agent Interface, Gateway, Observability, or API Reference. Nested page lists continue to come from
+each section's `meta.json`; “All docs” restores the global sidebar without changing the current
+page. Direct links into a section start in nested mode.
+
+`components/docs-navbar.tsx` provides the shared docs header, search, theme control, and mobile
+sidebar trigger.
## Path aliases
diff --git a/docs/app/(home)/integrations/data.ts b/docs/app/(home)/integrations/data.ts
index 1f51abf6a..3f6b51322 100644
--- a/docs/app/(home)/integrations/data.ts
+++ b/docs/app/(home)/integrations/data.ts
@@ -86,7 +86,11 @@ const integrationCatalog: Integration[] = [
howItWorks:
"Each shadcn component is registered with defineComponent and a Zod prop schema. createLibrary produces both the prompt vocabulary and the renderer mapping used by the example chat app.",
links: [
- { label: "Integration guide", href: "/docs/openui-lang/examples/design-systems/shadcn", kind: "Guide" },
+ {
+ label: "Integration guide",
+ href: "/docs/openui-lang/examples/design-systems/shadcn",
+ kind: "Guide",
+ },
exampleLink("shadcn-chat"),
{ label: "shadcn/ui", href: "https://ui.shadcn.com", kind: "Website" },
],
@@ -163,6 +167,11 @@ const integrationCatalog: Integration[] = [
href: "/docs/agent/reference/adapters-and-formats#langgraphadapter",
kind: "Docs",
},
+ {
+ label: "Integration guide",
+ href: "/docs/agent/agent-runtimes/langgraph-platform",
+ kind: "Guide",
+ },
exampleLink("langchain-chat"),
],
},
@@ -183,6 +192,11 @@ const integrationCatalog: Integration[] = [
href: "/docs/agent/reference/adapters-and-formats#vercelaiadapter",
kind: "Docs",
},
+ {
+ label: "Integration guide",
+ href: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ kind: "Guide",
+ },
...packageLinks("@openuidev/react-headless", "react-headless"),
exampleLink("vercel-ai-chat"),
{ label: "AI SDK", href: "https://ai-sdk.dev", kind: "Website" },
@@ -296,7 +310,7 @@ const integrationCatalog: Integration[] = [
links: [
{
label: "Integration guide",
- href: "/docs/openui-lang/examples/agent-frameworks/vercel-eve",
+ href: "/docs/agent/agent-runtimes/vercel-eve",
kind: "Guide",
},
exampleLink("harnesses/vercel-eve", "OpenUI harness"),
@@ -316,7 +330,7 @@ const integrationCatalog: Integration[] = [
links: [
{
label: "Integration guide",
- href: "/docs/openui-lang/examples/harnesses/pi",
+ href: "/docs/agent/agent-runtimes/pi",
kind: "Guide",
},
exampleLink("harnesses/pi-agent-harness", "OpenUI harness"),
diff --git a/docs/app/docs/[[...slug]]/page.tsx b/docs/app/docs/[[...slug]]/page.tsx
index 200fbfaf9..d3e2d7970 100644
--- a/docs/app/docs/[[...slug]]/page.tsx
+++ b/docs/app/docs/[[...slug]]/page.tsx
@@ -16,15 +16,19 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
return (
<DocsPage toc={page.data.toc} full={page.data.full}>
- <DocsTitle>{page.data.title}</DocsTitle>
- <DocsDescription className="mb-0">{page.data.description}</DocsDescription>
- <div className="flex flex-row gap-2 items-center border-b pb-6">
- <LLMCopyButton markdownUrl={`${page.url}.mdx`} />
- <ViewOptions
- markdownUrl={page.url}
- githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/docs/content/docs/${page.path}`}
- />
- </div>
+ {!page.data.customHeader && (
+ <>
+ <DocsTitle>{page.data.title}</DocsTitle>
+ <DocsDescription className="mb-0">{page.data.description}</DocsDescription>
+ <div className="flex flex-row gap-2 items-center border-b pb-6">
+ <LLMCopyButton markdownUrl={`${page.url}.mdx`} />
+ <ViewOptions
+ markdownUrl={page.url}
+ githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/docs/content/docs/${page.path}`}
+ />
+ </div>
+ </>
+ )}
<DocsBody>
<MDX
components={getMDXComponents({
diff --git a/docs/app/global.css b/docs/app/global.css
index 9660186fa..0666fe2ea 100644
--- a/docs/app/global.css
+++ b/docs/app/global.css
@@ -32,12 +32,11 @@ body {
#nd-docs-layout {
--color-fd-background: var(--openui-foreground);
--color-doc-surface: var(--openui-foreground);
- /* 4rem top bar + 0.5rem gap above tabs + ~2.5rem tabs row — keep in sync with `.tabsBar` padding */
- --fd-banner-height: calc(4rem + 0.5rem + 2.5rem) !important;
+ --fd-banner-height: 4rem !important;
--fd-layout-width: 1560px !important;
width: 100%;
- min-height: calc(100dvh - (4rem + 0.5rem + 2.5rem)) !important;
- padding-top: calc(4rem + 0.5rem + 2.5rem) !important;
+ min-height: calc(100dvh - 4rem) !important;
+ padding-top: 4rem !important;
background: var(--openui-foreground);
}
@@ -150,12 +149,3 @@ body {
#nd-sidebar-mobile [data-radix-scroll-area-viewport] a[target="_blank"] > svg:first-child {
order: 1;
}
-
-@media (max-width: 767px) {
- #nd-docs-layout {
- --fd-banner-height: calc(4rem + 2.5rem) !important;
- min-height: calc(100dvh - (4rem + 2.5rem)) !important;
- padding-top: calc(4rem + 2.5rem) !important;
- }
-}
-
diff --git a/docs/components/docs-navbar.module.css b/docs/components/docs-navbar.module.css
index bfc5df80c..9f4313773 100644
--- a/docs/components/docs-navbar.module.css
+++ b/docs/components/docs-navbar.module.css
@@ -10,22 +10,6 @@
width: 100%;
}
-.tabsBar {
- width: 100%;
- padding-top: 0.5rem;
- background-color: color-mix(in srgb, var(--color-fd-background) 80%, transparent);
- backdrop-filter: blur(24px);
-}
-
-.tabsInner {
- width: 100%;
- max-width: calc(1560px + 2rem);
- min-height: 2.5rem;
- margin-inline: auto;
- padding-inline: 1rem;
- box-sizing: border-box;
-}
-
.sidebarToggle {
display: none;
align-items: center;
@@ -138,64 +122,6 @@
background: var(--openui-highlight);
}
-.tabsNav {
- width: 100%;
- min-height: 2.5rem;
- display: flex;
- align-items: stretch;
- gap: 1.125rem;
- border-bottom: 1px solid var(--openui-border-default);
- overflow-x: auto;
- scrollbar-width: none;
-}
-
-.tabsNav::-webkit-scrollbar {
- display: none;
-}
-
-.tabLink {
- position: relative;
- display: inline-flex;
- align-items: center;
- flex-shrink: 0;
- min-height: 2.5rem;
- padding: 0.5rem 0;
- color: var(--openui-text-neutral-secondary);
- text-decoration: none;
- white-space: nowrap;
- font-size: 1rem;
- font-weight: 400;
- line-height: 1.5rem;
-}
-
-.tabLink:hover {
- color: var(--openui-text-neutral-primary);
-}
-
-.tabLink::after {
- content: "";
- position: absolute;
- right: 0;
- bottom: -1px;
- left: 0;
- height: 1.5px;
- background: transparent;
-}
-
-.tabLinkActive {
- color: var(--openui-text-neutral-primary);
- font-weight: 600;
-}
-
-.tabLinkActive::after {
- background: var(--openui-border-interactive-selected);
-}
-
-.tabLink:focus-visible {
- outline: 2px solid var(--openui-border-accent-emphasis);
- outline-offset: 2px;
-}
-
@media (min-width: 640px) {
.searchShortcut {
display: inline-flex;
@@ -213,32 +139,4 @@
.sidebarToggle {
display: flex;
}
-
- .tabsBar {
- padding-top: 0;
- border-top: 1px solid var(--openui-border-default);
- }
-
- .tabsInner {
- min-height: 2.5rem;
- padding-inline: 0;
- }
-
- .tabsNav {
- box-sizing: border-box;
- min-height: 2.5rem;
- gap: 0.625rem;
- padding-inline: 0.5rem;
- border-bottom: 1px solid var(--openui-border-default);
- overflow-x: auto;
- overscroll-behavior-x: contain;
- -webkit-overflow-scrolling: touch;
- }
-
- .tabLink {
- min-height: 2.5rem;
- padding: 0.5rem 0;
- font-size: 0.8125rem;
- line-height: 1.5rem;
- }
}
diff --git a/docs/components/docs-navbar.tsx b/docs/components/docs-navbar.tsx
index a3600b08f..1cb493b22 100644
--- a/docs/components/docs-navbar.tsx
+++ b/docs/components/docs-navbar.tsx
@@ -5,35 +5,12 @@ import { SidebarTrigger } from "fumadocs-ui/components/sidebar/base";
import { useSearchContext } from "fumadocs-ui/contexts/search";
import { useTheme } from "next-themes";
import Link from "next/link";
-import { usePathname } from "next/navigation";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useState } from "react";
import { GitHubStarButton } from "./brand-logo";
import styles from "./docs-navbar.module.css";
import { SiteHeaderFrame } from "./site-header";
import { ThemeToggle } from "./theme-toggle";
-const tabs: { title: string; url: string; match?: string }[] = [
- { title: "Overview", url: "/docs/overview" },
- { title: "OpenUI", url: "/docs/openui-lang" },
- {
- title: "Agent Interface",
- url: "/docs/agent/getting-started/introduction",
- match: "/docs/agent",
- },
- { title: "OpenUI Cloud", url: "/docs/openui-cloud" },
- { title: "API Reference", url: "/docs/api-reference" },
-];
-
-function activeTabUrl(pathname: string): string {
- const sorted = [...tabs].sort((a, b) => (b.match ?? b.url).length - (a.match ?? a.url).length);
- return (
- sorted.find((t) => {
- const prefix = t.match ?? t.url;
- return pathname === prefix || pathname.startsWith(`${prefix}/`);
- })?.url ?? tabs[0].url
- );
-}
-
function SearchBar() {
const { setOpenSearch } = useSearchContext();
const [isMac, setIsMac] = useState(false);
@@ -87,8 +64,7 @@ function SearchBar() {
);
}
-export function DocsNavbar({ showSidebarToggle = false }: { showSidebarToggle?: boolean }) {
- const pathname = usePathname();
+export function DocsNavbar() {
const { resolvedTheme } = useTheme();
// resolvedTheme is undefined during SSR and the first client render, so gate the
// theme-derived variant behind a mount flag (matching SiteMarketingHeader) to
@@ -105,8 +81,6 @@ export function DocsNavbar({ showSidebarToggle = false }: { showSidebarToggle?:
}, []);
const logoVariant = mounted && resolvedTheme === "dark" ? "dark" : "light";
- const tabValue = useMemo(() => activeTabUrl(pathname), [pathname]);
-
return (
<header className={styles.header}>
<div className={styles.topBar}>
@@ -121,24 +95,22 @@ export function DocsNavbar({ showSidebarToggle = false }: { showSidebarToggle?:
</div>
}
leading={
- showSidebarToggle ? (
- <SidebarTrigger className={styles.sidebarToggle}>
- <svg
- width="20"
- height="20"
- viewBox="0 0 24 24"
- fill="none"
- stroke="currentColor"
- strokeWidth="2"
- strokeLinecap="round"
- strokeLinejoin="round"
- >
- <line x1="3" y1="6" x2="21" y2="6" />
- <line x1="3" y1="12" x2="21" y2="12" />
- <line x1="3" y1="18" x2="21" y2="18" />
- </svg>
- </SidebarTrigger>
- ) : null
+ <SidebarTrigger className={styles.sidebarToggle} aria-label="Browse documentation">
+ <svg
+ width="20"
+ height="20"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ >
+ <line x1="3" y1="6" x2="21" y2="6" />
+ <line x1="3" y1="12" x2="21" y2="12" />
+ <line x1="3" y1="18" x2="21" y2="18" />
+ </svg>
+ </SidebarTrigger>
}
end={
<div className={styles.actions}>
@@ -161,26 +133,6 @@ export function DocsNavbar({ showSidebarToggle = false }: { showSidebarToggle?:
}
/>
</div>
- <div className={styles.tabsBar}>
- <div className={styles.tabsInner}>
- <nav className={styles.tabsNav} aria-label="Documentation sections">
- {tabs.map((tab) => {
- const isActive = tab.url === tabValue;
-
- return (
- <Link
- key={tab.url}
- href={tab.url}
- className={`${styles.tabLink} ${isActive ? styles.tabLinkActive : ""}`.trim()}
- aria-current={isActive ? "page" : undefined}
- >
- {tab.title}
- </Link>
- );
- })}
- </nav>
- </div>
- </div>
</header>
);
}
diff --git a/docs/components/docs-route-layout.tsx b/docs/components/docs-route-layout.tsx
index 5943a18b0..fab2691dc 100644
--- a/docs/components/docs-route-layout.tsx
+++ b/docs/components/docs-route-layout.tsx
@@ -1,36 +1,79 @@
"use client";
import { DocsNavbar } from "@/components/docs-navbar";
-import { baseOptions, siteConfig } from "@/lib/layout.shared";
+import {
+ GLOBAL_DOCS_TREE,
+ NESTED_DOCS_SECTIONS,
+ getGlobalActiveItemUrl,
+ getNestedDocsTree,
+ getNestedRootForEntryUrl,
+ getSidebarModeForPathname,
+ type NestedDocsRoot,
+ type SidebarModeOverride,
+} from "@/lib/docs-navigation";
+import { baseOptions } from "@/lib/layout.shared";
+import type * as PageTree from "fumadocs-core/page-tree";
+import { SidebarItem, useSidebar } from "fumadocs-ui/components/sidebar/base";
import { DocsLayout } from "fumadocs-ui/layouts/docs";
-import { Play, Plug } from "lucide-react";
-import Link from "next/link";
+import { ChevronLeft, ChevronRight } from "lucide-react";
import { usePathname } from "next/navigation";
-import type { ReactNode } from "react";
+import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from "react";
+
+type DocsNavigationContextValue = {
+ enterNested: (root: NestedDocsRoot) => void;
+ showGlobal: () => void;
+};
+
+const DocsNavigationContext = createContext<DocsNavigationContextValue | null>(null);
+
+function useDocsNavigation() {
+ const value = useContext(DocsNavigationContext);
+ if (!value) throw new Error("Docs navigation must be rendered inside DocsRouteLayout.");
+ return value;
+}
+
+function GlobalSidebarItem({ item }: { item: PageTree.Item }) {
+ const pathname = usePathname();
+ const { enterNested } = useDocsNavigation();
+ const nestedRoot = getNestedRootForEntryUrl(item.url);
+ const active = (getGlobalActiveItemUrl(pathname) ?? pathname) === item.url;
-function SidebarBannerLink({
- href,
- label,
- icon,
- external = false,
-}: {
- href: string;
- label: string;
- icon: ReactNode;
- external?: boolean;
-}) {
return (
- <Link
- href={href}
- target={external ? "_blank" : undefined}
- rel={external ? "noopener noreferrer" : undefined}
- className="relative flex flex-row items-center gap-3 rounded-lg p-2 text-sm text-fd-foreground no-underline hover:bg-fd-accent transition-colors"
+ <SidebarItem
+ href={item.url}
+ external={item.external}
+ active={active}
+ icon={item.icon}
+ className="relative flex flex-row items-center gap-2 rounded-lg p-2 text-start text-fd-muted-foreground wrap-anywhere transition-colors hover:bg-fd-accent/50 hover:text-fd-accent-foreground data-[active=true]:bg-fd-primary/10 data-[active=true]:text-fd-primary"
+ onClick={nestedRoot ? () => enterNested(nestedRoot) : undefined}
>
- <span className="flex items-center justify-center size-8 rounded-lg bg-fd-muted text-fd-muted-foreground shrink-0 [&_svg]:size-4 [&_svg]:shrink-0">
- {icon}
- </span>
- {label}
- </Link>
+ <span className="min-w-0 flex-1">{item.name}</span>
+ {nestedRoot ? <ChevronRight aria-hidden className="ms-auto" size={18} /> : null}
+ </SidebarItem>
+ );
+}
+
+function NestedSidebarHeader({ root }: { root: NestedDocsRoot }) {
+ const { showGlobal } = useDocsNavigation();
+ const { setOpen } = useSidebar();
+
+ return (
+ <div className="flex flex-col gap-4">
+ <button
+ 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={() => {
+ showGlobal();
+ setOpen(false);
+ }}
+ >
+ <ChevronLeft aria-hidden className="size-4" />
+ All docs
+ </button>
+ <p className="px-2 text-sm font-semibold text-fd-foreground">
+ {NESTED_DOCS_SECTIONS[root].title}
+ </p>
+ </div>
);
}
@@ -41,38 +84,47 @@ type DocsRouteLayoutProps = {
export function DocsRouteLayout({ tree, children }: DocsRouteLayoutProps) {
const pathname = usePathname();
- const isOverview = pathname === "/docs/overview";
+ const [sidebarOverride, setSidebarOverride] = useState<SidebarModeOverride>();
+ const sidebarMode = getSidebarModeForPathname(pathname, sidebarOverride);
+
+ const enterNested = useCallback(
+ (root: NestedDocsRoot) => {
+ setSidebarOverride({ pathname, mode: { kind: "nested", root } });
+ },
+ [pathname],
+ );
+ const showGlobal = useCallback(() => {
+ setSidebarOverride({ pathname, mode: { kind: "global" } });
+ }, [pathname]);
+ const navigationContext = useMemo(() => ({ enterNested, showGlobal }), [enterNested, showGlobal]);
+
+ const nestedRoot = sidebarMode.kind === "nested" ? sidebarMode.root : undefined;
+ const activeTree = useMemo(
+ () => (nestedRoot ? getNestedDocsTree(tree, nestedRoot) : GLOBAL_DOCS_TREE),
+ [nestedRoot, tree],
+ );
return (
- <DocsLayout
- tree={tree}
- {...baseOptions()}
- nav={{ component: <DocsNavbar showSidebarToggle={!isOverview} /> }}
- sidebar={{
- tabs: false,
- enabled: !isOverview,
- collapsible: false,
- banner: (
- <div className="flex flex-col mb-2">
- <SidebarBannerLink href="/demos" label="Demos" external icon={<Play />} />
- <SidebarBannerLink
- href={siteConfig.discordUrl}
- label="Discord"
- external
- icon={
- <svg viewBox="0 0 24 24" fill="currentColor">
- <path d="M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057 19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028 14.09 14.09 0 0 0 1.226-1.994.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.839 19.839 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.946 2.418-2.157 2.418z" />
- </svg>
- }
- />
- <SidebarBannerLink href="/docs/mcp" label="Docs MCP" icon={<Plug />} />
- </div>
- ),
- }}
- searchToggle={{ enabled: false }}
- themeSwitch={{ enabled: false }}
- >
- {children}
- </DocsLayout>
+ <DocsNavigationContext.Provider value={navigationContext}>
+ <DocsLayout
+ tree={activeTree}
+ {...baseOptions()}
+ nav={{ component: <DocsNavbar /> }}
+ sidebar={{
+ tabs: false,
+ collapsible: false,
+ className:
+ nestedRoot === "build-agents"
+ ? "[&_button[aria-expanded]]:!text-fd-foreground [&_button[aria-expanded]+div]:mb-4"
+ : undefined,
+ banner: nestedRoot ? <NestedSidebarHeader root={nestedRoot} /> : undefined,
+ components: sidebarMode.kind === "global" ? { Item: GlobalSidebarItem } : undefined,
+ }}
+ searchToggle={{ enabled: false }}
+ themeSwitch={{ enabled: false }}
+ >
+ {children}
+ </DocsLayout>
+ </DocsNavigationContext.Provider>
);
}
diff --git a/docs/components/openui-architecture-overview.module.css b/docs/components/openui-architecture-overview.module.css
deleted file mode 100644
index 6d2dcf5ab..000000000
--- a/docs/components/openui-architecture-overview.module.css
+++ /dev/null
@@ -1,322 +0,0 @@
-.layout {
- display: grid;
- grid-template-columns: minmax(0, 1.08fr) minmax(340px, 0.92fr);
- gap: clamp(2.5rem, 5vw, 4.75rem);
- align-items: start;
- margin-top: 3rem;
-}
-
-.diagramColumn {
- position: sticky;
- top: 9.25rem;
-}
-
-.diagram {
- position: relative;
- display: flex;
- flex-direction: column;
- margin: 0;
- padding: clamp(1.25rem, 2.5vw, 2rem);
- overflow: hidden;
- border: 1px solid var(--openui-border-default);
- border-radius: 1.25rem;
- background-color: var(--color-doc-surface);
- background-image:
- linear-gradient(
- color-mix(in srgb, var(--openui-border-default) 45%, transparent) 1px,
- transparent 1px
- ),
- linear-gradient(
- 90deg,
- color-mix(in srgb, var(--openui-border-default) 45%, transparent) 1px,
- transparent 1px
- );
- background-size: 2.25rem 2.25rem;
- box-shadow: 0 1.5rem 3.5rem color-mix(in srgb, var(--openui-text-neutral-primary) 8%, transparent);
-}
-
-.surfaceRow,
-.frameworkRow,
-.providerRow,
-.backendRow {
- position: relative;
- z-index: 1;
- display: grid;
- gap: 0.625rem;
-}
-
-.surfaceRow {
- grid-template-columns: repeat(4, minmax(0, 1fr));
-}
-
-.frameworkRow,
-.providerRow {
- grid-template-columns: repeat(3, minmax(0, 1fr));
-}
-
-.backendRow {
- grid-template-columns: repeat(2, minmax(0, 1fr));
-}
-
-.node,
-.providerNode,
-.backendNode {
- border: 1px solid color-mix(in srgb, var(--openui-text-neutral-primary) 72%, transparent);
- background: color-mix(in srgb, var(--color-doc-surface) 94%, var(--openui-highlight));
- color: var(--openui-text-neutral-primary);
- box-shadow: 0 0.25rem 0.75rem
- color-mix(in srgb, var(--openui-text-neutral-primary) 5%, transparent);
-}
-
-.node {
- display: flex;
- min-height: 4rem;
- align-items: center;
- justify-content: center;
- padding: 0.75rem;
- border-radius: 0.75rem;
- font-size: 0.8125rem;
- font-weight: 600;
- line-height: 1.2;
- text-align: center;
-}
-
-.nodeAgent {
- background: #c8f64b;
- color: #17200b;
-}
-
-.nodeRuntime {
- position: relative;
- z-index: 1;
- min-height: 5rem;
- border-color: #5f7095;
- border-radius: 0.875rem;
- background: #dbe4ff;
- color: #17213a;
- font-size: 1rem;
-}
-
-.runtimeTag {
- position: absolute;
- top: -0.75rem;
- right: 1rem;
- display: inline-flex;
- height: 1.5rem;
- align-items: center;
- gap: 0.3rem;
- padding: 0 0.625rem;
- border: 1px solid #5f7095;
- border-radius: 999px;
- background: #17213a;
- color: #ffffff;
- font-size: 0.6875rem;
- font-weight: 650;
- letter-spacing: 0.04em;
- line-height: 1;
- text-transform: uppercase;
-}
-
-.connector {
- position: relative;
- z-index: 0;
- display: flex;
- height: 2.5rem;
- align-items: center;
- justify-content: center;
- color: var(--openui-text-neutral-tertiary);
-}
-
-.connector::before {
- position: absolute;
- top: 0;
- bottom: 0;
- left: 50%;
- width: 1px;
- background: var(--openui-border-interactive-emphasis);
- content: "";
- transform: translateX(-50%);
-}
-
-.connector svg {
- position: relative;
- padding: 0.125rem;
- background: var(--color-doc-surface);
-}
-
-.backendNode {
- display: flex;
- min-height: 8.25rem;
- flex-direction: column;
- justify-content: space-between;
- gap: 1rem;
- padding: 1.125rem;
- border-radius: 0.875rem;
-}
-
-.backendNode strong {
- font-size: 1rem;
- font-weight: 650;
- letter-spacing: -0.02em;
-}
-
-.backendNode span {
- color: color-mix(in srgb, currentColor 70%, transparent);
- font-size: 0.75rem;
- line-height: 1.55;
-}
-
-.nodeCloud {
- border-color: #7c6fb0;
- background: #e4ddff;
- color: #251d45;
-}
-
-.nodeManaged {
- background: color-mix(in srgb, var(--color-doc-surface) 88%, var(--openui-highlight));
-}
-
-.providerNode {
- display: flex;
- min-height: 3.25rem;
- align-items: center;
- justify-content: center;
- padding: 0.625rem;
- border-radius: 999px;
- font-size: 0.75rem;
- font-weight: 600;
- text-align: center;
-}
-
-.explanations {
- border-top: 1px solid var(--openui-border-default);
-}
-
-.explanation {
- display: grid;
- grid-template-columns: 2.5rem minmax(0, 1fr);
- gap: 1rem;
- padding: 2.25rem 0 2.5rem;
- border-bottom: 1px solid var(--openui-border-default);
-}
-
-.number {
- padding-top: 0.35rem;
- color: var(--openui-text-brand);
- font-size: 0.8125rem;
- font-weight: 650;
- line-height: 1;
-}
-
-.explanationBody h2 {
- margin: 0;
- color: var(--openui-text-neutral-primary);
- font-size: clamp(1.25rem, 2vw, 1.5rem);
- font-weight: 650;
- letter-spacing: -0.045em;
- line-height: 1.05;
-}
-
-.explanationBody p {
- margin: 1rem 0 0;
- color: var(--openui-text-neutral-secondary);
- font-size: 1rem;
- line-height: 1.65;
-}
-
-.explanationLink {
- display: inline-flex;
- align-items: center;
- gap: 0.45rem;
- margin-top: 1.25rem;
- color: var(--openui-text-neutral-primary);
- font-size: 0.875rem;
- font-weight: 650;
- text-decoration: none;
-}
-
-.explanationLink svg {
- transition: transform 160ms ease;
-}
-
-.explanationLink:hover svg {
- transform: translateX(0.2rem);
-}
-
-.explanationLink:focus-visible {
- border-radius: 0.25rem;
- outline: 2px solid var(--openui-border-accent-emphasis);
- outline-offset: 0.25rem;
-}
-
-@media (max-width: 980px) {
- .layout {
- grid-template-columns: 1fr;
- gap: 2.75rem;
- }
-
- .diagramColumn {
- position: static;
- }
-
- .explanation {
- grid-template-columns: 2.25rem minmax(0, 1fr);
- }
-}
-
-@media (max-width: 600px) {
- .layout {
- margin-top: 2.25rem;
- }
-
- .diagram {
- padding: 1rem;
- border-radius: 1rem;
- background-size: 1.75rem 1.75rem;
- }
-
- .surfaceRow {
- grid-template-columns: repeat(2, minmax(0, 1fr));
- }
-
- .frameworkRow {
- grid-template-columns: 1fr;
- }
-
- .backendRow {
- grid-template-columns: 1fr;
- }
-
- .backendNode {
- min-height: 6.5rem;
- }
-
- .providerRow {
- gap: 0.4rem;
- }
-
- .providerNode {
- padding-inline: 0.35rem;
- font-size: 0.6875rem;
- }
-
- .explanation {
- grid-template-columns: 2rem minmax(0, 1fr);
- gap: 0.75rem;
- padding: 1.75rem 0 2rem;
- }
-
- .explanationBody h2 {
- font-size: 1.75rem;
- }
-
- .explanationBody p {
- font-size: 0.9375rem;
- }
-}
-
-@media (prefers-reduced-motion: reduce) {
- .explanationLink svg {
- transition: none;
- }
-}
diff --git a/docs/components/openui-architecture-overview.tsx b/docs/components/openui-architecture-overview.tsx
deleted file mode 100644
index 2739d40ba..000000000
--- a/docs/components/openui-architecture-overview.tsx
+++ /dev/null
@@ -1,126 +0,0 @@
-import { ArrowDownUp, ArrowRight, Sparkles } from "lucide-react";
-import Link from "next/link";
-import styles from "./openui-architecture-overview.module.css";
-
-type ProductExplanation = {
- number: string;
- title: string;
- description: string;
- href: string;
- linkLabel: string;
-};
-
-const explanations: ProductExplanation[] = [
- {
- number: "01",
- title: "Agent Interface",
- description:
- "Agent Interface is a frontend SDK for building agentic experiences. It includes streaming conversations, thread history, native support for generative UI, and an artifact workspace without requiring you to assemble the application shell from scratch.",
- href: "/docs/agent/getting-started/introduction",
- linkLabel: "Explore Agent Interface",
- },
- {
- number: "02",
- title: "OpenUI Lang",
- description:
- "OpenUI Lang is an open-source, streaming-first language and runtime for generative UI. Agents compose interfaces from your component library, while the runtime parses and renders their output progressively as it streams.",
- href: "/docs/openui-lang",
- linkLabel: "Explore OpenUI Lang",
- },
- {
- number: "03",
- title: "OpenUI Cloud",
- description:
- "OpenUI Cloud is the managed backend for OpenUI. It provides model access and automatic fallbacks, validates generated output, persists conversations and artifacts, and includes built-in tools, reports, and presentations.",
- href: "/docs/openui-cloud",
- linkLabel: "Explore OpenUI Cloud",
- },
-];
-
-function Connector() {
- return (
- <div className={styles.connector} aria-hidden="true">
- <ArrowDownUp size={18} strokeWidth={1.6} />
- </div>
- );
-}
-
-function ArchitectureDiagram() {
- return (
- <figure className={styles.diagram} aria-label="OpenUI architecture and ecosystem">
- <div className={styles.surfaceRow}>
- <div className={`${styles.node} ${styles.nodeAgent}`}>Agent Interface</div>
- <div className={styles.node}>CopilotKit</div>
- <div className={styles.node}>assistant-ui</div>
- <div className={styles.node}>Custom</div>
- </div>
-
- <Connector />
-
- <div className={`${styles.node} ${styles.nodeRuntime}`}>
- <span className={styles.runtimeTag}>
- <Sparkles size={12} strokeWidth={2} aria-hidden="true" />
- Gen UI
- </span>
- OpenUI Lang runtime
- </div>
-
- <Connector />
-
- <div className={styles.frameworkRow}>
- <div className={styles.node}>LangGraph</div>
- <div className={styles.node}>Mastra</div>
- <div className={styles.node}>Vercel AI SDK</div>
- </div>
-
- <Connector />
-
- <div className={styles.backendRow}>
- <div className={`${styles.backendNode} ${styles.nodeCloud}`}>
- <strong>OpenUI Cloud</strong>
- <span>Models · validation · persistence · built-in artifacts</span>
- </div>
- <div className={`${styles.backendNode} ${styles.nodeManaged}`}>
- <strong>Self-managed</strong>
- <span>Provider · API route · storage · tools</span>
- </div>
- </div>
-
- <Connector />
-
- <div className={styles.providerRow}>
- <div className={styles.providerNode}>Anthropic</div>
- <div className={styles.providerNode}>OpenAI</div>
- <div className={styles.providerNode}>Google Gemini</div>
- </div>
- </figure>
- );
-}
-
-export function OpenUIArchitectureOverview() {
- return (
- <section className={styles.layout} aria-label="OpenUI products and architecture">
- <div className={styles.diagramColumn}>
- <ArchitectureDiagram />
- </div>
-
- <div className={styles.explanations}>
- {explanations.map((item) => (
- <article className={styles.explanation} key={item.number}>
- <span className={styles.number} aria-hidden="true">
- {item.number}
- </span>
- <div className={styles.explanationBody}>
- <h2>{item.title}</h2>
- <p>{item.description}</p>
- <Link href={item.href} className={styles.explanationLink}>
- {item.linkLabel}
- <ArrowRight size={17} strokeWidth={2} aria-hidden="true" />
- </Link>
- </div>
- </article>
- ))}
- </div>
- </section>
- );
-}
diff --git a/docs/content/docs/openui-lang/examples/agent-frameworks/langgraph-platform.mdx b/docs/content/docs/agent/agent-runtimes/langgraph-platform.mdx
similarity index 73%
rename from docs/content/docs/openui-lang/examples/agent-frameworks/langgraph-platform.mdx
rename to docs/content/docs/agent/agent-runtimes/langgraph-platform.mdx
index 1fc2c4b1e..411baf3d1 100644
--- a/docs/content/docs/openui-lang/examples/agent-frameworks/langgraph-platform.mdx
+++ b/docs/content/docs/agent/agent-runtimes/langgraph-platform.mdx
@@ -1,13 +1,11 @@
---
title: LangGraph Platform
-description: Stream OpenUI generative interfaces from a DeepAgents graph with the supported @openuidev/langchain integration.
+description: Connect Agent Interface to a LangGraph Platform agent through @openuidev/langchain.
---
-OpenUI's renderer is transport-agnostic: it turns streamed OpenUI Lang into
-interactive components no matter which agent produced it. This example uses a
-[DeepAgents](https://docs.langchain.com/oss/javascript/deepagents/overview)
-agent running on LangGraph and the supported `@openuidev/langchain` integration
-to deliver its response as AG-UI events.
+This example connects a [DeepAgents](https://docs.langchain.com/oss/javascript/deepagents/overview)
+agent running on LangGraph to `<AgentInterface />`. The supported `@openuidev/langchain`
+integration converts LangGraph protocol events into the AG-UI stream consumed by Agent Interface.
[View source on GitHub →](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/langgraph-platform)
@@ -49,20 +47,34 @@ The integration has two halves:
Pass the transformer factory to the agent's `streamTransformers` option:
```ts
+import { cloudInstructions } from "@/lib/cloud-prompt";
+import { ChatOpenAI } from "@langchain/openai";
import { openUIStreamTransformer } from "@openuidev/langchain/transformer";
import { createDeepAgent } from "deepagents";
+const model = new ChatOpenAI({
+ model: "google/gemini-3.6-flash-free",
+ apiKey: process.env.THESYS_API_KEY,
+ streaming: true,
+ configuration: { baseURL: "https://api.thesys.dev/v1/embed" },
+});
+
export const graph = createDeepAgent({
- model: `openai:${process.env.OPENAI_MODEL ?? "gpt-5.5"}`,
+ model,
tools: [getWeather, getStockPrice, searchWeb],
- systemPrompt: SYSTEM_PROMPT,
+ systemPrompt: cloudInstructions(
+ [
+ "You are an OpenUI assistant with weather, finance, and research tools.",
+ "Use the tools when they help answer the user's request, then answer only in OpenUI Lang.",
+ ].join("\n"),
+ ),
streamTransformers: [openUIStreamTransformer],
});
```
-The example's `SYSTEM_PROMPT` includes the prompt generated from its OpenUI
-component library. That teaches the agent to return OpenUI Lang after it uses
-the mock weather, stock-price, and research tools.
+`cloudInstructions()` loads the generated component-library specification and wraps it for OpenUI
+Gateway. This teaches the agent to return OpenUI Lang after it uses the mock weather, stock-price,
+and research tools.
The integration package does not depend on DeepAgents. It works with any agent
surface that accepts LangGraph stream transformers.
@@ -104,7 +116,8 @@ The proxy already returns AG-UI, so no LangChain-specific browser adapter or
message conversion is needed:
```tsx
-import { AgentInterface, agUIAdapter, fetchLLM, openuiChatLibrary } from "@openuidev/react-ui";
+import { AgentInterface, agUIAdapter, fetchLLM } from "@openuidev/react-ui";
+import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
const llm = fetchLLM({
url: "/api/chat",
@@ -113,7 +126,7 @@ const llm = fetchLLM({
<AgentInterface
llm={llm}
- componentLibrary={openuiChatLibrary}
+ componentLibrary={openuiLibrary}
agentName="OpenUI + DeepAgents Chat"
/>;
```
@@ -126,8 +139,9 @@ examples/agent-frameworks/langgraph-platform/
|- src/app/api/chat/route.ts # createLangChainStreamResponse()
|- src/agent/agent.ts # DeepAgent with openUIStreamTransformer()
|- src/agent/tools.ts # Mock weather, finance, and research tools
+|- src/lib/cloud-prompt.ts # Generated OpenUI Lang instructions for Gateway
|- src/library.ts # Components the model can render
-|- src/generated/ # Generated OpenUI system prompt
+|- src/generated/ # Generated component-library specification
|- langgraph.json # Local and deployed graph configuration
```
@@ -156,8 +170,8 @@ npm install
cp .env.example .env
```
-Add `OPENAI_API_KEY` to `.env`, then start the LangGraph server and Next.js app
-together:
+Add `THESYS_API_KEY` to `.env`, then start the LangGraph server and Next.js app together. The
+LangGraph process uses this key when it calls OpenUI Gateway:
```bash tab="pnpm" tab-group="pkg"
pnpm dev
@@ -180,8 +194,9 @@ or "AAPL stock price".
## Deploy to LangGraph Platform
-The included `langgraph.json` can be deployed without changing app code. Point
-the proxy at the deployment through `.env`:
+The included `langgraph.json` can be deployed without changing app code. Configure
+`THESYS_API_KEY` for the LangGraph deployment, then point the Next.js proxy at that deployment
+through `.env`:
```bash
LANGGRAPH_API_URL=https://your-deployment.us.langgraph.app
diff --git a/docs/content/docs/openui-lang/examples/harnesses/pi.mdx b/docs/content/docs/agent/agent-runtimes/pi.mdx
similarity index 71%
rename from docs/content/docs/openui-lang/examples/harnesses/pi.mdx
rename to docs/content/docs/agent/agent-runtimes/pi.mdx
index a5e30e46f..261d3a16f 100644
--- a/docs/content/docs/openui-lang/examples/harnesses/pi.mdx
+++ b/docs/content/docs/agent/agent-runtimes/pi.mdx
@@ -1,9 +1,9 @@
---
-title: pi Agent Harness
-description: Chat with the pi coding agent (a real read/bash/edit/write agent) and get its answers as live generative UI, bridged through the pi SDK over an OpenAI-compatible stream.
+title: Pi Agent Harness
+description: Connect Agent Interface to the pi coding agent over an OpenAI-compatible stream.
---
-Anything that can stream text can drive OpenUI's renderer, including a full **coding agent**. This example connects [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (`@earendil-works/pi-coding-agent`), running its default `read` / `bash` / `edit` / `write` tools, to `<AgentInterface>`. Pi calls **OpenUI Cloud** Completions; `generateSystemPrompt({ cloud: true })` is appended so it emits [OpenUI Lang](/docs/openui-lang/overview) for `openuiLibrary` instead of markdown.
+Anything that can stream text can drive OpenUI's renderer, including a full **coding agent**. This example connects [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (`@earendil-works/pi-coding-agent`), running its default `read` / `bash` / `edit` / `write` tools, to `<AgentInterface>`. Pi calls **OpenUI Gateway** Completions; `generateSystemPrompt({ cloud: true, library })` is appended so it emits [OpenUI Lang](/docs/openui-lang/overview) for `openuiLibrary` instead of markdown.
Its mid-turn activity (reasoning and tool runs) surfaces as cards too.
@@ -24,18 +24,18 @@ Its mid-turn activity (reasoning and tool runs) surfaces as cards too.
## How it connects
-| Piece | File | Role |
-| --- | --- | --- |
-| Frontend | `src/app/page.tsx` | A single `<AgentInterface>` wired with `fetchLLM({ streamAdapter: openAIReadableStreamAdapter(), messageFormat: openAIMessageFormat })` and `openuiLibrary`. |
-| Bridge route | `src/app/api/chat/route.ts` | Drives a pi `AgentSession` against OpenUI Cloud Completions and re-emits its events as NDJSON OpenAI chunks (`delta.content` is OpenUI Lang). |
-| Session registry | `src/lib/pi-session.ts` | One persistent `AgentSession` per chat thread, keyed by `threadId`. Injects `generateSystemPrompt({ cloud: true })` and the Cloud model. |
-| Agent | `@earendil-works/pi-coding-agent` | The pi coding agent: `read` / `bash` / `edit` / `write` on the workspace you choose at launch. |
+| Piece | File | Role |
+| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Frontend | `src/app/page.tsx` | A single `<AgentInterface>` wired with `fetchLLM({ streamAdapter: openAIReadableStreamAdapter(), messageFormat: openAIMessageFormat })` and `openuiLibrary`. |
+| Bridge route | `src/app/api/chat/route.ts` | Drives a pi `AgentSession` against OpenUI Gateway Completions and re-emits its events as NDJSON OpenAI chunks (`delta.content` is OpenUI Lang). |
+| Session registry | `src/lib/pi-session.ts` | One persistent `AgentSession` per chat thread, keyed by `threadId`. Injects `generateSystemPrompt({ cloud: true, library })` and the Gateway model. |
+| Agent | `@earendil-works/pi-coding-agent` | The pi coding agent: `read` / `bash` / `edit` / `write` on the workspace you choose at launch. |
Everything runs in **one Next.js process**: the App-Router route _is_ the backend. The pi SDK is embedded directly (no separate server), so there is no second service and no CORS. Each chat thread maps to one persistent pi `AgentSession`, so multi-turn context is preserved.
## Connecting the frontend
-The client is a single `<AgentInterface>` (the artifact chat surface with sidebar thread history). It parses the response with `openAIReadableStreamAdapter()` (NDJSON OpenAI chunks). The Cloud system prompt is attached server-side:
+The client is a single `<AgentInterface>` (the artifact chat surface with sidebar thread history). It parses the response with `openAIReadableStreamAdapter()` (NDJSON OpenAI chunks). The Gateway-managed system prompt is attached server-side:
```tsx
import {
@@ -52,21 +52,19 @@ const llm = fetchLLM({
messageFormat: openAIMessageFormat,
});
-<AgentInterface
- llm={llm}
- componentLibrary={openuiLibrary}
- agentName="OpenUI Agent Harness"
-/>;
+<AgentInterface llm={llm} componentLibrary={openuiLibrary} agentName="OpenUI Agent Harness" />;
```
-`generateSystemPrompt({ cloud: true })` from `@openuidev/lang-core` is the **same** Cloud library sentinel Pi sends on Completions, so the model's markup matches `openuiLibrary`.
+`generateSystemPrompt({ cloud: true, library })` from `@openuidev/lang-core` sends the component-library specification with the Gateway request, so the model's markup matches `openuiLibrary`.
## The bridge route
The route keys a persistent `AgentSession` by `threadId`, injects the OpenUI Lang prompt via `appendSystemPrompt`, subscribes to the session's events, and re-emits them as NDJSON OpenAI chunks. Because pi keeps its own transcript, only the newest user turn is sent to `session.prompt()`:
```ts
-// lib/pi-session.ts: one AgentSession per conversation, model = OpenUI Cloud
+// lib/pi-session.ts: one AgentSession per conversation, model = OpenUI Gateway
+import library from "@/generated/spec.json";
+
const {
AuthStorage,
createAgentSession,
@@ -84,7 +82,7 @@ const loader = new DefaultResourceLoader({
cwd,
agentDir,
settingsManager,
- appendSystemPrompt: [generateSystemPrompt({ instructions })],
+ appendSystemPrompt: [generateSystemPrompt({ cloud: true, library, instructions })],
});
await loader.reload();
const { session } = await createAgentSession({
@@ -147,7 +145,7 @@ This example executes real code on your machine. The agent has the full `read` /
## Authentication
-Pi calls OpenUI Cloud Chat Completions. Set `THESYS_API_KEY` from [console.thesys.dev/keys](https://console.thesys.dev/keys). Optional: `OPENUI_MODEL` (default `google/gemini-3.6-flash-free`). The pi CLI is **not** required.
+Pi calls OpenUI Gateway Chat Completions. Set `THESYS_API_KEY` from [console.thesys.dev/keys](https://console.thesys.dev/keys). Optional: `OPENUI_MODEL` (default `google/gemini-3.6-flash-free`). The pi CLI is **not** required.
## Project layout
@@ -156,7 +154,7 @@ examples/harnesses/pi/
|- src/app/page.tsx # <AgentInterface> + chatLibrary
|- src/app/api/chat/route.ts # pi event stream into NDJSON OpenAI chunks
|- src/lib/pi-session.ts # one persistent pi AgentSession per conversation
-|- src/lib/openui-cloud-models.json # Pi provider pointing at Cloud Completions
+|- src/lib/openui-cloud-models.json # Pi provider pointing at Gateway Completions
|- scripts/launch.mjs # picks the agent workspace, then starts Next
|- next.config.ts # keeps the ESM-only pi SDK external
```
diff --git a/docs/content/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk.mdx b/docs/content/docs/agent/agent-runtimes/vercel-ai-sdk.mdx
similarity index 65%
rename from docs/content/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk.mdx
rename to docs/content/docs/agent/agent-runtimes/vercel-ai-sdk.mdx
index bd3ef3772..dbb765e31 100644
--- a/docs/content/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk.mdx
+++ b/docs/content/docs/agent/agent-runtimes/vercel-ai-sdk.mdx
@@ -1,9 +1,9 @@
---
-title: Vercel AI Chat
-description: AgentInterface over a Vercel AI SDK streamText backend with server-side tools.
+title: Vercel AI SDK
+description: Connect Agent Interface to a Vercel AI SDK streamText backend.
---
-This example uses the [Vercel AI SDK](https://ai-sdk.dev/) (`streamText`, `tool()`, `toUIMessageStreamResponse()`) as the agent backend, and OpenUI's `<AgentInterface />` as the chat UI. The route talks to OpenUI Cloud Completions; the browser decodes the AI SDK UIMessage stream with `vercelAIAdapter()`.
+This example uses the [Vercel AI SDK](https://ai-sdk.dev/) (`streamText`, `tool()`, `toUIMessageStreamResponse()`) as the agent backend and OpenUI's `<AgentInterface />` as the chat UI. The browser decodes the AI SDK UIMessage stream with `vercelAIAdapter()`.
[View source on GitHub →](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/vercel-ai-sdk)
@@ -22,7 +22,7 @@ This example uses the [Vercel AI SDK](https://ai-sdk.dev/) (`streamText`, `tool(
## How it connects
-The API route calls `streamText` with Cloud Completions, `generateSystemPrompt({ cloud: true })`, and tools defined with `tool()`. When the model calls a tool, the AI SDK executes it server-side and continues — up to 5 steps. The response is a UIMessage stream.
+The API route calls `streamText` through OpenUI Gateway with OpenUI Lang instructions and tools defined with `tool()`. When the model calls a tool, the AI SDK executes it server-side and continues — up to 5 steps. The response is a UIMessage stream.
The page passes that stream to `<AgentInterface />`:
@@ -33,7 +33,7 @@ import {
vercelAIAdapter,
vercelAIMessageFormat,
} from "@openuidev/react-ui";
-import { chatLibrary } from "@openuidev/thesys";
+import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
const llm = fetchLLM({
url: "/api/chat",
@@ -41,11 +41,7 @@ const llm = fetchLLM({
messageFormat: vercelAIMessageFormat,
});
-<AgentInterface
- llm={llm}
- componentLibrary={chatLibrary}
- agentName="OpenUI + Vercel AI SDK"
-/>;
+<AgentInterface llm={llm} componentLibrary={openuiLibrary} agentName="OpenUI + Vercel AI SDK" />;
```
Storage is omitted, so AgentInterface uses its built-in in-memory default (wiped on reload).
@@ -53,12 +49,12 @@ Storage is omitted, so AgentInterface uses its built-in in-memory default (wiped
## Backend
```ts
+import { cloudInstructions } from "@/lib/cloud-prompt";
+import { tools } from "@/lib/tools";
import { createOpenAI } from "@ai-sdk/openai";
-import { generateSystemPrompt } from "@openuidev/lang-core";
import { convertToModelMessages, stepCountIs, streamText } from "ai";
-import { tools } from "@/lib/tools";
-const openai = createOpenAI({
+const gateway = createOpenAI({
baseURL: "https://api.thesys.dev/v1/embed",
apiKey: process.env.THESYS_API_KEY,
});
@@ -66,8 +62,8 @@ const openai = createOpenAI({
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
- model: openai.chat("google/gemini-3.6-flash-free"),
- system: generateSystemPrompt({ cloud: true }),
+ model: gateway.chat("google/gemini-3.6-flash-free"),
+ system: cloudInstructions(),
messages: await convertToModelMessages(messages),
tools,
stopWhen: stepCountIs(5),
@@ -82,8 +78,11 @@ Tools live in `src/lib/tools.ts` (`get_weather`, `get_stock_price`, `search_web`
```
examples/agent-frameworks/vercel-ai-sdk/
-|- src/app/ # Next.js app (layout, page, API route)
-|- src/lib/tools.ts # Vercel AI SDK tool() definitions
+|- src/app/page.tsx # AgentInterface with the Vercel AI stream adapter
+|- src/app/api/chat/route.ts # streamText() through OpenUI Gateway
+|- src/lib/cloud-prompt.ts # Generated OpenUI Lang instructions
+|- src/lib/tools.ts # Vercel AI SDK tool() definitions
+|- src/library.ts # Component library used to generate the prompt spec
```
## Run the example
@@ -112,7 +111,7 @@ cd examples/agent-frameworks/vercel-ai-sdk
npm install
```
-2. Create a `.env.local` file with your OpenUI Cloud key:
+2. Create a `.env.local` file with your Gateway key:
```bash
THESYS_API_KEY=sk-th-...
diff --git a/docs/content/docs/openui-lang/examples/agent-frameworks/vercel-eve.mdx b/docs/content/docs/agent/agent-runtimes/vercel-eve.mdx
similarity index 79%
rename from docs/content/docs/openui-lang/examples/agent-frameworks/vercel-eve.mdx
rename to docs/content/docs/agent/agent-runtimes/vercel-eve.mdx
index 6f0190ba2..574229169 100644
--- a/docs/content/docs/openui-lang/examples/agent-frameworks/vercel-eve.mdx
+++ b/docs/content/docs/agent/agent-runtimes/vercel-eve.mdx
@@ -1,6 +1,6 @@
---
title: Vercel Eve
-description: Connect a Vercel Eve agent to OpenUI and render streamed responses and tool calls as live generative UI.
+description: Connect Agent Interface to Vercel Eve's resumable agent sessions.
---
OpenUI can render output from a [Vercel Eve](https://github.com/vercel/eve) agent without replacing Eve's session protocol. This example uses Eve's built-in HTTP channel for delivery and resumable streaming. `eveAdapter()` from `@openuidev/react-headless` maps Eve's NDJSON session stream to AG-UI for `<AgentInterface />`.
@@ -24,12 +24,12 @@ The agent receives the OpenUI component-library prompt when a session starts, so
## How it connects
-| Piece | File | Role |
-| ------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
-| OpenUI chat | `src/app/page.tsx` | Renders `<AgentInterface />` with `eveAdapter()` and the Cloud chat library. |
-| Session bridge | `src/eve-chat.ts` | Delivers turns through Eve's HTTP API and returns Eve's raw NDJSON stream. |
-| Event adapter | `eveAdapter()` | Maps Eve text, tool-call, and failure events to AG-UI (`@openuidev/react-headless`). |
-| Agent instructions | `agent/instructions/openui.ts` | Adds the generated OpenUI system prompt when each Eve session starts. |
+| Piece | File | Role |
+| ------------------ | ------------------------------ | ------------------------------------------------------------------------------------ |
+| OpenUI chat | `src/app/page.tsx` | Renders `<AgentInterface />` with the built-in `openuiLibrary`. |
+| Session bridge | `src/eve-chat.ts` | Delivers turns through Eve's HTTP API and returns Eve's raw NDJSON stream. |
+| Event adapter | `eveAdapter()` | Maps Eve text, tool-call, and failure events to AG-UI (`@openuidev/react-headless`). |
+| Agent instructions | `agent/instructions/openui.ts` | Adds the Gateway-compatible OpenUI instructions when each Eve session starts. |
The Next.js app and Eve development server start together through `withEve()`. The browser uses
Eve's same-origin session endpoints directly, so the integration does not need a custom backend
@@ -41,8 +41,8 @@ stream cursor, preserving multi-turn context and resumable delivery.
The page creates Eve-backed chat callbacks and passes them to `<AgentInterface />`. `eveAdapter()` consumes Eve's NDJSON session stream:
```tsx
-import { AgentInterface, useSystemThemeMode } from "@openuidev/react-ui";
-import { chatLibrary } from "@openuidev/thesys";
+import { AgentInterface } from "@openuidev/react-ui";
+import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
import { createEveChatProps } from "../eve-chat";
const { llm, storage } = createEveChatProps();
@@ -50,7 +50,7 @@ const { llm, storage } = createEveChatProps();
<AgentInterface
llm={llm}
storage={storage}
- componentLibrary={chatLibrary}
+ componentLibrary={openuiLibrary}
agentName="Eve + OpenUI"
/>;
```
@@ -62,20 +62,21 @@ const { llm, storage } = createEveChatProps();
Eve loads instructions from `agent/instructions`. A dynamic instruction adds the component library's generated prompt once when a session starts:
```ts
-import { openuiChatLibrary, openuiChatPromptOptions } from "@openuidev/react-ui/genui-lib";
+import { cloudInstructions } from "../../src/lib/cloud-prompt";
import { defineDynamic, defineInstructions } from "eve/instructions";
export default defineDynamic({
events: {
"session.started": () =>
defineInstructions({
- markdown: openuiChatLibrary.prompt(openuiChatPromptOptions),
+ markdown: cloudInstructions(),
}),
},
});
```
-This keeps the model's instructions synchronized with the exact component library used by the renderer.
+`cloudInstructions()` loads the generated specification for the same `openuiLibrary` used by the
+renderer and wraps it for OpenUI Gateway.
## The session bridge
@@ -119,8 +120,9 @@ session.failed -> RUN_ERROR
Tool calls and text share one assistant message ID. OpenUI renders tool activity in its behind-the-scenes section and the final OpenUI Lang response in the conversation.
-The included `get_current_time` tool is a minimal example. Additional Eve tools automatically
-surface through the same AG-UI tool-call mapping.
+The included `get_weather` tool calls Open-Meteo. The example disables Eve's built-in
+`ask_question` tool so clarifying questions remain visible in the chat. Additional Eve tools
+automatically surface through the same AG-UI tool-call mapping.
## Thread persistence
@@ -139,10 +141,14 @@ The demo channel uses anonymous authentication for local development. Replace `n
examples/agent-frameworks/vercel-eve/
|- agent/agent.ts # Eve model and build configuration
|- agent/channels/eve.ts # Eve HTTP session channel
+|- agent/instructions/identity.md # Standing agent identity
|- agent/instructions/openui.ts # Generated OpenUI Lang instructions
-|- agent/tools/get_current_time.ts # Example Eve tool
+|- agent/tools/get_weather.ts # Open-Meteo weather tool
+|- agent/tools/ask_question.ts # Disables Eve's built-in ask_question tool
|- src/app/page.tsx # OpenUI AgentInterface chat
|- src/eve-chat.ts # Session transport, eveAdapter, persistence
+|- src/library.ts # Component library used to generate the prompt spec
+|- src/lib/cloud-prompt.ts # Gateway-compatible OpenUI Lang instructions
|- src/thread-store.ts # Browser thread and transcript storage
|- next.config.ts # Installs Eve with withEve()
```
@@ -158,9 +164,9 @@ pnpm install
# 2. Enter the example.
cd examples/agent-frameworks/vercel-eve
-# 3. Configure an OpenAI-compatible model provider.
+# 3. Configure OpenUI Gateway.
cp .env.example .env
-# Edit .env and set LLM_API_KEY.
+# Edit .env and set THESYS_API_KEY.
# 4. Start Next.js and the embedded Eve development server.
pnpm dev
@@ -173,9 +179,9 @@ bun install
# 2. Enter the example.
cd examples/agent-frameworks/vercel-eve
-# 3. Configure an OpenAI-compatible model provider.
+# 3. Configure OpenUI Gateway.
cp .env.example .env
-# Edit .env and set LLM_API_KEY.
+# Edit .env and set THESYS_API_KEY.
# 4. Start Next.js and the embedded Eve development server.
bun dev
@@ -188,9 +194,9 @@ yarn install
# 2. Enter the example.
cd examples/agent-frameworks/vercel-eve
-# 3. Configure an OpenAI-compatible model provider.
+# 3. Configure OpenUI Gateway.
cp .env.example .env
-# Edit .env and set LLM_API_KEY.
+# Edit .env and set THESYS_API_KEY.
# 4. Start Next.js and the embedded Eve development server.
yarn dev
@@ -203,35 +209,40 @@ npm install
# 2. Enter the example.
cd examples/agent-frameworks/vercel-eve
-# 3. Configure an OpenAI-compatible model provider.
+# 3. Configure OpenUI Gateway.
cp .env.example .env
-# Edit .env and set LLM_API_KEY.
+# Edit .env and set THESYS_API_KEY.
# 4. Start Next.js and the embedded Eve development server.
npm run dev
```
-Open [http://localhost:3000](http://localhost:3000) and start a conversation. `OPENAI_API_KEY`,
-`OPENAI_MODEL`, and `OPENAI_BASE_URL` are accepted as aliases for the `LLM_*` variables.
+Open [http://localhost:3000](http://localhost:3000) and start a conversation. The example requires
+`THESYS_API_KEY` and accepts an optional `OPENUI_MODEL` override. The default model is
+`google/gemini-3.6-flash-free`.
The repository scripts also expose Eve directly when you need to build or run the agent separately:
```bash tab="pnpm" tab-group="pkg"
+pnpm eve:dev
pnpm eve:build
pnpm eve:start
```
```bash tab="bun" tab-group="pkg"
+bun eve:dev
bun eve:build
bun eve:start
```
```bash tab="yarn" tab-group="pkg"
+yarn eve:dev
yarn eve:build
yarn eve:start
```
```bash tab="npm" tab-group="pkg"
+npm run eve:dev
npm run eve:build
npm run eve:start
```
diff --git a/docs/content/docs/agent/core-concepts/artifacts.mdx b/docs/content/docs/agent/core-concepts/artifacts.mdx
index c9ec10d37..408e435e6 100644
--- a/docs/content/docs/agent/core-concepts/artifacts.mdx
+++ b/docs/content/docs/agent/core-concepts/artifacts.mdx
@@ -5,8 +5,6 @@ description: Durable, first-class conversation outputs like slides, reports, and
An **artifact** is a first-class output of a conversation. Slides, reports, dashboards, a small app: things the user opens, reads, and returns to. An artifact is not a chat message and not a tool result. Once it exists, it stands on its own.
-On OpenUI Cloud, the agent produces **slides and reports** for you, with nothing to wire.
-
## Where an artifact shows up
The same renderer drives two surfaces:
diff --git a/docs/content/docs/agent/core-concepts/conversations.mdx b/docs/content/docs/agent/core-concepts/conversations.mdx
index 56c224dbc..165a4ee98 100644
--- a/docs/content/docs/agent/core-concepts/conversations.mdx
+++ b/docs/content/docs/agent/core-concepts/conversations.mdx
@@ -5,14 +5,14 @@ description: How to persist conversations and make them accessible to Agent Inte
Every conversation with `AgentInterface` is stored through a `storage` adapter. Each message is persisted (its content, any extra context, and the complete response including text and tool calls), and `AgentInterface` reloads the threads and messages of the selected conversation automatically.
-On OpenUI Cloud, `useOpenuiCloudStorage` is that adapter. Cloud stores and reloads every conversation, so you run no database and write no persistence logic.
+Connect an application-owned storage adapter to store and reload conversations from your database. Without one, Agent Interface keeps the conversation in memory for the current page session.
This persistence lets users return to previous conversations, and the full history informs the agent's future responses.
## What gets stored
- **Threads:** the containers for a conversation. Each has an `id`, a title, and metadata like `createdAt`.
-- **Messages:** the turns inside a thread. Each has a `role` (`user`, `assistant`, or `tool`) and its content, including any [generative UI](/docs/agent/core-concepts/generative-ui) or [artifacts](/docs/agent/core-concepts/artifacts) the assistant produced.
+- **Messages:** the turns inside a thread. Each has a `role` (`user`, `assistant`, or `tool`) and its content, including any [generative UI](/docs/agent/core-concepts/generative-ui) the assistant produced.
<img
src="/images/agent/conversation-history-sidebar.png"
@@ -34,5 +34,3 @@ function ChatCount() {
```
Both are selector hooks: pass a function that picks the slice you need, and the component re-renders only when that slice changes. They work anywhere inside `AgentInterface`. See [Hooks](/docs/agent/reference/hooks) for the full state.
-
-<Callout type="info">**Self-hosted:** the scaffold stores conversations in a local store it generates. To use your own database, implement the storage contract. See [Adapters & formats](/docs/agent/reference/adapters-and-formats).</Callout>
diff --git a/docs/content/docs/agent/core-concepts/generative-ui.mdx b/docs/content/docs/agent/core-concepts/generative-ui.mdx
index b97bc2abe..72c765477 100644
--- a/docs/content/docs/agent/core-concepts/generative-ui.mdx
+++ b/docs/content/docs/agent/core-concepts/generative-ui.mdx
@@ -1,20 +1,24 @@
---
title: Generative UI
-description: "Render interactive components inline in chat messages: tables, forms, charts, and cards, not just markdown."
+description: Render streamed OpenUI Lang as interactive application components inside a conversation.
---
-An assistant message is normally markdown text. **Generative UI (GenUI)** lets the agent render real components instead: tables, forms, charts, and cards, inline in the message and streaming as the reply arrives.
+An assistant message is normally markdown text. With OpenUI Lang, the agent can compose the
+components your application defines: tables, forms, charts, cards, or domain-specific controls.
+The interface renders progressively as the response streams.
-Turn it on with one prop. On OpenUI Cloud, the components and model instructions are managed for you.
+Build the component library with OpenUI Lang, then pass the same library to Agent Interface:
```tsx
import { AgentInterface } from "@openuidev/react-ui";
-import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
+import { library } from "./library";
-<AgentInterface llm={llm} componentLibrary={openuiLibrary} />;
+<AgentInterface llm={llm} componentLibrary={library} />;
```
-`openuiLibrary` covers layout, content, tables, charts, forms, and buttons, enough for most agents. To define your own components, see the [OpenUI Lang overview](/docs/openui-lang/overview).
+The component definitions remain in your application. They determine what the model may generate,
+how each element renders, and which interactions are available. Start with the
+[OpenUI Lang Quick Start](/docs/openui-lang/quickstart) to create that contract.
<video
src="/videos/agent/generative-ui-chart-inline.mp4"
@@ -27,29 +31,10 @@ import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
## Interactivity
-Generated components are interactive, and the runtime wires up the behavior. When a user fills a form or clicks a button, one of two things happens:
+Generated components can continue the conversation or update locally:
-- **It continues the conversation.** The interaction goes back to the agent as the next turn, carrying the current field values.
-- **It updates in place.** The component refreshes data, changes a value, or opens a link, with no round trip to the model.
+- **Continue the conversation:** Send an interaction and its current values back as the next turn.
+- **Update in place:** Refresh data, change state, or open a link without another model request.
-Form state is tracked automatically and saved with the thread, so a half-filled form survives a reload. See [Interactivity](/docs/openui-lang/interactivity) for the details.
-
-<video
- src="/videos/agent/generative-ui-form-interaction.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-## GenUI vs artifacts
-
-Use GenUI when the UI is the reply: a form to fill, a table to scan. Use [artifacts](/docs/agent/core-concepts/artifacts) when the output is a durable thing the user returns to on its own surface. An agent can do both in one thread.
-
-
-## Open-ended HTML
-
-OpenUI can also let the model generate a complete HTML/CSS/JavaScript experience instead of composing predefined components. The same response stream can show the incoming source, then render the completed document in a sandboxed iframe inside the detailed-view panel.
-
-See [Open-ended HTML](/docs/agent/guides/open-ended-html) for the minimal pattern.
+Form state is tracked with the thread, so an in-progress interaction can survive navigation and
+reloads. See [Interactivity](/docs/openui-lang/interactivity) for the language and renderer behavior.
diff --git a/docs/content/docs/agent/core-concepts/tools.mdx b/docs/content/docs/agent/core-concepts/tools.mdx
index 0b6bd4b8f..50a9632b4 100644
--- a/docs/content/docs/agent/core-concepts/tools.mdx
+++ b/docs/content/docs/agent/core-concepts/tools.mdx
@@ -1,6 +1,6 @@
---
title: Tools
-description: Let the agent call functions to fetch data and take actions, with your own tools or OpenUI Cloud's built-ins.
+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.
@@ -54,14 +54,4 @@ const tools = [
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.
-This declaration is the same on OpenUI Cloud and self-hosted. Your code always runs your own tools. Only the built-in tools below run inside Cloud.
-
-<Callout type="info">**Self-hosted:** you run the loop in your own route. Call the provider, execute any tool it asks for, append the result, and call again until the model returns text with no more tool calls. See [Self-hosting](/docs/agent/reference/self-hosting).</Callout>
-
-## Built-in tools (OpenUI Cloud)
-
-OpenUI Cloud ships tools you enable without writing any implementation. Cloud holds the keys and runs them. For example, `image_search` lets the agent pull in relevant images.
-
-## Tools and artifacts
-
-A tool call is also one way an [artifact](/docs/agent/core-concepts/artifacts) gets produced. When the agent calls something like `generate_report`, the interface matches a renderer to that tool by name and draws the result in its own panel. The tool call is the mechanism; the artifact is the output. Many tool calls, like `get_weather`, produce no artifact at all. See [Custom artifacts](/docs/agent/guides/custom-artifacts) to render a tool's result as an artifact.
+Your application runs these functions on the server and returns their results to the agent.
diff --git a/docs/content/docs/agent/customize/message-rendering.mdx b/docs/content/docs/agent/customize/message-rendering.mdx
index e1cd8bd51..2bdb409ca 100644
--- a/docs/content/docs/agent/customize/message-rendering.mdx
+++ b/docs/content/docs/agent/customize/message-rendering.mdx
@@ -75,4 +75,4 @@ When a message renders, `AgentInterface` picks the first matching renderer:
2. **`componentLibrary` (GenUI):** rich rendering so the model can emit components inline.
3. **Built-in default:** markdown for assistant, plain text for user, tool calls inline.
-The props compose. Set `components.AssistantMessage` and your component wins for assistant messages, while user messages still flow through GenUI or the default.
\ No newline at end of file
+The props compose. Set `components.AssistantMessage` and your component wins for assistant messages, while user messages still flow through GenUI or the default.
diff --git a/docs/content/docs/agent/customize/sidebar.mdx b/docs/content/docs/agent/customize/sidebar.mdx
index 8943e77b8..0e66cec0f 100644
--- a/docs/content/docs/agent/customize/sidebar.mdx
+++ b/docs/content/docs/agent/customize/sidebar.mdx
@@ -3,13 +3,13 @@ title: Sidebar
description: Add your own nav items to the left sidebar, or replace it entirely through the Sidebar slot.
---
-The left sidebar holds the header, the thread list, and (when artifact storage is configured) an artifact entry. Add a couple of your own links above the threads, or take over the whole region.
+The left sidebar holds the header and thread list. Add a couple of your own links above the threads, or take over the whole region.
Both go through the `Sidebar` slot. Its children replace the sidebar's inner content, so you re-include the default pieces you want to keep. `SidebarContent` and `SidebarSeparator` are primitives you compose inside the slot, not slots themselves.
## Add nav items above the thread list
-The common case: a few of your own links, the default thread list underneath. Pass children to the `Sidebar` slot and re-include `SidebarHeader`, `ArtifactNav`, and `ThreadList`.
+The common case: a few of your own links, with the default thread list underneath. Pass children to the `Sidebar` slot and re-include `SidebarHeader` and `ThreadList`.
```tsx
import { AgentInterface } from "@openuidev/react-ui";
@@ -29,11 +29,10 @@ import { Home, LayoutDashboard } from "lucide-react";
<AgentInterface.SidebarSeparator />
{/* keep the defaults */}
- <AgentInterface.ArtifactNav />
<AgentInterface.ThreadList />
</AgentInterface.SidebarContent>
</AgentInterface.Sidebar>
-</AgentInterface>
+</AgentInterface>;
```
A `SidebarItem` with `path` navigates. Without one, handle the click yourself via `onClick`. When `path` is set, the item highlights while its route is active, and clicking it calls the router. Your `onClick` runs first; call `event.preventDefault()` to suppress navigation.
@@ -77,8 +76,6 @@ import { Home, LifeBuoy } from "lucide-react";
Home
</AgentInterface.SidebarItem>
- <AgentInterface.SidebarSeparator />
- <AgentInterface.ArtifactNav />
<AgentInterface.ThreadList />
<AgentInterface.SidebarSeparator />
@@ -90,9 +87,7 @@ import { Home, LifeBuoy } from "lucide-react";
</AgentInterface.SidebarItem>
</AgentInterface.SidebarContent>
</AgentInterface.Sidebar>
-</AgentInterface>
+</AgentInterface>;
```
-<Callout type="info">`ArtifactNav` renders nothing unless `storage.artifact` is configured. It auto-appears in the default sidebar and stays safe to include in a custom one regardless. With [artifact categories](/docs/agent/core-concepts/artifacts) it renders one entry per category, otherwise a single "Artifacts" item.</Callout>
-
Put `SidebarHeader` inside the slot, not at the top level. When you replace the sidebar, you compose the header there too. `NewChatButton` is not part of the default sidebar content (it lives in the mobile header), so place it yourself if you want it on desktop.
diff --git a/docs/content/docs/agent/customize/welcome-and-starters.mdx b/docs/content/docs/agent/customize/welcome-and-starters.mdx
index 2ace35ef0..47af58915 100644
--- a/docs/content/docs/agent/customize/welcome-and-starters.mdx
+++ b/docs/content/docs/agent/customize/welcome-and-starters.mdx
@@ -16,8 +16,8 @@ const llm = fetchLLM({ url: "/api/chat", streamAdapter: agUIAdapter() });
const starters = [
{
- displayText: "Summarize my latest report",
- prompt: "Summarize the key findings from my most recent quarterly report.",
+ displayText: "Summarize customer feedback",
+ prompt: "Summarize the themes in the latest customer feedback.",
},
{
displayText: "Build a revenue dashboard",
@@ -32,7 +32,11 @@ export default function App() {
Each entry is `{ displayText, prompt, icon? }`. Clicking a starter sends its `prompt` as a user message, exactly as if the user typed it, so write `prompt` as a full instruction. Omit `icon` for a default lightbulb, pass a React node for a custom glyph, or pass `<></>` for none. `starterVariant` is `"short"` (compact pills) or `"long"` (a vertical list with icons).
-<Callout type="info">`starters` and `starterVariant` set on `AgentInterface` flow down to the Welcome and Composer slots. Each slot can override with its own value. Pass `[]` to a slot to suppress inherited starters there.</Callout>
+<Callout type="info">
+ `starters` and `starterVariant` set on `AgentInterface` flow down to the Welcome and Composer
+ slots. Each slot can override with its own value. Pass `[]` to a slot to suppress inherited
+ starters there.
+</Callout>
## The Welcome slot
@@ -42,7 +46,7 @@ Each entry is `{ displayText, prompt, icon? }`. Clicking a starter sends its `pr
<AgentInterface llm={llm}>
<AgentInterface.Welcome
title="What can I help you build?"
- description="Ask about your reports and dashboards, or pick a starter below."
+ description="Ask about your data and dashboards, or pick a starter below."
image={{ url: "/logo.svg" }}
starters={starters}
starterVariant="long"
@@ -61,18 +65,17 @@ import { AgentInterface, useThread } from "@openuidev/react-ui";
function Starter({ label, prompt }: { label: string; prompt: string }) {
const processMessage = useThread((s) => s.processMessage);
- return (
- <button onClick={() => processMessage({ role: "user", content: prompt })}>
- {label}
- </button>
- );
+ return <button onClick={() => processMessage({ role: "user", content: prompt })}>{label}</button>;
}
<AgentInterface llm={llm}>
<AgentInterface.Welcome>
<div className="my-welcome">
<h1>What can I help you build?</h1>
- <Starter label="Build a dashboard" prompt="Build a revenue dashboard for the last six months." />
+ <Starter
+ label="Build a dashboard"
+ prompt="Build a revenue dashboard for the last six months."
+ />
</div>
</AgentInterface.Welcome>
</AgentInterface>;
diff --git a/docs/content/docs/agent/getting-started/introduction.mdx b/docs/content/docs/agent/getting-started/introduction.mdx
index a38a4ee66..dc23e1894 100644
--- a/docs/content/docs/agent/getting-started/introduction.mdx
+++ b/docs/content/docs/agent/getting-started/introduction.mdx
@@ -1,48 +1,37 @@
---
-title: Agent Interface
-description: "A generative-UI toolkit for building agent interfaces in React: interactive components and artifacts inside a complete, streaming chat, on OpenUI Cloud or your own backend."
+title: Introduction
+description: A complete React SDK for building streaming agent interfaces with OpenUI Lang.
---
-Agent Interface helps developers ship production agent UIs. Your agent renders interactive components and artifacts (dashboards, slides, reports) inside a complete, streaming chat, on OpenUI Cloud or your own backend.
+Agent Interface is OpenUI's optional React SDK for teams that want a complete chat surface instead of integrating the renderer into assistant-ui, CopilotKit, or a custom message UI.
-<video
- src="/videos/agent/agent-interface-hero.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
+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.
-## Why Agent Interface?
+## When to use Agent Interface
-Building an agent UI from scratch is a lot of work before you ship a single feature. You wire up streaming and thread history, render every message, build the interactive components your agent returns, add panels for richer outputs, theme it all, and make it work on mobile.
+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.
-Agent Interface gives you that in one component. Give it a component library and your agent renders those components inline, streaming their props as they arrive. Durable outputs like dashboards, slides, and reports become artifacts your users can open, revisit, and edit. Connect it to OpenUI Cloud and it handles conversations, generative UI, and artifacts for you. You can also run it on your own backend.
+## The integration boundary
+
+`<AgentInterface />` receives an `llm` transport, an optional conversation `storage` adapter, and your OpenUI component library. The transport streams agent events; Agent Interface manages the chat experience; the renderer turns OpenUI Lang into application components.
```tsx
-import { AgentInterface, fetchLLM, openAIResponsesAdapter, openAIConversationMessageFormat } from "@openuidev/react-ui";
-import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
+import {
+ AgentInterface,
+ fetchLLM,
+ openAIConversationMessageFormat,
+ openAIResponsesAdapter,
+} from "@openuidev/react-ui";
-// Point the llm adapter at your backend route.
const llm = fetchLLM({
url: "/api/chat",
- streamAdapter: openAIResponsesAdapter(),
messageFormat: openAIConversationMessageFormat,
+ streamAdapter: openAIResponsesAdapter(),
});
-export default function App() {
- return <AgentInterface llm={llm} componentLibrary={openuiLibrary} />;
+export function Agent() {
+ return <AgentInterface llm={llm} componentLibrary={componentLibrary} />;
}
```
-That is the whole integration. `AgentInterface` renders the streaming chat with generative UI on. Point `storage` at OpenUI Cloud (or your own backend) to add conversation history and artifacts.
-
-## What's included
-
-- **`<AgentInterface>`:** a complete chat UI out of the box, with a sidebar, thread list, composer, streaming, and a responsive layout.
-- **Generative UI:** your agent renders rich, interactive components inline in the conversation instead of plain text.
-- **Artifacts:** durable outputs like dashboards, slides, and reports, opened in side panels and full pages.
-- **Fully customizable:** override any slot, theme with design tokens, and swap in your own message rendering.
-- **OpenUI Cloud or self-hosted:** managed conversations, generative UI, and artifacts, or run it on your own backend.
-
+The `/api/chat` route connects to your agent backend and returns a supported stream. Continue with the [Quickstart](/docs/agent/getting-started/quickstart) or review the available [adapters and formats](/docs/agent/reference/adapters-and-formats).
diff --git a/docs/content/docs/agent/getting-started/openui-cloud.mdx b/docs/content/docs/agent/getting-started/openui-cloud.mdx
deleted file mode 100644
index 59b7ace67..000000000
--- a/docs/content/docs/agent/getting-started/openui-cloud.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-title: OpenUI Cloud
-description: "The managed backend for Agent Interface: conversation history, production-grade generative UI, and prebuilt presentation and report artifacts."
----
-
-OpenUI Cloud is the managed backend for Agent Interface. It is built on the open-source OpenUI rendering engine and adds the production layers on top, so you point your app at it and ship instead of operating that infrastructure yourself.
-
-<img
- src="/images/agent/cloud-interface-with-artifacts.png"
- alt="A Cloud-rendered, on-brand interface beside a report and presentation artifact it generated"
- className="w-full rounded-lg border"
-/>
-
-## What you get
-
-- **Conversation history.** Threads and messages are stored and reloaded for you. No database to run, no endpoints to write.
-- **Production-grade generative UI.** A pre-tested, responsive, accessible component set. Invalid model output is detected and corrected before the user sees it, and a middleware layer normalizes model quirks so generation stays consistent across providers and model versions.
-- **Prebuilt artifacts.** Reports and presentations the agent generates and renders out of the box, with no renderer to build.
-- **Theming and white-labeling.** Fonts, colors, spacing, and component styles are configurable, so every agent-rendered UI is on-brand by default. Multiple brand configurations are supported.
-- **Production hardening.** Model fallbacks and a degraded mode when a provider is slow or down, version pinning and rollback to a known-good setup, and observability with an audit trail: render success, latency, token usage, and a record of what was rendered for whom.
-
-## Connect
-
-`AgentInterface` connects to Cloud through two props, both wired by the `openui-cloud` CLI template:
-
-- **`llm`** points at a thin `/api/chat` route in your app that proxies to Cloud's Responses endpoint. Your `THESYS_API_KEY` stays on that route and never reaches the browser. On the client it uses `openAIResponsesAdapter()` with `openAIConversationMessageFormat`.
-- **`storage`** is `useOpenuiCloudStorage()` from `@openuidev/thesys`. It reads conversations and artifacts from Cloud directly, authenticated by a short-lived frontend token your app mints from a `/api/frontend-token` route (so the server key never reaches the browser).
-
-The component set (`chatLibrary`), artifact renderers, and categories also come from `@openuidev/thesys`. The model catalog and allowlist remain app-owned; the reusable `ModelSwitcher` comes from `@openuidev/react-ui`.
-
-Add your server-side key:
-
-```bash
-THESYS_API_KEY=sk-th-your-key
-```
-
-Generate a key in the [Thesys console](https://console.thesys.dev/keys). See [Quickstart](/docs/agent/getting-started/quickstart) to scaffold a Cloud app.
-
-## OpenUI vs OpenUI Cloud
-
-| | OpenUI (open source) | OpenUI Cloud |
-|---|---|---|
-| Generative UI rendering | ✓ | ✓ |
-| Streaming and progressive rendering | ✓ | ✓ |
-| Production-grade components | Basic | Optimized, cross-browser tested |
-| Prebuilt report and presentation artifacts | ✗ | ✓ |
-| Theming and white-labeling | ✗ | ✓ |
-| Error detection and correction | ✗ | ✓ |
-| Cross-model consistency | ✗ | ✓ |
-| Fallbacks, versioning, observability | ✗ | ✓ |
-
-## Roadmap
-
-Coming next:
-
-- **Document exports.** Download reports and presentations as PDF, DOCX, and PPT.
-- **Live dashboards.** Dashboards backed by your business-specific data.
-- **Manual editing.** Edit generated reports and presentations by hand.
-- **Insights.** See what users ask, where they hit dead ends, and which usage patterns to build for next.
-- **Continual learning and memory.** Cloud learns how individual users prefer information presented and adapts over time.
diff --git a/docs/content/docs/agent/getting-started/quickstart.mdx b/docs/content/docs/agent/getting-started/quickstart.mdx
index 05fd6c734..751b6ee4b 100644
--- a/docs/content/docs/agent/getting-started/quickstart.mdx
+++ b/docs/content/docs/agent/getting-started/quickstart.mdx
@@ -1,107 +1,55 @@
---
title: Quickstart
-description: Scaffold a working streaming chat agent (conversation history, tools, artifacts, and generative UI) in a few minutes with the OpenUI CLI.
+description: Scaffold a streaming Agent Interface application connected to your model provider.
---
-The CLI scaffolds a complete Next.js app: a streaming chat with a sidebar, thread list, composer, and generative UI on by default. You write no boilerplate: create, connect, run. You can add the <a style={{ color: 'var(--swatch-lime-500)' }} href="/skills.md">OpenUI skill</a> from here to enable working with coding agents.
+The OpenUI CLI can scaffold a Next.js agent application with Agent Interface, an OpenUI renderer, and a server route for model generation.
-## 1. Create
+## 1. Create the application
-Run the create command and answer the prompts. One prompt asks you to choose your agent backend:
-For most prototypes and evaluations, start with **OpenUI Cloud, the recommended
-default**: hosted models plus managed conversation history, streaming, built-in
-tools, and ready-to-use reports and presentations. You can ship without operating
-the model, storage, or artifact infrastructure. Choose **self-hosted** when owning
-the OpenAI-compatible provider, AI route, and persistence is a requirement.
+Run the command with the self-hosted template to connect your own OpenAI-compatible provider:
```bash tab="pnpm" tab-group="pkg"
-pnpx @openuidev/cli@latest create
+pnpx @openuidev/cli@latest create --template openui-self-hosted
```
```bash tab="bun" tab-group="pkg"
-bunx @openuidev/cli@latest create
+bunx @openuidev/cli@latest create --template openui-self-hosted
```
```bash tab="yarn" tab-group="pkg"
-yarn dlx @openuidev/cli@latest create
+yarn dlx @openuidev/cli@latest create --template openui-self-hosted
```
```bash tab="npm" tab-group="pkg"
-npx @openuidev/cli@latest create
+npx @openuidev/cli@latest create --template openui-self-hosted
```
-When it finishes, move into the project:
+## 2. Configure your provider key
-```bash
-cd my-agent
-```
-
-## 2. Connect
-
-<Tabs groupId="deploy" items={["OpenUI Cloud", "Self-hosted"]} persist>
- <Tab value="OpenUI Cloud">
-
-The CLI will prompt you to sign in to Thesys and create an API key in your browser, or you can generate your own on the [Thesys console](https://console.thesys.dev/keys) and add it to `.env`:
-
-```bash
-THESYS_API_KEY=sk-th-your-key-here
-```
-
-The scaffold's `/api/chat` route proxies to Cloud with this key, so it stays on the server. Cloud manages conversation history, artifacts, and built-in tools, so there's no database or renderers to run. See [OpenUI Cloud](/docs/agent/getting-started/openui-cloud).
-
- </Tab>
- <Tab value="Self-hosted">
-
-The scaffold generates an `/api/chat` route that calls OpenAI on the server. Add your key to `.env.local`:
+Enter your provider key when prompted, or add it to the generated environment file:
```bash
OPENAI_API_KEY=sk-your-key-here
```
-The key stays on the server. The browser only ever talks to your route, never the provider.
-
- </Tab>
-</Tabs>
+The key stays in the generated server route. Browser code calls your application and never receives this server credential.
## 3. Run
-Start the dev server:
-
```bash tab="pnpm" tab-group="pkg"
pnpm dev
```
-```bash tab="bun" tab-group="pkg"
-bun dev
-```
-
-```bash tab="yarn" tab-group="pkg"
-yarn dev
-```
-
```bash tab="npm" tab-group="pkg"
npm run dev
```
-Open [http://localhost:3000](http://localhost:3000) and send a message. The response streams in token by token, and the assistant can render rich, interactive components inline.
-
-<video
- src="/videos/agent/quickstart-inline-generative-ui.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-## What you get
-
-A working agent out of the box:
+Open [http://localhost:3000](http://localhost:3000) and request an interface such as a comparison table or interactive form.
-- **Streaming chat:** responses render token by token in a full layout (sidebar, thread list, composer).
-- **Conversation history that persists:** past threads are saved and reloadable, not reset on refresh. See [Conversations](/docs/agent/core-concepts/conversations).
-- **Tool calling:** the agent can call tools mid-response, including built-in Cloud tools like `image_search` (no code to enable). See [Tools](/docs/agent/core-concepts/tools).
-- **An example artifact:** the scaffold ships a slides/report artifact you can prompt for and open in the workspace. See [Artifacts](/docs/agent/core-concepts/artifacts).
-- **Generative UI, on by default:** the assistant renders interactive components inside messages. See [Generative UI](/docs/agent/core-concepts/generative-ui).
+## What to read next
-The difference is only in the backing: **OpenUI Cloud** manages history, artifacts, and built-in tools for you, while **self-hosted** uses your own OpenAI route and a local store the scaffold generates.
+- [Adapters and formats](/docs/agent/reference/adapters-and-formats)
+- [Generative UI](/docs/agent/core-concepts/generative-ui)
+- [Customize Agent Interface](/docs/agent/customize/welcome-and-starters)
+- [`AgentInterface` props](/docs/agent/reference/agentinterface-props)
diff --git a/docs/content/docs/agent/guides/custom-artifacts.mdx b/docs/content/docs/agent/guides/custom-artifacts.mdx
index 0fa7a993b..245bb7d75 100644
--- a/docs/content/docs/agent/guides/custom-artifacts.mdx
+++ b/docs/content/docs/agent/guides/custom-artifacts.mdx
@@ -1,17 +1,15 @@
---
title: Custom artifacts
-description: "Add a custom artifact type beyond Cloud's built-in slides and reports: produce the data, write a renderer, register it."
+description: "Add a custom artifact type: produce the data, write a renderer, and register it."
---
-OpenUI Cloud ships built-in artifact types (slides, reports) already wired to render. When your agent produces something they don't cover, like a code snippet or a custom app, you add your own type: a tool returns the data, a renderer turns it into UI, and the `artifactRenderers` prop registers it. The same renderer draws the artifact whether it just streamed in or was loaded from storage.
+When your agent produces a first-class output such as a code snippet or a custom app, you add an artifact type: a tool returns the data, a renderer turns it into UI, and the `artifactRenderers` prop registers it. The same renderer draws the artifact whether it just streamed in or was loaded from storage.
This guide builds one custom artifact end to end: a code snippet the agent generates. For the concept, see [Artifacts](/docs/agent/core-concepts/artifacts). For every renderer field and edge case, see [defineArtifactRenderer](/docs/agent/reference/define-artifact-renderer).
## 1. Produce the artifact
-An artifact reaches the UI as the result of a [tool call](/docs/agent/core-concepts/tools). Your agent calls a `create_code_artifact` tool, and its arguments are the artifact's data. The renderer below matches that tool by name and draws the result, the same way on OpenUI Cloud or your own backend.
-
-Keep that shape identical to whatever you persist, so one renderer covers both the freshly-streamed and the loaded-from-storage cases. For this example the data is:
+An artifact reaches the UI as the result of a tool call. Your agent calls a `create_code_artifact` tool, and its arguments are the artifact's data.
```ts
interface CodeArtifact {
@@ -23,9 +21,9 @@ interface CodeArtifact {
## 2. Write the renderer
-A renderer is keyed to an artifact `type`, not to a tool. A tool call is just one way the data arrives. You describe it with `defineArtifactRenderer`: a `parser` that reads the raw envelope into typed props, a `preview` (the inline card in the chat), and an `actual` (the full view in a side panel or page).
+A renderer is keyed to an artifact `type`, not to a tool. Describe it with `defineArtifactRenderer`: a `parser` that reads the raw envelope into typed props, a `preview` for the inline chat card, and an `actual` view for the side panel or page.
-The rule that matters most: the `parser` must never throw. It runs on every stream update, including before the result exists, so read `response` as the source of truth, fall back to a tolerant parse of `args` for an early preview, and bail with `null` until you have enough to draw.
+The `parser` must never throw. It runs on every stream update, including before the result exists, so read `response` as the source of truth, fall back to a tolerant parse of `args` for an early preview, and return `null` until there is enough to draw.
```tsx
import { defineArtifactRenderer, CodeBlock } from "@openuidev/react-ui";
@@ -35,15 +33,11 @@ const codeArtifactRenderer = defineArtifactRenderer({
toolName: "create_code_artifact",
parser: ({ args, response }, { isStreaming }) => {
- // Storage path: args is undefined, response is the persisted content.
- // Tool-call path: response is null until the result lands; args streams
- // in first as a partial JSON string.
const data = (response as CodeArtifact | null) ?? tryParse(args);
- if (!data?.title) return null; // not enough to draw yet
+ if (!data?.title) return null;
return {
props: data,
- // Don't register in the workspace until the result is final.
meta: isStreaming
? null
: { id: `code:${data.title}`, version: 1, heading: data.title },
@@ -51,14 +45,9 @@ const codeArtifactRenderer = defineArtifactRenderer({
},
preview: (props, controls) => (
- <button
- type="button"
- onClick={controls.open}
- data-active={controls.isActive}
- className="code-card"
- >
- <span className="code-card__title">{props.title}</span>
- <span className="code-card__lang">
+ <button type="button" onClick={controls.open} data-active={controls.isActive}>
+ <span>{props.title}</span>
+ <span>
{props.language}
{controls.isStreaming ? " · building…" : ""}
</span>
@@ -66,32 +55,23 @@ const codeArtifactRenderer = defineArtifactRenderer({
),
actual: (props) => (
- <div className="code-artifact">
- <CodeBlock language={props.language || "text"} codeString={props.code} />
- </div>
+ <CodeBlock language={props.language || "text"} codeString={props.code} />
),
});
-// Best-effort parse of a possibly-partial JSON arg string.
function tryParse(args: unknown): CodeArtifact | null {
if (typeof args !== "string") return null;
try {
return JSON.parse(args) as CodeArtifact;
} catch {
- return null; // still mid-stream
+ return null;
}
}
```
-A few things to notice:
-
-- **`preview` vs `actual`:** `preview` is the compact card inline in the message; keep it small and give it an affordance that calls `controls.open()`. `actual` is the full view in the detailed-view panel or the artifact page. Here it uses the built-in `CodeBlock` component.
-- **`meta`:** return `meta: null` while streaming so the artifact joins the workspace only once complete; return `{ id, version, heading }` on the final pass to register it. Keep `id` stable across re-runs of the same artifact.
-- **`controls.isStreaming`:** the same component instance is reused across the streaming-to-complete transition, so this is a state swap, not a remount.
-
## 3. Register it
-Hand your renderer to `<AgentInterface>` through the `artifactRenderers` prop. Pass as many as you like:
+Pass the renderer to `<AgentInterface>` through the `artifactRenderers` prop:
```tsx
import { AgentInterface } from "@openuidev/react-ui";
@@ -99,4 +79,4 @@ import { AgentInterface } from "@openuidev/react-ui";
<AgentInterface llm={llm} artifactRenderers={[codeArtifactRenderer]} />;
```
-The interface indexes each renderer by `toolName` (the tool-call path) and by `type` (the storage path), so a `create_code_artifact` call renders as an inline card that opens a full panel, and any `code_artifact` loaded from storage renders through the same code. On a duplicate `toolName` or `type`, the first registration wins, so put your custom renderers before any built-in defaults.
+The interface indexes each renderer by `toolName` for streamed tool calls and by `type` for stored artifacts. If registrations duplicate a `toolName` or `type`, the first one wins.
diff --git a/docs/content/docs/agent/guides/migrating.mdx b/docs/content/docs/agent/guides/migrating.mdx
deleted file mode 100644
index 4c8f7f59e..000000000
--- a/docs/content/docs/agent/guides/migrating.mdx
+++ /dev/null
@@ -1,225 +0,0 @@
----
-title: Migrating from flat-props ChatProvider
-description: Move from the legacy flat-props chat component to AgentInterface and its two adapter objects — with a complete old-to-new mapping and the behavior changes to watch for.
----
-
-The legacy chat component took its backend wiring as a flat bag of props — `apiUrl`, `streamProtocol`, `processMessage`, `threadApiUrl`, `fetchThreadList`, `loadThread`, and a dozen more — directly on the component. `AgentInterface` replaces all of that with **two adapter objects**: an `llm` for producing replies and a `storage` for persistence. The component's prop surface shrinks to something small and stable, and each adapter is testable in isolation — you can unit-test a `ChatLLM` or `ChatStorage` without rendering anything.
-
-The whole migration, in one idea: the flat backend props are **removed** (not deprecated), and their values move into `fetchLLM({ ... })` for the LLM and `restStorage({ ... })` for threads.
-
-<Callout type="info">Everything imports from `@openuidev/react-ui`: `AgentInterface`, the `fetchLLM` / `restStorage` / `defineArtifactRenderer` factories, the stream adapters, the message formats, and hooks like `useArtifactList`.</Callout>
-
-## The whole diff
-
-If you were on the common setup — POST to a route, REST-backed threads — the migration is: build two adapters, pass two props.
-
-**Before:**
-
-```tsx
-// legacy flat-props chat component
-<LegacyChat
- apiUrl="/api/chat"
- streamProtocol="openai"
- messageFormat="openai"
- threadApiUrl="/api/threads"
-/>;
-```
-
-**After:**
-
-```tsx
-import { AgentInterface, fetchLLM, restStorage, openAIAdapter, openAIMessageFormat } from "@openuidev/react-ui";
-
-const llm = fetchLLM({
- url: "/api/chat",
- streamAdapter: openAIAdapter(),
- messageFormat: openAIMessageFormat,
-});
-
-const storage = restStorage({
- baseUrl: "/api/threads",
- messageFormat: openAIMessageFormat,
-});
-
-<AgentInterface llm={llm} storage={storage} />;
-```
-
-Your route handler doesn't change: `fetchLLM` POSTs the same `{ threadId, messages }` to `url`, and `restStorage` calls the same thread endpoints `threadApiUrl` did. Everything else on this page is the field-by-field mapping behind those two factory calls.
-
-## Old → new at a glance
-
-| Legacy flat prop | New home | Notes |
-|------------------|----------|-------|
-| `apiUrl` | `fetchLLM({ url })` | The LLM endpoint moves into the factory's `url`. |
-| `streamProtocol` | `fetchLLM({ streamAdapter })` | String enum → a stream-adapter **factory call** (`openAIAdapter()`). |
-| `messageFormat` | `fetchLLM({ messageFormat })` *(and `restStorage({ messageFormat })`)* | String enum → a `MessageFormat` value (`openAIMessageFormat`). |
-| `processMessage` | `ChatLLM.send` | Custom send logic becomes a `send` implementation. `abortController` → the `signal` you receive. |
-| `threadApiUrl` | `restStorage({ baseUrl })` | The thread REST root moves into `restStorage`. |
-| `fetchThreadList` | `storage.thread.listThreads` | Now takes an optional cursor; returns `{ threads, nextCursor? }`. |
-| `createThread` | `storage.thread.createThread` | Receives the first `UserMessage`, returns the new `Thread`. |
-| `updateThread` | `storage.thread.updateThread` | Takes a full `Thread`, returns the updated `Thread`. |
-| `deleteThread` | `storage.thread.deleteThread` | Takes an id. |
-| `loadThread` | `storage.thread.getMessages` | Renamed; takes a `threadId`, returns `Message[]`. |
-| `appRenderers` | `artifactRenderers` | Prop rename; array of renderer configs. |
-| `defineAppRenderer` | `defineArtifactRenderer` | `kind` → `type`; `toolName` is `string \| string[]`; parser returns `{ props, meta }`. |
-| `useAppList` | `useArtifactList` | Hook rename; per-thread artifact registry. |
-| `Artifact*` panel APIs | `DetailedView*` | The in-thread panel hooks were renamed around "detailed view." |
-| legacy chat component | `AgentInterface` | Component rename, same package. |
-
-## LLM props → `llm`
-
-Four old props collapse into one `fetchLLM` call. Two things change beyond the renames:
-
-- **`streamProtocol` was a string; `streamAdapter` is a factory call.** Pick the adapter matching your provider's wire format and **call it** — `openAIAdapter()`, not the bare reference. The options are `agUIAdapter`, `openAIAdapter`, `openAIReadableStreamAdapter`, `openAIResponsesAdapter`, and `langGraphAdapter`.
-- **`messageFormat` was a string; it's now a value.** Use `openAIMessageFormat`, `openAIConversationMessageFormat` (the one that pairs with `openAIResponsesAdapter()`), `langGraphMessageFormat`, or `identityMessageFormat` (the default — the canonical `Message` array, unchanged).
-
-### `processMessage` → a custom `ChatLLM`
-
-If `processMessage` did something `fetchLLM` can't express — a non-`fetch` transport, a websocket, bespoke request shaping — implement the `ChatLLM` interface directly instead of calling `fetchLLM`.
-
-**Before** — `processMessage` received an `abortController`:
-
-```tsx
-<LegacyChat
- streamProtocol="openai"
- processMessage={async (messages, { abortController }) => {
- return fetch("/api/chat", {
- method: "POST",
- body: JSON.stringify({ messages }),
- signal: abortController.signal,
- });
- }}
-/>;
-```
-
-**After** — `send` receives the `signal` directly, and the parser moves onto the object as `streamProtocol`:
-
-```tsx
-import { AgentInterface, type ChatLLM, openAIAdapter } from "@openuidev/react-ui";
-
-const llm: ChatLLM = {
- streamProtocol: openAIAdapter(),
- async send({ threadId, messages, signal }) {
- return fetch("/api/chat", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({ threadId, messages }),
- signal, // was abortController.signal
- });
- },
-};
-
-<AgentInterface llm={llm} />;
-```
-
-The behavior change to internalize: **you no longer create or own an `AbortController`.** `AgentInterface` owns it and hands you the `signal` — wired to the UI's stop control — in every `send` call. Just forward it.
-
-## Thread props → `storage`
-
-`threadApiUrl` plus the per-operation callbacks become a single `ChatStorage` whose `thread` member holds five methods.
-
-### The REST case → `restStorage`
-
-If your old setup pointed `threadApiUrl` at a REST backend, the migration is one factory call:
-
-```tsx
-import { restStorage } from "@openuidev/react-ui";
-
-const storage = restStorage({ baseUrl: "/api/threads" }); // was threadApiUrl
-
-<AgentInterface llm={llm} storage={storage} />;
-```
-
-`restStorage` hits the exact endpoints the old `threadApiUrl` prop did — `GET {baseUrl}/get`, `POST {baseUrl}/create`, `GET {baseUrl}/get/{threadId}`, `PATCH {baseUrl}/update/{id}`, `DELETE {baseUrl}/delete/{id}` — so an existing backend keeps working. Pass `messageFormat` here too if your backend stores messages in a provider shape.
-
-<Callout type="info">If you pass no `storage` at all, `AgentInterface` uses an internal in-memory store — fine for prototyping, but wiped on reload.</Callout>
-
-### Custom thread callbacks → `storage.thread.*`
-
-If you supplied individual thread callbacks, each maps to a method on `storage.thread`:
-
-```tsx
-import { AgentInterface, type ChatStorage } from "@openuidev/react-ui";
-
-const storage: ChatStorage = {
- thread: {
- listThreads: fetchThreadList, // now takes an optional cursor, returns { threads, nextCursor? }
- createThread, // receives the first UserMessage, returns the new Thread
- getMessages: loadThread, // was loadThread — takes threadId, returns Message[]
- updateThread, // takes a full Thread, returns the updated Thread
- deleteThread, // takes an id
- },
-};
-
-<AgentInterface llm={llm} storage={storage} />;
-```
-
-Two renames carry behavior changes: **`fetchThreadList` → `listThreads`** now takes an optional `cursor` and must return `{ threads, nextCursor? }` (cursor pagination for the sidebar's "load more"); **`loadThread` → `getMessages`** is the same job, just renamed for symmetry. If your callbacks already match these shapes, hand them over directly; otherwise wrap them.
-
-## Renderers: `appRenderers` → `artifactRenderers`
-
-The "app renderer" concept was renamed to **artifact renderer** throughout — the prop, the factory, and the parser contract all changed.
-
-```tsx
-import { AgentInterface, defineArtifactRenderer } from "@openuidev/react-ui";
-
-const codeArtifactRenderer = defineArtifactRenderer({
- type: "code_artifact", // was kind
- toolName: "create_code_artifact", // now string | string[]
- parser: ({ args, response }, { isStreaming }) => {
- const data = response as CodeArtifact | null;
- if (!data) return null; // tolerate partial data while streaming
- return {
- props: data, // props AND meta now come from one return value
- meta: isStreaming ? null : { id: `code:${data.title}`, version: 1, heading: data.title },
- };
- },
- preview: (props, controls) => <CodeCard {...props} onOpen={controls.open} />,
- actual: (props) => <CodeBlock language={props.language} codeString={props.code} />,
-});
-
-<AgentInterface llm={llm} artifactRenderers={[codeArtifactRenderer]} />;
-```
-
-The behavior changes inside the renderer:
-
-- **`kind` → `type`.** A literal string that links the renderer to its stored artifacts' `type`.
-- **`toolName` is now `string | string[]`.** Register one renderer for several tools by passing an array. Names are **literal only** — no RegExp. First registration wins on a duplicate `toolName`.
-- **The parser returns `{ props, meta }` (or `null`), not props alone.** `meta` is `{ id, version, heading } | null`: return the object to render *and* register the artifact in the thread (so it appears in the Workspace rail and artifact lists); return `null` for `meta` to render without registering (the common move while streaming). Returning `null` from the parser entirely skips rendering.
-- **The parser must tolerate partial data.** It's called on every stream update — `response` is `null` until the result lands, and `args` may be a partial JSON string. Guard accordingly.
-
-## Hooks and panel APIs
-
-`useAppList()` → **`useArtifactList(filter?)`**, imported from `@openuidev/react-ui`. It returns the per-thread artifact registry, optionally filtered by `type`:
-
-```tsx
-import { useArtifactList } from "@openuidev/react-ui";
-
-const artifacts = useArtifactList();
-const codeArtifacts = useArtifactList({ type: ["code_artifact"] });
-```
-
-The in-thread panel hooks that used to be named around "Artifact" are now named around **detailed view**: `useActiveDetailedView()`, `useDetailedView(viewId)`, `useDetailedViewStore()`, `useDetailedViewPortalTarget()`. If you reached into the old `Artifact*` panel hooks, swap to these.
-
-<Callout type="info">"Artifact" now consistently means the durable output (a dashboard, report, app); "detailed view" means the in-thread panel that shows one. The old "app" / "Artifact panel" naming conflated the two.</Callout>
-
-## Migration checklist
-
-1. Rename the legacy chat component → `AgentInterface` (same `@openuidev/react-ui` package).
-2. Build `llm = fetchLLM({ url, streamAdapter, messageFormat })` from your old `apiUrl` / `streamProtocol` / `messageFormat`. **Call** the adapter (`openAIAdapter()`).
-3. If you had a custom `processMessage`, implement `ChatLLM` directly and forward the `signal` — drop your own `AbortController`.
-4. Build `storage = restStorage({ baseUrl })` from `threadApiUrl`, **or** assemble `storage.thread.*` from your `fetchThreadList` (→ `listThreads`), `createThread`, `updateThread`, `deleteThread`, and `loadThread` (→ `getMessages`).
-5. Pass `llm` (required) and `storage` (optional) to `AgentInterface`.
-6. Rename `appRenderers` → `artifactRenderers` and `defineAppRenderer` → `defineArtifactRenderer`; change `kind` → `type`, allow `toolName` arrays, and return `{ props, meta }` from each parser.
-7. Rename `useAppList` → `useArtifactList` and any `Artifact*` panel hooks → `DetailedView*`.
-8. Delete every remaining flat backend prop — they're gone. If TypeScript flags an unknown prop, find it in the table above and move it into the right adapter.
-
-## Related
-
-<Cards>
- <Card title="AgentInterface props" href="/docs/agent/reference/agentinterface-props">The presentation props that stay flat on the component.</Card>
- <Card title="Adapters & formats" href="/docs/agent/reference/adapters-and-formats">Reference for `fetchLLM`, `restStorage`, stream adapters, and message formats.</Card>
- <Card title="defineArtifactRenderer" href="/docs/agent/reference/define-artifact-renderer">The renderer config, parser contract, and `meta` shape.</Card>
- <Card title="Conversations" href="/docs/agent/core-concepts/conversations">How `llm` and `storage` drive a thread end to end.</Card>
- <Card title="Hooks" href="/docs/agent/reference/hooks">`useArtifactList`, the `DetailedView*` hooks, and more.</Card>
-</Cards>
diff --git a/docs/content/docs/agent/meta.json b/docs/content/docs/agent/meta.json
index 4b60ec4f5..b26f12262 100644
--- a/docs/content/docs/agent/meta.json
+++ b/docs/content/docs/agent/meta.json
@@ -1,30 +1,31 @@
{
"title": "Agent Interface",
- "root": true,
"pages": [
"---Getting Started---",
"getting-started/introduction",
"getting-started/quickstart",
- "getting-started/openui-cloud",
"---Core Concepts---",
"core-concepts/generative-ui",
"core-concepts/conversations",
- "core-concepts/tools",
"core-concepts/artifacts",
"---Customize---",
"customize/welcome-and-starters",
"customize/sidebar",
"customize/message-rendering",
+ "---Guides---",
+ "guides/open-ended-html",
+ "guides/custom-artifacts",
"---Reference---",
"reference/agentinterface-props",
+ "reference/components",
+ "reference/hooks",
"reference/adapters-and-formats",
"reference/define-artifact-renderer",
- "reference/hooks",
- "reference/components",
"reference/self-hosting",
- "---Guides---",
- "guides/open-ended-html",
- "guides/custom-artifacts",
- "guides/migrating"
+ "---Examples---",
+ "agent-runtimes/vercel-ai-sdk",
+ "agent-runtimes/langgraph-platform",
+ "agent-runtimes/pi",
+ "agent-runtimes/vercel-eve"
]
}
diff --git a/docs/content/docs/agent/reference/adapters-and-formats.mdx b/docs/content/docs/agent/reference/adapters-and-formats.mdx
index 6ac55f745..9d80a3c81 100644
--- a/docs/content/docs/agent/reference/adapters-and-formats.mdx
+++ b/docs/content/docs/agent/reference/adapters-and-formats.mdx
@@ -3,12 +3,12 @@ title: Adapters & formats
description: Complete reference for AgentInterface's backend channels — the ChatLLM/ChatStorage/ThreadStorage/ArtifactStorage interfaces, the fetchLLM and restStorage factories, the Thread type, the bundled stream adapters, and the message formats.
---
-`AgentInterface` talks to your backend through two independent channels, each an *adapter* you supply:
+`AgentInterface` talks to your backend through two independent channels, each an _adapter_ you supply:
- **`llm`** — a `ChatLLM` that produces replies. **Required.**
- **`storage`** — a `ChatStorage` that persists threads, messages, and (optionally) artifacts. Optional; defaults to an internal in-memory store that's wiped on reload.
-This page is the exhaustive reference for both channels, the factories that build them (`fetchLLM`, `restStorage`), the `Thread` record, the bundled **stream adapters** that parse provider wire formats, and the **message formats** that translate message shapes. For the task-oriented walkthroughs, see [Conversations](/docs/agent/core-concepts/conversations) and [Self-hosting](/docs/agent/reference/self-hosting).
+This page is the exhaustive reference for both channels, the factories that build them (`fetchLLM`, `restStorage`), the `Thread` record, the bundled **stream adapters** that parse provider wire formats, and the **message formats** that translate message shapes. For the task-oriented walkthrough, see [Conversations](/docs/agent/core-concepts/conversations).
## Import sources
@@ -44,7 +44,10 @@ import {
} from "@openuidev/react-ui";
```
-<Callout type="warn">All six stream adapters are **factory functions** — always call them with `()`. `streamAdapter: openAIAdapter()` is correct; a bare `streamAdapter: openAIAdapter` is wrong.</Callout>
+<Callout type="warn">
+ All six stream adapters are **factory functions** — always call them with `()`. `streamAdapter:
+ openAIAdapter()` is correct; a bare `streamAdapter: openAIAdapter` is wrong.
+</Callout>
## The two channels
@@ -52,7 +55,7 @@ import {
import { AgentInterface } from "@openuidev/react-ui";
<AgentInterface
- llm={chatLLM} // required — ChatLLM
+ llm={chatLLM} // required — ChatLLM
storage={chatStorage} // optional — ChatStorage
/>;
```
@@ -67,11 +70,7 @@ The object `AgentInterface` calls when the user sends a message.
```ts
interface ChatLLM {
- send(params: {
- threadId: string;
- messages: Message[];
- signal: AbortSignal;
- }): Promise<Response>;
+ send(params: { threadId: string; messages: Message[]; signal: AbortSignal }): Promise<Response>;
streamProtocol: StreamProtocolAdapter;
}
```
@@ -96,14 +95,14 @@ function fetchLLM(options: {
}): ChatLLM;
```
-| Option | Type | Required | What it does |
-|-----------------|----------------------------|----------|-----------------------------------------------------------------------------------------|
-| `url` | `string` | Yes | The endpoint `fetchLLM` POSTs to (your own route — never the provider directly). |
-| `streamAdapter` | `StreamProtocolAdapter` | Yes | Parses the streamed response into UI events. Becomes the `ChatLLM`'s `streamProtocol`. |
-| `messageFormat` | `MessageFormat` | No | Converts outgoing `messages` to your provider's shape. Defaults to `identityMessageFormat`. |
-| `headers` | `Record<string, string>` | No | Extra headers merged into every request (e.g. a session token). **Browser-visible.** |
-| `fetch` | `typeof fetch` | No | Override `fetch` (auth wrappers, instrumentation, tests). |
-| `body` | `Record<string, unknown>` | No | Extra fields merged into the request body (e.g. `model`) |
+| Option | Type | Required | What it does |
+| --------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `url` | `string` | Yes | The endpoint `fetchLLM` POSTs to (your own route — never the provider directly). |
+| `streamAdapter` | `StreamProtocolAdapter` | Yes | Parses the streamed response into UI events. Becomes the `ChatLLM`'s `streamProtocol`. |
+| `messageFormat` | `MessageFormat` | No | Converts outgoing `messages` to your provider's shape. Defaults to `identityMessageFormat`. |
+| `headers` | `Record<string, string>` | No | Extra headers merged into every request (e.g. a session token). **Browser-visible.** |
+| `fetch` | `typeof fetch` | No | Override `fetch` (auth wrappers, instrumentation, tests). |
+| `body` | `Record<string, unknown>` | No | Extra fields merged into the request body (e.g. `model`) |
**Request body.** `fetchLLM` POSTs JSON `{ threadId, messages }`, where `messages` is run through `messageFormat.toApi`, and threads the `AbortSignal` from the UI:
@@ -136,7 +135,11 @@ const llm = fetchLLM({
});
```
-<Callout type="warn">`headers` are headers on the browser's request to *your* route. Use them for things like a session token or CSRF token — never a provider API key. The provider key lives only in your server-side route handler.</Callout>
+<Callout type="warn">
+ `headers` are headers on the browser's request to *your* route. Use them for things like a session
+ token or CSRF token — never a provider API key. The provider key lives only in your server-side
+ route handler.
+</Callout>
---
@@ -152,7 +155,7 @@ interface ChatStorage {
```
- **`thread`** persists conversations — the thread list, message history, renames, and deletes.
-- **`artifact`** persists durable artifacts (dashboards, reports, presentations, apps) and powers the artifact browser. Optional and independent of `thread`. See [`ArtifactStorage`](#artifactstorage-optional) below and [Artifacts](/docs/agent/core-concepts/artifacts).
+- **`artifact`** persists durable artifacts such as dashboards, data explorers, and apps, and powers the artifact browser. It is optional and independent of `thread`. See [`ArtifactStorage`](#artifactstorage-optional) below.
Omit `storage` entirely and `AgentInterface` uses an internal in-memory store — fine for prototyping, but ephemeral.
@@ -170,13 +173,13 @@ interface ThreadStorage {
}
```
-| Method | Returns | When `AgentInterface` calls it |
-|--------|---------|--------------------------------|
-| `listThreads(cursor?)` | `{ threads, nextCursor? }` | Populating the thread list; loading more when `nextCursor` exists and the user scrolls. |
-| `createThread(firstMessage)` | the new `Thread` | The user sends the first message of a new chat. |
-| `getMessages(threadId)` | `Message[]` | The user opens a thread. |
-| `updateThread(thread)` | the updated `Thread` | A thread changes (e.g. a rename). |
-| `deleteThread(id)` | `void` | The user deletes a thread. |
+| Method | Returns | When `AgentInterface` calls it |
+| ---------------------------- | -------------------------- | --------------------------------------------------------------------------------------- |
+| `listThreads(cursor?)` | `{ threads, nextCursor? }` | Populating the thread list; loading more when `nextCursor` exists and the user scrolls. |
+| `createThread(firstMessage)` | the new `Thread` | The user sends the first message of a new chat. |
+| `getMessages(threadId)` | `Message[]` | The user opens a thread. |
+| `updateThread(thread)` | the updated `Thread` | A thread changes (e.g. a rename). |
+| `deleteThread(id)` | `void` | The user deletes a thread. |
Implement these directly when your storage doesn't fit the REST shape `restStorage` expects — a different route layout, GraphQL, or a client-side store like IndexedDB:
@@ -229,11 +232,11 @@ type Thread = {
};
```
-| Field | Type | Notes |
-|-------|------|-------|
-| `id` | `string` | Stable thread identifier. |
-| `title` | `string` | Shown in the sidebar thread list. |
-| `createdAt` | `string \| number` | ISO string or epoch — used for ordering/display. |
+| Field | Type | Notes |
+| ----------- | -------------------- | --------------------------------------------------------------------------------------------- |
+| `id` | `string` | Stable thread identifier. |
+| `title` | `string` | Shown in the sidebar thread list. |
+| `createdAt` | `string \| number` | ISO string or epoch — used for ordering/display. |
| `isPending` | `boolean` (optional) | Marks a thread that's being created (e.g. optimistic insert before the create call resolves). |
---
@@ -251,12 +254,12 @@ function restStorage(options: {
}): ChatStorage;
```
-| Option | Type | Required | What it does |
-|-----------------|----------------------------|----------|-------------------------------------------------------------------------------------------|
-| `baseUrl` | `string` | Yes | Root path for the endpoints below (e.g. `/api/threads`). |
-| `messageFormat` | `MessageFormat` | No | Converts messages to/from your stored shape. Defaults to `identityMessageFormat`. |
-| `headers` | `Record<string, string>` | No | Sent on every request (e.g. a tenant or session header). |
-| `fetch` | `typeof fetch` | No | Override `fetch` (auth, instrumentation, tests). |
+| Option | Type | Required | What it does |
+| --------------- | ------------------------ | -------- | --------------------------------------------------------------------------------- |
+| `baseUrl` | `string` | Yes | Root path for the endpoints below (e.g. `/api/threads`). |
+| `messageFormat` | `MessageFormat` | No | Converts messages to/from your stored shape. Defaults to `identityMessageFormat`. |
+| `headers` | `Record<string, string>` | No | Sent on every request (e.g. a tenant or session header). |
+| `fetch` | `typeof fetch` | No | Override `fetch` (auth, instrumentation, tests). |
```tsx
import { restStorage, openAIMessageFormat } from "@openuidev/react-ui";
@@ -264,7 +267,7 @@ import { restStorage, openAIMessageFormat } from "@openuidev/react-ui";
const storage = restStorage({
baseUrl: "/api/threads",
messageFormat: openAIMessageFormat, // optional
- headers: { "x-tenant": "acme" }, // optional, sent on every request
+ headers: { "x-tenant": "acme" }, // optional, sent on every request
});
```
@@ -272,13 +275,13 @@ const storage = restStorage({
Each `ThreadStorage` operation maps to exactly one HTTP call under `baseUrl`. The paths are literal — these are the exact five endpoints you implement.
-| Operation | Method | Path | Request body | Response |
-|-----------|--------|------|--------------|----------|
-| List threads | `GET` | `{baseUrl}/get` — or `{baseUrl}/get?cursor={cursor}` when paginating | — | `{ threads: Thread[]; nextCursor?: string }` |
-| Create thread | `POST` | `{baseUrl}/create` | `{ messages: messageFormat.toApi([firstMessage]) }` | the new `Thread` |
-| Get messages | `GET` | `{baseUrl}/get/{threadId}` | — | `Message[]` (run through `messageFormat.fromApi`) |
-| Update thread | `PATCH` | `{baseUrl}/update/{thread.id}` | the `Thread` | the updated `Thread` |
-| Delete thread | `DELETE` | `{baseUrl}/delete/{id}` | — | — |
+| Operation | Method | Path | Request body | Response |
+| ------------- | -------- | -------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------- |
+| List threads | `GET` | `{baseUrl}/get` — or `{baseUrl}/get?cursor={cursor}` when paginating | — | `{ threads: Thread[]; nextCursor?: string }` |
+| Create thread | `POST` | `{baseUrl}/create` | `{ messages: messageFormat.toApi([firstMessage]) }` | the new `Thread` |
+| Get messages | `GET` | `{baseUrl}/get/{threadId}` | — | `Message[]` (run through `messageFormat.fromApi`) |
+| Update thread | `PATCH` | `{baseUrl}/update/{thread.id}` | the `Thread` | the updated `Thread` |
+| Delete thread | `DELETE` | `{baseUrl}/delete/{id}` | — | — |
With `baseUrl: "/api/threads"` the concrete paths are `/api/threads/get`, `/api/threads/create`, `/api/threads/get/{threadId}`, `/api/threads/update/{thread.id}`, and `/api/threads/delete/{id}`.
@@ -299,7 +302,7 @@ With the default `identityMessageFormat`, messages cross the wire as the canonic
## `ArtifactStorage` (optional)
-The optional `artifact` member of `ChatStorage`. Configure it to store durable artifacts and enable the artifact browser. Summarized here for completeness — the task-oriented coverage is in [Artifacts](/docs/agent/core-concepts/artifacts).
+The optional `artifact` member of `ChatStorage`. Configure it to store durable artifacts and enable the artifact browser.
```ts
interface ArtifactStorage {
@@ -317,7 +320,7 @@ interface ArtifactSummary {
id: string;
title: string;
type: string;
- threadId: string; // required — every artifact belongs to a thread
+ threadId: string; // required — every artifact belongs to a thread
updatedAt?: string | number;
}
@@ -343,7 +346,7 @@ const storage: ChatStorage = {
## Stream adapters
-A **stream adapter** parses the streamed `Response` your route returns into the AG-UI events the UI renders. There is one per response *wire format*. It's a factory returning a `StreamProtocolAdapter`:
+A **stream adapter** parses the streamed `Response` your route returns into the AG-UI events the UI renders. There is one per response _wire format_. It's a factory returning a `StreamProtocolAdapter`:
```ts
interface StreamProtocolAdapter {
@@ -353,22 +356,27 @@ interface StreamProtocolAdapter {
`fetchLLM` calls `parse` on the `Response` your route returns and consumes the yielded AG-UI events. All six bundled adapters are factories you call to get an instance — `agUIAdapter()`, `openAIAdapter()`, `openAIReadableStreamAdapter()`, `openAIResponsesAdapter()`, `vercelAIAdapter()`, `langGraphAdapter()`; only `langGraphAdapter()` accepts options.
-<Callout type="info">The line-oriented adapters log and skip malformed lines. `vercelAIAdapter()` delegates validation to the Vercel AI SDK and rejects invalid UIMessage chunks. Provider-level failures should be surfaced as a `RUN_ERROR` event (the OpenAI Responses, Vercel AI SDK, and LangGraph adapters do this for their error events).</Callout>
+<Callout type="info">
+ The line-oriented adapters log and skip malformed lines. `vercelAIAdapter()` delegates validation
+ to the Vercel AI SDK and rejects invalid UIMessage chunks. Provider-level failures should be
+ surfaced as a `RUN_ERROR` event (the OpenAI Responses, Vercel AI SDK, and LangGraph adapters do
+ this for their error events).
+</Callout>
### Selection guide
-Start from your provider and how the route streams its reply. The stream adapter and message format are independent knobs — pick the adapter to match how your backend *streams*, and the format to match how it represents *stored* messages — but they typically pair up as below.
+Start from your provider and how the route streams its reply. The stream adapter and message format are independent knobs — pick the adapter to match how your backend _streams_, and the format to match how it represents _stored_ messages — but they typically pair up as below.
-| Your backend streams… | Stream adapter | Pair with message format |
-|------------------------------------------------------------------------|---------------------------------|--------------------------------------|
-| OpenAI **Chat Completions** SSE (`data: {…}` lines) | `openAIAdapter()` | `openAIMessageFormat` |
-| OpenAI SDK `stream.toReadableStream()` (NDJSON, no `data:` prefix) | `openAIReadableStreamAdapter()` | `openAIMessageFormat` |
-| OpenAI **Responses / Conversations** API SSE | `openAIResponsesAdapter()` | `openAIConversationMessageFormat` |
-| **Vercel AI SDK v6** UIMessage SSE (`toUIMessageStreamResponse()`) | `vercelAIAdapter()` | `vercelAIMessageFormat` |
-| **LangGraph** named-event SSE (`event: messages\ndata: …`) | `langGraphAdapter()` | `langGraphMessageFormat` |
-| Already AG-UI events (your route emits AG-UI SSE directly) | `agUIAdapter()` | `identityMessageFormat` (default) |
+| Your backend streams… | Stream adapter | Pair with message format |
+| ------------------------------------------------------------------ | ------------------------------- | --------------------------------- |
+| OpenAI **Chat Completions** SSE (`data: {…}` lines) | `openAIAdapter()` | `openAIMessageFormat` |
+| OpenAI SDK `stream.toReadableStream()` (NDJSON, no `data:` prefix) | `openAIReadableStreamAdapter()` | `openAIMessageFormat` |
+| OpenAI **Responses / Conversations** API SSE | `openAIResponsesAdapter()` | `openAIConversationMessageFormat` |
+| **Vercel AI SDK v6** UIMessage SSE (`toUIMessageStreamResponse()`) | `vercelAIAdapter()` | `vercelAIMessageFormat` |
+| **LangGraph** named-event SSE (`event: messages\ndata: …`) | `langGraphAdapter()` | `langGraphMessageFormat` |
+| Already AG-UI events (your route emits AG-UI SSE directly) | `agUIAdapter()` | `identityMessageFormat` (default) |
-Wrapping Anthropic, or any provider with no bundled adapter? You have two paths: translate to AG-UI events server-side and use `agUIAdapter()`, or re-emit your provider's stream as OpenAI Completions SSE and use `openAIAdapter()`. See [Migrating](/docs/agent/guides/migrating).
+Wrapping Anthropic, or any provider with no bundled adapter? You have two paths: translate to AG-UI events server-side and use `agUIAdapter()`, or re-emit your provider's stream as OpenAI Completions SSE and use `openAIAdapter()`.
### `agUIAdapter`
@@ -412,7 +420,11 @@ const llm = fetchLLM({
- **Wire shape:** **NDJSON** — one JSON object per line with no `data:` SSE prefix. This is exactly what the OpenAI SDK's `Stream.toReadableStream()` produces.
- **When to use:** Your route returns `stream.toReadableStream()` from the OpenAI SDK directly, instead of re-serializing it as SSE. Same Completions chunk semantics as `openAIAdapter()` (same emitted events), only the line framing differs — it buffers partial lines across chunks rather than splitting on `data: `. Pair with `openAIMessageFormat`.
-<Callout type="info">`openAIAdapter()` and `openAIReadableStreamAdapter()` read the same OpenAI chunk objects — they differ only in framing (`data:` SSE vs. bare NDJSON lines). Match the one your route actually writes; using the wrong one will fail to parse every line.</Callout>
+<Callout type="info">
+ `openAIAdapter()` and `openAIReadableStreamAdapter()` read the same OpenAI chunk objects — they
+ differ only in framing (`data:` SSE vs. bare NDJSON lines). Match the one your route actually
+ writes; using the wrong one will fail to parse every line.
+</Callout>
### `openAIResponsesAdapter`
@@ -447,7 +459,11 @@ const llm = fetchLLM({
- **Current scope:** reasoning, sources, assistant files, custom data, metadata, and tool-approval-request chunks have no equivalent in the current AgentInterface stream processor and are ignored. Approval-gated tools therefore need a custom flow today. Provider-executed tool chunks (`providerExecuted: true`) are rejected because AG-UI cannot preserve their assistant-contained result semantics.
- **When to use:** Your route uses Vercel AI SDK `streamText()` and returns its UIMessage stream response. Pair with `vercelAIMessageFormat` so the route receives `UIMessage[]` that can be passed to `convertToModelMessages()`.
-<Callout type="info">Install `ai@^6` alongside `@openuidev/react-ui` or `@openuidev/react-headless` when using this integration. It is an optional peer dependency, so apps using other adapters do not need the Vercel AI SDK.</Callout>
+<Callout type="info">
+ Install `ai@^6` alongside `@openuidev/react-ui` or `@openuidev/react-headless` when using this
+ integration. It is an optional peer dependency, so apps using other adapters do not need the
+ Vercel AI SDK.
+</Callout>
### `langGraphAdapter`
@@ -476,22 +492,22 @@ const llm = fetchLLM({
Every stream adapter normalizes its provider's stream into the same set of **AG-UI events** — the agent↔UI event protocol OpenUI streams internally (from the `@ag-ui/core` package). These events progressively build the assistant message as they arrive.
-| Event | Role |
-|-------|------|
-| `TEXT_MESSAGE_START` | Begins an assistant text message. |
-| `TEXT_MESSAGE_CONTENT` | Appends a chunk of text to the in-progress message. |
-| `TEXT_MESSAGE_END` | Closes the assistant text message. |
-| `TOOL_CALL_START` | Begins a tool call (carries the tool name / call id). |
-| `TOOL_CALL_ARGS` | Appends a chunk of the tool call's streamed arguments. |
-| `TOOL_CALL_END` | Closes the tool call's arguments. |
-| `TOOL_CALL_RESULT` | Carries the result of a server-executed tool call. |
-| `RUN_ERROR` | Signals a provider/run-level failure; surfaces as an error in the UI. |
+| Event | Role |
+| ---------------------- | --------------------------------------------------------------------- |
+| `TEXT_MESSAGE_START` | Begins an assistant text message. |
+| `TEXT_MESSAGE_CONTENT` | Appends a chunk of text to the in-progress message. |
+| `TEXT_MESSAGE_END` | Closes the assistant text message. |
+| `TOOL_CALL_START` | Begins a tool call (carries the tool name / call id). |
+| `TOOL_CALL_ARGS` | Appends a chunk of the tool call's streamed arguments. |
+| `TOOL_CALL_END` | Closes the tool call's arguments. |
+| `TOOL_CALL_RESULT` | Carries the result of a server-executed tool call. |
+| `RUN_ERROR` | Signals a provider/run-level failure; surfaces as an error in the UI. |
---
## Message formats
-A **message format** converts between the canonical `Message` type at the boundary and your provider's message shape, in both directions. There is one per provider *message shape*:
+A **message format** converts between the canonical `Message` type at the boundary and your provider's message shape, in both directions. There is one per provider _message shape_:
```ts
interface MessageFormat {
@@ -506,7 +522,7 @@ Both methods operate on **arrays**, so formats where one canonical message maps
Where formats are used:
-- **`fetchLLM`** runs `messageFormat.toApi(messages)` on the outgoing request body. (The reply is parsed by the *stream adapter*, not the message format.)
+- **`fetchLLM`** runs `messageFormat.toApi(messages)` on the outgoing request body. (The reply is parsed by the _stream adapter_, not the message format.)
- **`restStorage`** uses `toApi` when creating a thread and `fromApi` when loading a thread's messages — so the same format keeps your stored history and your live requests consistent.
If you omit `messageFormat`, both default to `identityMessageFormat`.
@@ -537,7 +553,7 @@ import { openAIConversationMessageFormat } from "@openuidev/react-ui";
```
- **Shape:** OpenAI's item-based format for the **Responses API** and **Conversations API**. `toApi` returns `ResponseInputItem[]` (accepted by both `responses.create({ input })` and `conversations.items.create({ items })`); `fromApi` reads `ConversationItem[]` / `ResponseItem[]`.
-- **Conversions:** assistant messages are *flattened* into sibling items — a text `message` plus one `function_call` item per tool call; tool results become `function_call_output` items. Inbound, adjacent assistant `message` + `function_call` items are regrouped into one `AssistantMessage`, and Conversations-specific content parts (`reasoning_text`, `summary_text`, `refusal`, …) are folded into text.
+- **Conversions:** assistant messages are _flattened_ into sibling items — a text `message` plus one `function_call` item per tool call; tool results become `function_call_output` items. Inbound, adjacent assistant `message` + `function_call` items are regrouped into one `AssistantMessage`, and Conversations-specific content parts (`reasoning_text`, `summary_text`, `refusal`, …) are folded into text.
- **When to use:** Pair with `openAIResponsesAdapter()`.
### `vercelAIMessageFormat`
@@ -566,9 +582,13 @@ import { langGraphMessageFormat } from "@openuidev/react-ui";
## Related
<Cards>
- <Card title="AgentInterface props" href="/docs/agent/reference/agentinterface-props">Where llm and storage are passed.</Card>
- <Card title="Conversations" href="/docs/agent/core-concepts/conversations">How threads, messages, and persistence fit together.</Card>
- <Card title="Artifacts" href="/docs/agent/core-concepts/artifacts">Persisting durable artifacts and the browser.</Card>
- <Card title="Migrating" href="/docs/agent/guides/migrating">Choosing an adapter for a provider without a bundled one.</Card>
- <Card title="Self-hosting" href="/docs/agent/reference/self-hosting">Implementing the adapters against your own backend.</Card>
+ <Card
+ title="AgentInterface props"
+ href="/docs/agent/reference/agentinterface-props"
+ >
+ Where llm and storage are passed.
+ </Card>
+ <Card title="Conversations" href="/docs/agent/core-concepts/conversations">
+ How threads, messages, and persistence fit together.
+ </Card>
</Cards>
diff --git a/docs/content/docs/agent/reference/agentinterface-props.mdx b/docs/content/docs/agent/reference/agentinterface-props.mdx
index 2b2135a5c..cc02af2d0 100644
--- a/docs/content/docs/agent/reference/agentinterface-props.mdx
+++ b/docs/content/docs/agent/reference/agentinterface-props.mdx
@@ -9,24 +9,24 @@ The only required prop is `llm`. Everything else is optional and falls back to a
## At a glance
-| Prop | Type | Required | Default |
-|-----------------------|---------------------------------------------------|----------|-------------------------------|
-| `llm` | `ChatLLM` | **Yes** | — |
-| `storage` | `ChatStorage` | No | internal in-memory (ephemeral)|
-| `artifactRenderers` | `ReadonlyArray<ArtifactRendererConfig<any>>` | No | none |
-| `artifactCategories` | `ArtifactCategory[]` | No | none (single "Artifacts" item)|
-| `componentLibrary` | `Library` | No | none (markdown rendering) |
-| `components` | `{ AssistantMessage?; UserMessage? }` | No | none |
-| `theme` | `ThemeProps` | No | built-in theme |
-| `disableThemeProvider`| `boolean` | No | `false` |
-| `logoUrl` | `string` | No | none |
-| `agentName` | `string` | No | none |
-| `starters` | `ConversationStarterProps[]` | No | none |
-| `starterVariant` | `"short" \| "long"` | No | — |
-| `path` | `string` | No | — (uncontrolled) |
-| `defaultPath` | `string` | No | thread view (`undefined`) |
-| `onNavigate` | `(next: string \| undefined) => void` | No | — (uncontrolled) |
-| `children` | `ReactNode` | No | none |
+| Prop | Type | Required | Default |
+| ---------------------- | -------------------------------------------- | -------- | ------------------------------ |
+| `llm` | `ChatLLM` | **Yes** | — |
+| `storage` | `ChatStorage` | No | internal in-memory (ephemeral) |
+| `artifactRenderers` | `ReadonlyArray<ArtifactRendererConfig<any>>` | No | none |
+| `artifactCategories` | `ArtifactCategory[]` | No | none (single "Artifacts" item) |
+| `componentLibrary` | `Library` | No | none (markdown rendering) |
+| `components` | `{ AssistantMessage?; UserMessage? }` | No | none |
+| `theme` | `ThemeProps` | No | built-in theme |
+| `disableThemeProvider` | `boolean` | No | `false` |
+| `logoUrl` | `string` | No | none |
+| `agentName` | `string` | No | none |
+| `starters` | `ConversationStarterProps[]` | No | none |
+| `starterVariant` | `"short" \| "long"` | No | — |
+| `path` | `string` | No | — (uncontrolled) |
+| `defaultPath` | `string` | No | thread view (`undefined`) |
+| `onNavigate` | `(next: string \| undefined) => void` | No | — (uncontrolled) |
+| `children` | `ReactNode` | No | none |
The rest of this page explains each group.
@@ -34,31 +34,34 @@ The rest of this page explains each group.
These two props connect `AgentInterface` to your backend. They are independent channels: `llm` produces replies, `storage` persists threads and artifacts.
-| Prop | Type | Required | Default | Description |
-|-----------|---------------|----------|--------------------------------|------------------------------------------------------------------------|
-| `llm` | `ChatLLM` | **Yes** | — | Sends messages to your backend and streams the reply. |
-| `storage` | `ChatStorage` | No | internal in-memory (ephemeral) | Persists thread history (and, optionally, artifacts). |
+| Prop | Type | Required | Default | Description |
+| --------- | ------------- | -------- | ------------------------------ | ----------------------------------------------------- |
+| `llm` | `ChatLLM` | **Yes** | — | Sends messages to your backend and streams the reply. |
+| `storage` | `ChatStorage` | No | internal in-memory (ephemeral) | Persists thread history (and, optionally, artifacts). |
`llm` is a `ChatLLM` — usually built with `fetchLLM()`, which POSTs `{ threadId, messages }` to your route and parses the streamed response. See [Conversations](/docs/agent/core-concepts/conversations) for the model, and the [Adapters & formats reference](/docs/agent/reference/adapters-and-formats) for the full `ChatLLM` / `fetchLLM()` surface and the stream adapters that parse each provider's stream.
`storage` is a `ChatStorage` — `{ thread: ThreadStorage; artifact?: ArtifactStorage }`. Omit it and conversations live only in memory: a page refresh clears everything. Build one with `restStorage()`, or implement the interfaces yourself. The full adapter interfaces (`ChatLLM`, `ChatStorage`, `ThreadStorage`, `ArtifactStorage`, `fetchLLM`, `restStorage`) are in the [Adapters & formats reference](/docs/agent/reference/adapters-and-formats).
-<Callout type="info">The provider API call always happens on your server. `fetchLLM()` only ever talks to your own route, so provider keys never reach the browser.</Callout>
+<Callout type="info">
+ The provider API call always happens on your server. `fetchLLM()` only ever talks to your own
+ route, so provider keys never reach the browser.
+</Callout>
## Rendering
-These props control how the assistant's output is rendered — both durable artifacts (dashboards, reports, presentations, apps) and the inline message body.
+These props control how the assistant's output is rendered — both durable artifacts such as dashboards and apps, and the inline message body.
-| Prop | Type | Required | Default | Description |
-|----------------------|-----------------------------------------------|----------|---------|-----------------------------------------------------------------------------|
-| `artifactRenderers` | `ReadonlyArray<ArtifactRendererConfig<any>>` | No | none | Renderers that display artifacts (from a tool call or from stored content). |
-| `artifactCategories` | `ArtifactCategory[]` | No | none | User-defined groupings for the artifact browser and workspace rail. |
-| `componentLibrary` | `Library` | No | none | Turns on Generative UI — rich interactive components rendered inline in chat.|
-| `components` | `{ AssistantMessage?; UserMessage? }` | No | none | Replace the assistant/user message components entirely. |
+| Prop | Type | Required | Default | Description |
+| -------------------- | -------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------- |
+| `artifactRenderers` | `ReadonlyArray<ArtifactRendererConfig<any>>` | No | none | Renderers that display artifacts (from a tool call or from stored content). |
+| `artifactCategories` | `ArtifactCategory[]` | No | none | User-defined groupings for the artifact browser and workspace rail. |
+| `componentLibrary` | `Library` | No | none | Turns on Generative UI — rich interactive components rendered inline in chat. |
+| `components` | `{ AssistantMessage?; UserMessage? }` | No | none | Replace the assistant/user message components entirely. |
### `artifactRenderers`
-Each entry is built with `defineArtifactRenderer` and links a tool name (or names) to a `preview` (inline in the message) and an `actual` (full view in the workspace panel or a full-page artifact view). The registry indexes by both `toolName` and `type`. See [Artifacts](/docs/agent/core-concepts/artifacts) and the [`defineArtifactRenderer` reference](/docs/agent/reference/define-artifact-renderer).
+Each entry is built with `defineArtifactRenderer` and links a tool name (or names) to a `preview` (inline in the message) and an `actual` (full view in the workspace panel or a full-page artifact view). The registry indexes by both `toolName` and `type`. See the [`defineArtifactRenderer` reference](/docs/agent/reference/define-artifact-renderer).
```tsx
import { AgentInterface, defineArtifactRenderer } from "@openuidev/react-ui";
@@ -76,7 +79,7 @@ const codeArtifact = defineArtifactRenderer({
### `artifactCategories`
-Categories are **user-defined organization** for the artifact browser — they are orthogonal to whether an artifact is static or live. Each is `{ name: string; filter: { type: string[] } }`. Without categories, the sidebar shows a single "Artifacts" item; with them, one item per category. See [Artifacts](/docs/agent/core-concepts/artifacts).
+Categories are **user-defined organization** for the artifact browser — they are orthogonal to whether an artifact is static or live. Each is `{ name: string; filter: { type: string[] } }`. Without categories, the sidebar shows a single "Artifacts" item; with them, one item per category.
```tsx
<AgentInterface
@@ -84,9 +87,9 @@ Categories are **user-defined organization** for the artifact browser — they a
storage={storage}
artifactCategories={[
{ name: "Code", filter: { type: ["code_artifact"] } },
- { name: "Reports", filter: { type: ["th_report"] } },
+ { name: "Dashboards", filter: { type: ["dashboard"] } },
]}
-/>;
+/>
```
### `componentLibrary`
@@ -106,19 +109,19 @@ Override the message components directly: `{ AssistantMessage?, UserMessage? }`.
## Theme
-| Prop | Type | Required | Default | Description |
-|------------------------|--------------|----------|----------------|---------------------------------------------------------------------|
-| `theme` | `ThemeProps` | No | built-in theme | Customizes colors, radii, and typography. |
-| `disableThemeProvider` | `boolean` | No | `false` | Skip the built-in theme provider when your app already supplies one.|
+| Prop | Type | Required | Default | Description |
+| ---------------------- | ------------ | -------- | -------------- | -------------------------------------------------------------------- |
+| `theme` | `ThemeProps` | No | built-in theme | Customizes colors, radii, and typography. |
+| `disableThemeProvider` | `boolean` | No | `false` | Skip the built-in theme provider when your app already supplies one. |
Set `disableThemeProvider` to `true` when `AgentInterface` is mounted inside an app that already wraps it in a compatible theme provider, to avoid nesting two.
## Branding
-| Prop | Type | Required | Default | Description |
-|-------------|----------|----------|---------|----------------------------------------------------------|
-| `logoUrl` | `string` | No | none | Logo shown in the sidebar header and the mobile header. |
-| `agentName` | `string` | No | none | Agent name shown next to the logo. |
+| Prop | Type | Required | Default | Description |
+| ----------- | -------- | -------- | ------- | ------------------------------------------------------- |
+| `logoUrl` | `string` | No | none | Logo shown in the sidebar header and the mobile header. |
+| `agentName` | `string` | No | none | Agent name shown next to the logo. |
These feed the default `SidebarHeader` and `MobileHeader`. To go further, replace those slots. See [Sidebar](/docs/agent/customize/sidebar).
@@ -126,10 +129,10 @@ These feed the default `SidebarHeader` and `MobileHeader`. To go further, replac
Conversation starters are the suggested prompts shown on the welcome screen and in the composer.
-| Prop | Type | Required | Default | Description |
-|------------------|-------------------------------|----------|---------|--------------------------------------------------------------|
-| `starters` | `ConversationStarterProps[]` | No | none | Suggested prompts to seed a conversation. |
-| `starterVariant` | `"short" \| "long"` | No | — | Layout variant for how starters are presented. |
+| Prop | Type | Required | Default | Description |
+| ---------------- | ---------------------------- | -------- | ------- | ---------------------------------------------- |
+| `starters` | `ConversationStarterProps[]` | No | none | Suggested prompts to seed a conversation. |
+| `starterVariant` | `"short" \| "long"` | No | — | Layout variant for how starters are presented. |
Each starter is `{ displayText: string; prompt: string; icon?: ReactNode }` — `displayText` is the label on the suggestion chip and `prompt` is the message sent when it is clicked. These props set the defaults for the `Welcome` and `Composer` slots; either slot can also take its own `starters` / `starterVariant`. See [Welcome & starters](/docs/agent/customize/welcome-and-starters).
@@ -137,11 +140,11 @@ Each starter is `{ displayText: string; prompt: string; icon?: ReactNode }` —
`AgentInterface` has a built-in router. `undefined` is the thread view; non-`undefined` paths select Routes and the artifact browser.
-| Prop | Type | Required | Default | Description |
-|---------------|----------------------------------------|----------|--------------------------|--------------------------------------------------------------|
-| `path` | `string` | No | — (uncontrolled) | Controlled current route. |
-| `defaultPath` | `string` | No | thread view (`undefined`)| Uncontrolled initial route. |
-| `onNavigate` | `(next: string \| undefined) => void` | No | — (uncontrolled) | Navigation callback; **its presence selects controlled mode**.|
+| Prop | Type | Required | Default | Description |
+| ------------- | ------------------------------------- | -------- | ------------------------- | -------------------------------------------------------------- |
+| `path` | `string` | No | — (uncontrolled) | Controlled current route. |
+| `defaultPath` | `string` | No | thread view (`undefined`) | Uncontrolled initial route. |
+| `onNavigate` | `(next: string \| undefined) => void` | No | — (uncontrolled) | Navigation callback; **its presence selects controlled mode**. |
Controlled mode is chosen by the **presence of `onNavigate`**, not by `path !== undefined` — because `undefined` is a meaningful path (the thread view). In controlled mode, drive `path` from your own router and update it inside `onNavigate`. In uncontrolled mode, set an initial route with `defaultPath` and let the component manage navigation internally.
@@ -157,9 +160,9 @@ Controlled consumers must round-trip the reserved artifact-browser paths (`artif
## Children
-| Prop | Type | Required | Default | Description |
-|------------|-------------|----------|---------|---------------------------------------------------|
-| `children` | `ReactNode` | No | none | Slots, primitives, Routes, and free content. |
+| Prop | Type | Required | Default | Description |
+| ---------- | ----------- | -------- | ------- | -------------------------------------------- |
+| `children` | `ReactNode` | No | none | Slots, primitives, Routes, and free content. |
`children` is where composition happens. Pass the compound statics on `AgentInterface` — slots (`AgentInterface.Sidebar`, `.Welcome`, `.Composer`, `.Workspace`, …), primitives (`AgentInterface.SidebarItem`, `.ThreadList`, `.Messages`, …), and `AgentInterface.Route` for multi-page content. Slots not provided fall back to their built-in defaults. See the [Components reference](/docs/agent/reference/components).
@@ -167,12 +170,12 @@ Controlled consumers must round-trip the reserved artifact-browser paths (`artif
<AgentInterface llm={llm}>
<AgentInterface.Welcome
title="What can I help with?"
- description="Ask about your data, generate a report, or build a dashboard."
+ description="Ask about your data or build a dashboard."
/>
<AgentInterface.Route path="settings">
<SettingsPanel />
</AgentInterface.Route>
-</AgentInterface>;
+</AgentInterface>
```
## Related references
diff --git a/docs/content/docs/agent/reference/components.mdx b/docs/content/docs/agent/reference/components.mdx
index 71b7c346a..898530870 100644
--- a/docs/content/docs/agent/reference/components.mdx
+++ b/docs/content/docs/agent/reference/components.mdx
@@ -18,7 +18,7 @@ import { AgentInterface } from "@openuidev/react-ui";
<AgentInterface.SidebarSeparator />
<AgentInterface.ThreadList />
</AgentInterface.Sidebar>
-</AgentInterface>
+</AgentInterface>;
```
There are two kinds:
@@ -27,7 +27,7 @@ There are two kinds:
- **A — omit:** the built-in default renders.
- **B — props:** the default structure renders with your values swapped into specific pieces.
- **C — children:** your children replace the region entirely (children win over props; a dev warning fires if you pass both).
-- **Primitives / statics** — building blocks you place *inside* slots (or, for `Route`, at the top level) to assemble custom layouts: `SidebarItem`, `SidebarContent`, `SidebarSeparator`, `ArtifactNav`, `Route`, `NewChatButton`, `ThreadList`, `Messages`, `MessageLoading`, `ScrollArea`.
+- **Primitives / statics** — building blocks you place _inside_ slots (or, for `Route`, at the top level) to assemble custom layouts: `SidebarItem`, `SidebarContent`, `SidebarSeparator`, `ArtifactNav`, `Route`, `NewChatButton`, `ThreadList`, `Messages`, `MessageLoading`, `ScrollArea`.
All of these are also reachable as named exports from `@openuidev/react-ui`, but the compound-static form (`AgentInterface.X`) is the documented usage.
@@ -35,15 +35,15 @@ All of these are also reachable as named exports from `@openuidev/react-ui`, but
Pass these at the top level of `<AgentInterface>` to override a layout region. The **Modes** column lists which of the three override modes (A — omit, B — props, C — children) each slot supports.
-| Slot | Region | Modes |
-|------|--------|-------|
-| `AgentInterface.Sidebar` | The entire left sidebar | A, C |
-| `AgentInterface.SidebarHeader` | Header at the top of the sidebar | A, B, C |
-| `AgentInterface.MobileHeader` | Top bar shown on mobile in place of the sidebar | A, B, C |
-| `AgentInterface.ThreadHeader` | Header above the active conversation | A, C |
-| `AgentInterface.Welcome` | Empty-state screen shown before a thread starts | A, B, C |
-| `AgentInterface.Composer` | Message input at the bottom of the thread | A, B, C |
-| `AgentInterface.Workspace` | Per-thread right rail listing the thread's artifacts | A, C |
+| Slot | Region | Modes |
+| ------------------------------ | ---------------------------------------------------- | ------- |
+| `AgentInterface.Sidebar` | The entire left sidebar | A, C |
+| `AgentInterface.SidebarHeader` | Header at the top of the sidebar | A, B, C |
+| `AgentInterface.MobileHeader` | Top bar shown on mobile in place of the sidebar | A, B, C |
+| `AgentInterface.ThreadHeader` | Header above the active conversation | A, C |
+| `AgentInterface.Welcome` | Empty-state screen shown before a thread starts | A, B, C |
+| `AgentInterface.Composer` | Message input at the bottom of the thread | A, B, C |
+| `AgentInterface.Workspace` | Per-thread right rail listing the thread's artifacts | A, C |
### `AgentInterface.Sidebar`
@@ -63,8 +63,8 @@ The whole left sidebar. **Modes A, C.**
</AgentInterface.Sidebar>
```
-| Prop | Type | Notes |
-|------|------|-------|
+| Prop | Type | Notes |
+| ---------- | ----------- | ---------------------------------------------- |
| `children` | `ReactNode` | Mode C — replaces the sidebar's inner content. |
<Callout type="info">
@@ -75,55 +75,55 @@ When you provide `<AgentInterface.Sidebar>`, a `<AgentInterface.SidebarHeader>`
The header strip at the top of the sidebar — brand logo, agent name, and the collapse button. **Modes A, B, C.**
-| Prop | Type | Notes |
-|------|------|-------|
-| `logo` | `ReactNode` | Defaults to `logoUrl` from `<AgentInterface>`. |
-| `agentName` | `ReactNode` | Defaults to `agentName` from `<AgentInterface>`. |
-| `collapseButton` | `ReactNode \| false` | Pass `false` to hide the collapse control. |
-| `children` | `ReactNode` | Mode C — replaces the header body. |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ---------------- | -------------------- | ------------------------------------------------ |
+| `logo` | `ReactNode` | Defaults to `logoUrl` from `<AgentInterface>`. |
+| `agentName` | `ReactNode` | Defaults to `agentName` from `<AgentInterface>`. |
+| `collapseButton` | `ReactNode \| false` | Pass `false` to hide the collapse control. |
+| `children` | `ReactNode` | Mode C — replaces the header body. |
+| `className` | `string` | |
### `AgentInterface.MobileHeader`
The top bar shown on mobile viewports in place of the (collapsed) sidebar. **Modes A, B, C.**
-| Prop | Type | Notes |
-|------|------|-------|
-| `logo` | `ReactNode` | |
-| `agentName` | `ReactNode` | |
-| `menuButton` | `ReactNode \| false` | Opens the mobile sidebar drawer. Pass `false` to hide. |
-| `newChatButton` | `ReactNode \| false` | Pass `false` to hide. |
-| `actions` | `ReactNode` | Extra controls, right-aligned. |
-| `children` | `ReactNode` | Mode C — replaces the header. |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| --------------- | -------------------- | ------------------------------------------------------ |
+| `logo` | `ReactNode` | |
+| `agentName` | `ReactNode` | |
+| `menuButton` | `ReactNode \| false` | Opens the mobile sidebar drawer. Pass `false` to hide. |
+| `newChatButton` | `ReactNode \| false` | Pass `false` to hide. |
+| `actions` | `ReactNode` | Extra controls, right-aligned. |
+| `children` | `ReactNode` | Mode C — replaces the header. |
+| `className` | `string` | |
### `AgentInterface.ThreadHeader`
Header bar above the active conversation. **Modes A, C.**
-| Prop | Type | Notes |
-|------|------|-------|
-| `children` | `ReactNode` | Mode C — replaces the header. |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ----------- | ----------- | ----------------------------- |
+| `children` | `ReactNode` | Mode C — replaces the header. |
+| `className` | `string` | |
### `AgentInterface.Welcome`
The empty-state screen shown before the first message of a thread. **Modes A, B, C.** As with every slot, `children` (mode C) win over the content props (mode B) and a dev warning fires if you pass both.
-| Prop | Type | Notes |
-|------|------|-------|
-| `title` | `string` | Greeting/title text. |
-| `description` | `string` | Sub-text under the title. |
-| `image` | `{ url: string } \| ReactNode` | `{ url }` renders a styled 64×64 rounded `<img>`; a `ReactNode` is rendered as-is. |
-| `starters` | `ConversationStarterProps[]` | Conversation starters. Inherits from `<AgentInterface starters>` when omitted. |
-| `starterVariant` | `"short" \| "long"` | Layout for the starters. Inherits from `<AgentInterface starterVariant>`. |
-| `children` | `ReactNode` | Mode C — replaces the screen; when passed, `title`/`description`/`image`/`starters` are ignored (dev warning). |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ---------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `title` | `string` | Greeting/title text. |
+| `description` | `string` | Sub-text under the title. |
+| `image` | `{ url: string } \| ReactNode` | `{ url }` renders a styled 64×64 rounded `<img>`; a `ReactNode` is rendered as-is. |
+| `starters` | `ConversationStarterProps[]` | Conversation starters. Inherits from `<AgentInterface starters>` when omitted. |
+| `starterVariant` | `"short" \| "long"` | Layout for the starters. Inherits from `<AgentInterface starterVariant>`. |
+| `children` | `ReactNode` | Mode C — replaces the screen; when passed, `title`/`description`/`image`/`starters` are ignored (dev warning). |
+| `className` | `string` | |
```tsx
<AgentInterface.Welcome
title="Ask me anything"
- description="I can pull reports, build dashboards, and answer questions."
+ description="I can explore data, build dashboards, and answer questions."
image={{ url: "/logo.png" }}
starters={[{ displayText: "Summarize Q3 revenue", prompt: "Summarize Q3 revenue" }]}
starterVariant="short"
@@ -136,13 +136,13 @@ Each entry in `starters` is a `ConversationStarterProps`: `{ displayText: string
The message input at the bottom of the thread. **Modes A, B, C.**
-| Prop | Type | Notes |
-|------|------|-------|
-| `placeholder` | `string` | Input placeholder. |
-| `starters` | `ConversationStarterProps[]` | Starter chips shown above the input when the chat is empty. Inherits from `<AgentInterface starters>`. |
-| `starterVariant` | `"short" \| "long"` | Inherits from `<AgentInterface starterVariant>`. |
-| `children` | `ReactNode` | Mode C — fully replaces the composer area; auto-starter rendering is then disabled. |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `placeholder` | `string` | Input placeholder. |
+| `starters` | `ConversationStarterProps[]` | Starter chips shown above the input when the chat is empty. Inherits from `<AgentInterface starters>`. |
+| `starterVariant` | `"short" \| "long"` | Inherits from `<AgentInterface starterVariant>`. |
+| `children` | `ReactNode` | Mode C — fully replaces the composer area; auto-starter rendering is then disabled. |
+| `className` | `string` | |
### `AgentInterface.Workspace`
@@ -153,45 +153,45 @@ The per-thread right rail listing the artifacts registered in the active thread.
- Clicking an item opens the corresponding artifact's detailed view.
- Rendered **only in the thread view** — hidden on `Route` pages and the artifact browser. Hidden on mobile.
-| Prop | Type | Notes |
-|------|------|-------|
-| `children` | `ReactNode` | Mode C — replaces the entire rail (you own its chrome and visibility). |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ----------- | ----------- | ---------------------------------------------------------------------- |
+| `children` | `ReactNode` | Mode C — replaces the entire rail (you own its chrome and visibility). |
+| `className` | `string` | |
-See [Artifacts](/docs/agent/core-concepts/artifacts) for the artifact model the Workspace surfaces.
+See [`<AgentInterface>` props](/docs/agent/reference/agentinterface-props) for the Workspace APIs.
## Primitives & statics
Place these inside slots — or, for `Route`, at the top level — to build custom layouts. Unlike slots, primitives are not matched by reference into a region; they render wherever you put them.
-| Primitive | Role |
-|-----------|------|
-| `AgentInterface.SidebarContent` | Scrollable body region of the sidebar. |
-| `AgentInterface.SidebarSeparator` | Styled divider between sidebar groups. |
-| `AgentInterface.SidebarItem` | Clickable nav row, optionally path-bound. |
-| `AgentInterface.ArtifactNav` | Sidebar nav into the global artifact browser. |
-| `AgentInterface.Route` | Top-level exact-path view that replaces the thread region. |
-| `AgentInterface.NewChatButton` | Button that starts a fresh thread. |
-| `AgentInterface.ThreadList` | List of the user's threads from `storage.thread`. |
-| `AgentInterface.Messages` | The active thread's messages + streaming message. |
-| `AgentInterface.MessageLoading` | Default "assistant is thinking" indicator. |
-| `AgentInterface.ScrollArea` | Bottom-pinned scroll container for thread content. |
+| Primitive | Role |
+| --------------------------------- | ---------------------------------------------------------- |
+| `AgentInterface.SidebarContent` | Scrollable body region of the sidebar. |
+| `AgentInterface.SidebarSeparator` | Styled divider between sidebar groups. |
+| `AgentInterface.SidebarItem` | Clickable nav row, optionally path-bound. |
+| `AgentInterface.ArtifactNav` | Sidebar nav into the global artifact browser. |
+| `AgentInterface.Route` | Top-level exact-path view that replaces the thread region. |
+| `AgentInterface.NewChatButton` | Button that starts a fresh thread. |
+| `AgentInterface.ThreadList` | List of the user's threads from `storage.thread`. |
+| `AgentInterface.Messages` | The active thread's messages + streaming message. |
+| `AgentInterface.MessageLoading` | Default "assistant is thinking" indicator. |
+| `AgentInterface.ScrollArea` | Bottom-pinned scroll container for thread content. |
### `AgentInterface.SidebarContent`
The scrollable body region of the sidebar — where nav items and the thread list live. Place it inside `<AgentInterface.Sidebar>` to wrap your sidebar content.
-| Prop | Type | Notes |
-|------|------|-------|
-| `children` | `ReactNode` | The content to render. |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ----------- | ----------- | ---------------------- |
+| `children` | `ReactNode` | The content to render. |
+| `className` | `string` | |
### `AgentInterface.SidebarSeparator`
A styled divider rule for visually grouping sidebar sections. Takes no props; drop it between groups inside the sidebar.
```tsx
-<AgentInterface.SidebarItem path="reports">Reports</AgentInterface.SidebarItem>
+<AgentInterface.SidebarItem path="dashboards">Dashboards</AgentInterface.SidebarItem>
<AgentInterface.SidebarSeparator />
<AgentInterface.ThreadList />
```
@@ -200,23 +200,19 @@ A styled divider rule for visually grouping sidebar sections. Takes no props; dr
A styled clickable row for use inside the sidebar. Visually matches `ThreadList` rows so custom nav blends in with the thread list. Spreads remaining props onto the underlying `<button>`.
-| Prop | Type | Notes |
-|------|------|-------|
-| `icon` | `ReactNode` | Leading icon. |
-| `trailing` | `ReactNode` | Right-aligned trailing content (badges, counts). |
-| `path` | `string` | When set, clicking calls `navigate(path)`; the item auto-selects when the current path matches. Works in controlled and uncontrolled `<AgentInterface>`. |
-| `selected` | `boolean` | Active state. Defaults to `currentPath === path` when `path` is set; pass explicitly to override. |
-| `children` | `ReactNode` | The label. (Required.) |
-| `...buttonProps` | `ComponentPropsWithoutRef<"button">` | `onClick`, `disabled`, `aria-*`, etc. |
+| Prop | Type | Notes |
+| ---------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `icon` | `ReactNode` | Leading icon. |
+| `trailing` | `ReactNode` | Right-aligned trailing content (badges, counts). |
+| `path` | `string` | When set, clicking calls `navigate(path)`; the item auto-selects when the current path matches. Works in controlled and uncontrolled `<AgentInterface>`. |
+| `selected` | `boolean` | Active state. Defaults to `currentPath === path` when `path` is set; pass explicitly to override. |
+| `children` | `ReactNode` | The label. (Required.) |
+| `...buttonProps` | `ComponentPropsWithoutRef<"button">` | `onClick`, `disabled`, `aria-*`, etc. |
**Click order with `path`:** your `onClick` fires first (call `preventDefault()` to suppress navigation) → then `navigate(path)` → then the mobile sidebar closes.
```tsx
-<AgentInterface.SidebarItem
- path="settings"
- icon={<GearIcon />}
- trailing={<Badge>3</Badge>}
->
+<AgentInterface.SidebarItem path="settings" icon={<GearIcon />} trailing={<Badge>3</Badge>}>
Settings
</AgentInterface.SidebarItem>
```
@@ -231,10 +227,10 @@ Sidebar navigation for the global artifact browser. Renders one `SidebarItem` pe
- **Renders nothing** when `storage.artifact` is not configured.
- When you build a custom `<AgentInterface.Sidebar>`, add it back manually where you want it.
-| Prop | Type | Notes |
-|------|------|-------|
-| `icon` | `ReactNode` | Leading icon for every category item. Defaults to a boxes icon. |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ----------- | ----------- | --------------------------------------------------------------- |
+| `icon` | `ReactNode` | Leading icon for every category item. Defaults to a boxes icon. |
+| `className` | `string` | |
```tsx
<AgentInterface.Sidebar>
@@ -247,16 +243,16 @@ Sidebar navigation for the global artifact browser. Renders one `SidebarItem` pe
</AgentInterface.Sidebar>
```
-See [Artifacts](/docs/agent/core-concepts/artifacts).
+See [`<AgentInterface>` props](/docs/agent/reference/agentinterface-props).
### `AgentInterface.Route`
Declares a routable view. Placed at the **top level** of `<AgentInterface>` (not inside a slot). When the current nav path **exactly matches** `path`, the Route's children **replace the entire thread region** — `MobileHeader`, `ThreadHeader`, the message scroll area, and `Composer` are all hidden. When no Route matches, the thread region renders normally.
-| Prop | Type | Notes |
-|------|------|-------|
-| `path` | `string` | Exact string match — **no wildcards or params**. |
-| `children` | `ReactNode` | Content shown in the thread region when active. |
+| Prop | Type | Notes |
+| ---------- | ----------- | ------------------------------------------------ |
+| `path` | `string` | Exact string match — **no wildcards or params**. |
+| `children` | `ReactNode` | Content shown in the thread region when active. |
```tsx
<AgentInterface llm={llm}>
@@ -273,9 +269,9 @@ Use multiple `<AgentInterface.Route>` siblings to define separate views. The pat
A styled button that starts a fresh thread (clears the active thread and returns to the empty/welcome state). Drop it anywhere inside the sidebar or a custom header.
-| Prop | Type | Notes |
-|------|------|-------|
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ----------- | -------- | ----- |
+| `className` | `string` | |
```tsx
<AgentInterface.SidebarHeader />
@@ -286,9 +282,9 @@ A styled button that starts a fresh thread (clears the active thread and returns
Renders the list of the user's threads from `storage.thread` (one row per thread). Clicking a row opens that thread and **auto-clears the current path** (returning to the thread view from any Route or the artifact browser).
-| Prop | Type | Notes |
-|------|------|-------|
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ----------- | -------- | ----- |
+| `className` | `string` | |
```tsx
<AgentInterface.SidebarContent>
@@ -300,12 +296,12 @@ Renders the list of the user's threads from `storage.thread` (one row per thread
Renders the active thread's messages, including the in-flight streaming message and the loading indicator. Used inside a custom thread region (typically wrapped in `ScrollArea`).
-| Prop | Type | Notes |
-|------|------|-------|
-| `loader` | `ReactNode` | Custom loading indicator shown while a response is pending. Defaults to `MessageLoading`. |
-| `assistantMessage` | component | Override for rendering assistant messages. Mirrors `components.AssistantMessage` on `<AgentInterface>`. |
-| `userMessage` | component | Override for rendering user messages. Mirrors `components.UserMessage`. |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------- |
+| `loader` | `ReactNode` | Custom loading indicator shown while a response is pending. Defaults to `MessageLoading`. |
+| `assistantMessage` | component | Override for rendering assistant messages. Mirrors `components.AssistantMessage` on `<AgentInterface>`. |
+| `userMessage` | component | Override for rendering user messages. Mirrors `components.UserMessage`. |
+| `className` | `string` | |
```tsx
<AgentInterface.ScrollArea>
@@ -327,12 +323,12 @@ The default "assistant is thinking" indicator. Render it standalone, or pass it
A scroll container that keeps the conversation pinned to the bottom as messages stream in. Wrap `Messages` (or any thread content) in it when composing a custom thread region.
-| Prop | Type | Notes |
-|------|------|-------|
-| `scrollVariant` | `ScrollVariant` | Controls the scroll-to-bottom behavior when the last message is added. |
-| `userMessageSelector` | `string` | CSS selector identifying the user message element (used to anchor scrolling). |
-| `children` | `ReactNode` | Scrollable content. |
-| `className` | `string` | |
+| Prop | Type | Notes |
+| --------------------- | --------------- | ----------------------------------------------------------------------------- |
+| `scrollVariant` | `ScrollVariant` | Controls the scroll-to-bottom behavior when the last message is added. |
+| `userMessageSelector` | `string` | CSS selector identifying the user message element (used to anchor scrolling). |
+| `children` | `ReactNode` | Scrollable content. |
+| `className` | `string` | |
```tsx
<AgentInterface.ScrollArea>
diff --git a/docs/content/docs/agent/reference/define-artifact-renderer.mdx b/docs/content/docs/agent/reference/define-artifact-renderer.mdx
index 3eb5e6b80..1dc862380 100644
--- a/docs/content/docs/agent/reference/define-artifact-renderer.mdx
+++ b/docs/content/docs/agent/reference/define-artifact-renderer.mdx
@@ -3,7 +3,7 @@ title: defineArtifactRenderer
description: Full reference for the artifact-renderer config — type, toolName, the parser contract, preview/actual, controls, and registry matching.
---
-A **renderer** describes how one kind of artifact — a dashboard, a report, a slide deck, a code file — turns into UI: an inline preview inside the chat message and a full view in a side panel or page. You build one with `defineArtifactRenderer(config)` and pass the results to `<AgentInterface>` through the [`artifactRenderers`](/docs/agent/reference/agentinterface-props#artifactrenderers) prop.
+A **renderer** describes how one kind of artifact — a dashboard, data explorer, or code file — turns into UI: an inline preview inside the chat message and a full view in a side panel or page. You build one with `defineArtifactRenderer(config)` and pass the results to `<AgentInterface>` through the [`artifactRenderers`](/docs/agent/reference/agentinterface-props#artifactrenderers) prop.
```tsx
import { defineArtifactRenderer } from "@openuidev/react-ui";
@@ -23,7 +23,7 @@ const codeArtifactRenderer = defineArtifactRenderer({
`defineArtifactRenderer` returns its argument unchanged. Its only job is type inference: it infers the `Props` type from the `parser`'s return value, so `preview` and `actual` receive a fully-typed `props` without you annotating anything by hand. (Without it you'd have to write `const r: ArtifactRendererConfig<CodeArtifact> = { ... }`.)
-For a walkthrough of building a renderer end to end, see [Custom artifacts](/docs/agent/guides/custom-artifacts). This page is the precise contract.
+This page documents the precise renderer contract.
## Config type
@@ -59,13 +59,13 @@ interface ArtifactRendererControls {
All five fields (`type`, `toolName`, `parser`, `preview`, `actual`) are required.
-| Field | Type | Purpose |
-| --- | --- | --- |
-| `type` | `string` | The artifact kind — the key for the storage path and for category filters. |
-| `toolName` | `string \| string[]` | The tool call(s) this renderer matches on the tool-call path. |
-| `parser` | `(raw, ctx) => ParsedArtifact \| null` | Converts the raw envelope into typed `props` plus an optional `meta` registry entry. |
-| `preview` | `(props, controls) => ReactNode` | The compact inline view rendered in the chat message. |
-| `actual` | `(props, controls) => ReactNode` | The full view rendered in the detailed-view panel or full-page browser. |
+| Field | Type | Purpose |
+| ---------- | -------------------------------------- | ------------------------------------------------------------------------------------ |
+| `type` | `string` | The artifact kind — the key for the storage path and for category filters. |
+| `toolName` | `string \| string[]` | The tool call(s) this renderer matches on the tool-call path. |
+| `parser` | `(raw, ctx) => ParsedArtifact \| null` | Converts the raw envelope into typed `props` plus an optional `meta` registry entry. |
+| `preview` | `(props, controls) => ReactNode` | The compact inline view rendered in the chat message. |
+| `actual` | `(props, controls) => ReactNode` | The full view rendered in the detailed-view panel or full-page browser. |
## `type`
@@ -87,10 +87,10 @@ The artifact kind — a literal string like `"code_artifact"` or `"code_block"`.
toolName: string | string[];
```
-The tool call(s) this renderer matches on the tool-call path. Literal strings only — **no `RegExp`, no wildcards, no patterns**. A single string matches one tool; an array registers the *same* renderer for several tool names (e.g. a create and an edit tool that both yield the same artifact):
+The tool call(s) this renderer matches on the tool-call path. Literal strings only — **no `RegExp`, no wildcards, no patterns**. A single string matches one tool; an array registers the _same_ renderer for several tool names (e.g. a create and an edit tool that both yield the same artifact):
```ts
-toolName: ["presentation:create", "presentation:edit"],
+toolName: ["dashboard:create", "dashboard:edit"],
```
On a duplicate `toolName` across renderers, the first registration wins.
@@ -104,16 +104,16 @@ parser: (
) => { props: Props; meta: { id; version; heading } | null } | null;
```
-The parser converts the raw envelope into typed `props` plus an optional `meta` registry entry. The SDK **does not pre-parse JSON** — `args` and `response` arrive exactly as the backend emitted them (typically a JSON *string* for `args`, the raw deserialized value for `response`, depending on your stream adapter). Your parser owns deserialization and validation.
+The parser converts the raw envelope into typed `props` plus an optional `meta` registry entry. The SDK **does not pre-parse JSON** — `args` and `response` arrive exactly as the backend emitted them (typically a JSON _string_ for `args`, the raw deserialized value for `response`, depending on your stream adapter). Your parser owns deserialization and validation.
### Two invocation paths
The same parser is called on both paths, with different inputs:
-| | `args` | `response` | `ctx.isStreaming` |
-| --- | --- | --- | --- |
+| | `args` | `response` | `ctx.isStreaming` |
+| ------------------------------------------ | -------------------------------- | ------------------------------------------- | ---------------------------------------------------------- |
| **Tool-call path** (matched by `toolName`) | the call's arguments, as emitted | the tool result, or `null` until it arrives | `true` while args stream in; `false` once the result lands |
-| **Storage path** (matched by `type`) | `undefined` | `artifact.content` | always `false` |
+| **Storage path** (matched by `type`) | `undefined` | `artifact.content` | always `false` |
Concretely, the storage path always calls:
@@ -123,16 +123,16 @@ parser({ args: undefined, response: artifact.content }, { isStreaming: false });
Two consequences your parser must respect:
-1. **It is called on every update during streaming.** While `ctx.isStreaming` is `true`, `args` may be a *partial* JSON string (the LLM is still emitting it) and `response` may be `null` (the tool result hasn't paired in yet). Tolerate both — wrap JSON parsing in `try/catch`, and bail with `return null` until you have enough to render.
-2. **Read everything you need out of `response`, not `args`.** Only the tool-call path populates `args`, and only the storage path guarantees a complete `response`. Treat `args` as a streaming nicety (useful for an early preview) and `response` as the source of truth. To make one renderer work on both paths, ensure whatever your tool *returns* has the same shape as whatever you *persist* as `artifact.content`.
+1. **It is called on every update during streaming.** While `ctx.isStreaming` is `true`, `args` may be a _partial_ JSON string (the LLM is still emitting it) and `response` may be `null` (the tool result hasn't paired in yet). Tolerate both — wrap JSON parsing in `try/catch`, and bail with `return null` until you have enough to render.
+2. **Read everything you need out of `response`, not `args`.** Only the tool-call path populates `args`, and only the storage path guarantees a complete `response`. Treat `args` as a streaming nicety (useful for an early preview) and `response` as the source of truth. To make one renderer work on both paths, ensure whatever your tool _returns_ has the same shape as whatever you _persist_ as `artifact.content`.
### Return value
-| Return | Effect |
-| --- | --- |
-| `null` (outer) | Skip rendering this call entirely — no preview, no actual, no registry entry. |
+| Return | Effect |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `null` (outer) | Skip rendering this call entirely — no preview, no actual, no registry entry. |
| `{ props, meta: { id, version, heading } }` | Render `preview`/`actual` with `props`, **and** register an entry in the per-thread ThreadContext. |
-| `{ props, meta: null }` | Render `preview`/`actual` with `props`, but do **not** register in ThreadContext. |
+| `{ props, meta: null }` | Render `preview`/`actual` with `props`, but do **not** register in ThreadContext. |
`meta` controls the [per-thread artifact registry](/docs/agent/reference/hooks#useartifactlist) — the list backing `useArtifactList` and the [Workspace](/docs/agent/reference/components#agentinterfaceworkspace) rail:
@@ -181,21 +181,21 @@ Both `preview` and `actual` receive a `controls` object:
```ts
interface ArtifactRendererControls {
- isActive: boolean; // this renderer's detailed view is the currently active one
+ isActive: boolean; // this renderer's detailed view is the currently active one
isStreaming: boolean; // true while the tool call is still streaming; always false for storage-opened artifacts
- open: () => void; // activate this renderer's detailed view
- close: () => void; // close this renderer's detailed view if active
- toggle: () => void; // toggle this renderer's detailed view
+ open: () => void; // activate this renderer's detailed view
+ close: () => void; // close this renderer's detailed view if active
+ toggle: () => void; // toggle this renderer's detailed view
}
```
-| Field | Meaning |
-| --- | --- |
-| `isActive` | `true` when this renderer's detailed view is the currently active one. Lets a preview reflect that its panel is already open (e.g. highlight the card). |
+| Field | Meaning |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isActive` | `true` when this renderer's detailed view is the currently active one. Lets a preview reflect that its panel is already open (e.g. highlight the card). |
| `isStreaming` | Mirrors the `ctx.isStreaming` your parser saw — `true` while arguments arrive incrementally and no tool result has paired in, then `false` once the result lands. Always `false` for storage-opened artifacts. |
-| `open` | Activate this renderer's detailed view. |
-| `close` | Close this renderer's detailed view if active. |
-| `toggle` | Toggle this renderer's detailed view. |
+| `open` | Activate this renderer's detailed view. |
+| `close` | Close this renderer's detailed view if active. |
+| `toggle` | Toggle this renderer's detailed view. |
The **same component instance is reused** across the streaming → completed transition (no remount), so you can swap UI states off `isStreaming` — a skeleton or "streaming…" badge during partial args, then the final view once the result lands.
@@ -209,14 +209,16 @@ Pass an array of configs to `<AgentInterface artifactRenderers={[...]}>`. The in
```tsx
<AgentInterface
llm={llm}
- artifactRenderers={[codeArtifactRenderer, presentationRenderer, codeBlockRenderer]}
+ artifactRenderers={[codeArtifactRenderer, dashboardRenderer, codeBlockRenderer]}
/>
```
**First-wins on duplicates.** If two renderers register the same `toolName`, the first one in the array wins and the later one is ignored (with a dev-mode `console.warn`). The same rule applies independently to `type`. Because the rules are independent, a renderer whose `type` collides with an earlier one is still indexed under its own (non-colliding) `toolName`s — only the type-based lookup is deduped. **Put your custom renderers before any SDK defaults** so yours win.
<Callout type="warn">
-The registry is built once and stays stable for the provider's lifetime; later changes to the `artifactRenderers` prop are ignored (with a dev-mode warning). Pass a stable array — don't construct a fresh `artifactRenderers` value on every render expecting it to swap renderers in.
+ The registry is built once and stays stable for the provider's lifetime; later changes to the
+ `artifactRenderers` prop are ignored (with a dev-mode warning). Pass a stable array — don't
+ construct a fresh `artifactRenderers` value on every render expecting it to swap renderers in.
</Callout>
### Looking renderers up at runtime
@@ -287,8 +289,6 @@ export const codeBlockRenderer = defineArtifactRenderer({
## See also
-- [Custom artifacts](/docs/agent/guides/custom-artifacts) — the build-it walkthrough, including the storage path and `artifactCategories`.
-- [Artifacts](/docs/agent/core-concepts/artifacts) — what artifacts are and where they show up.
- [Hooks](/docs/agent/reference/hooks) — `useArtifactRenderer`, `useArtifactRendererRegistry`, `useArtifactList`.
- [`<AgentInterface>` props](/docs/agent/reference/agentinterface-props) — `artifactRenderers`, `artifactCategories`.
- [Components](/docs/agent/reference/components#agentinterfaceworkspace) — the Workspace rail backed by the registry.
diff --git a/docs/content/docs/agent/reference/hooks.mdx b/docs/content/docs/agent/reference/hooks.mdx
index f44fe5dca..f9dde13dd 100644
--- a/docs/content/docs/agent/reference/hooks.mdx
+++ b/docs/content/docs/agent/reference/hooks.mdx
@@ -59,7 +59,7 @@ Reserved `artifacts/…` paths are matched before your own Routes.
## Artifact storage & registry
-These cover the two distinct artifact surfaces: the **storage adapter** (the global, cross-thread browser backed by `storage.artifact`) and the **per-thread registry** (the artifacts a renderer registered while rendering the current thread). See [Artifacts](/docs/agent/core-concepts/artifacts) for how the two relate.
+These cover the two distinct artifact surfaces: the **storage adapter** (the global, cross-thread browser backed by `storage.artifact`) and the **per-thread registry** (the artifacts a renderer registered while rendering the current thread).
### `useArtifactStorage`
@@ -97,14 +97,11 @@ function CategoryTabs() {
### `useArtifactList`
```ts
-function useArtifactList(filter?: { type?: string[] }): Record<
- string,
- ArtifactEntry[]
->;
+function useArtifactList(filter?: { type?: string[] }): Record<string, ArtifactEntry[]>;
// ArtifactEntry = { id: string; version: number; heading: string; type: string }
```
-Returns the **per-thread artifact registry** — the artifacts a renderer registered while rendering the *current* thread, keyed for grouping (the same data that powers the per-thread Workspace rail). Pass `filter.type` to limit to specific artifact types. This is the in-thread registry, **not** the global storage browser — it reflects what the open conversation produced and works even with ephemeral storage.
+Returns the **per-thread artifact registry** — the artifacts a renderer registered while rendering the _current_ thread, keyed for grouping (the same data that powers the per-thread Workspace rail). Pass `filter.type` to limit to specific artifact types. This is the in-thread registry, **not** the global storage browser — it reflects what the open conversation produced and works even with ephemeral storage.
```tsx
function ThreadArtifacts() {
@@ -197,14 +194,14 @@ function ThreadCount() {
### `useMessage`
```ts
-function useMessage(): Message;
+function useMessage(): { message: Message };
```
-Returns the canonical `Message` for the **current message row** — the same hook the built-in message renderer uses, so you never thread the message through props. Because it returns the live message, your component re-renders as the reply streams in (`content` grows token by token). **Throws if called outside a message component** — it only works inside the components you pass via the `components` prop or inside `AgentInterface.Messages`.
+Returns an object containing the canonical `Message` for the **current message row** — the same hook the built-in message renderer uses, so you never thread the message through props. Because it returns the live message, your component re-renders as the reply streams in (`content` grows token by token). **Throws if called outside a message component** — it only works inside the components you pass via the `components` prop or inside `AgentInterface.Messages`.
```tsx
function AssistantMessage() {
- const message = useMessage();
+ const { message } = useMessage();
return <div className="bubble">{message.content}</div>;
}
```
@@ -277,34 +274,49 @@ Returns the store holding the **thread context** — the per-thread registry of
const ctx = useThreadContextStore();
```
-<Callout type="info">The exact return shapes of the detailed-view hooks and `useThreadContextStore` are internal store/view objects. For the common cases — opening the full view, listing a thread's artifacts — prefer the renderer `controls` ([defineArtifactRenderer](/docs/agent/reference/define-artifact-renderer)) and `useArtifactList` over reaching into these stores.</Callout>
+<Callout type="info">
+ The exact return shapes of the detailed-view hooks and `useThreadContextStore` are internal
+ store/view objects. For the common cases — opening the full view, listing a thread's artifacts —
+ prefer the renderer `controls`
+ ([defineArtifactRenderer](/docs/agent/reference/define-artifact-renderer)) and
+ `useArtifactList` over reaching into these stores.
+</Callout>
---
## Where each hook can be called
-| Hook | Call site | Outside `<AgentInterface>` |
-|------|-----------|----------------------------|
-| `useNav` | anywhere in the tree | throws |
-| `useArtifactStorage` | anywhere in the tree | returns `null` |
-| `useArtifactCategories` | anywhere in the tree | empty array |
-| `useArtifactList` | inside a thread | empty / per-thread |
-| `useArtifactRenderer` | anywhere in the tree | `null` |
-| `useArtifactRendererRegistry` | anywhere in the tree | `null` |
-| `useThread` | inside a thread | n/a |
-| `useThreadList` | anywhere in the tree | n/a |
-| `useMessage` | inside a message component only | throws |
-| `useActiveDetailedView` · `useDetailedView` · `useDetailedViewStore` · `useDetailedViewPortalTarget` | inside a thread | n/a |
-| `useThreadContextStore` | inside a thread | n/a |
+| Hook | Call site | Outside `<AgentInterface>` |
+| ---------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------- |
+| `useNav` | anywhere in the tree | throws |
+| `useArtifactStorage` | anywhere in the tree | returns `null` |
+| `useArtifactCategories` | anywhere in the tree | empty array |
+| `useArtifactList` | inside a thread | empty / per-thread |
+| `useArtifactRenderer` | anywhere in the tree | `null` |
+| `useArtifactRendererRegistry` | anywhere in the tree | `null` |
+| `useThread` | inside a thread | n/a |
+| `useThreadList` | anywhere in the tree | n/a |
+| `useMessage` | inside a message component only | throws |
+| `useActiveDetailedView` · `useDetailedView` · `useDetailedViewStore` · `useDetailedViewPortalTarget` | inside a thread | n/a |
+| `useThreadContextStore` | inside a thread | n/a |
<Cards>
- <Card title="<AgentInterface> props" href="/docs/agent/reference/agentinterface-props">
+ <Card
+ title="<AgentInterface> props"
+ href="/docs/agent/reference/agentinterface-props"
+ >
Every prop AgentInterface accepts.
</Card>
- <Card title="Adapters & formats" href="/docs/agent/reference/adapters-and-formats">
+ <Card
+ title="Adapters & formats"
+ href="/docs/agent/reference/adapters-and-formats"
+ >
The storage and LLM adapter shapes hooks read from.
</Card>
- <Card title="defineArtifactRenderer" href="/docs/agent/reference/define-artifact-renderer">
+ <Card
+ title="defineArtifactRenderer"
+ href="/docs/agent/reference/define-artifact-renderer"
+ >
Register renderers and their preview/actual controls.
</Card>
<Card title="Components" href="/docs/agent/reference/components">
diff --git a/docs/content/docs/agent/reference/self-hosting.mdx b/docs/content/docs/agent/reference/self-hosting.mdx
index 8fad92a11..3cb4122bb 100644
--- a/docs/content/docs/agent/reference/self-hosting.mdx
+++ b/docs/content/docs/agent/reference/self-hosting.mdx
@@ -1,9 +1,9 @@
---
-title: Self-hosting
-description: Run your own backend instead of OpenUI Cloud — connect your LLM with a streaming route, persist threads and artifacts against your own storage, on any server framework.
+title: Connect a backend
+description: Connect your LLM with a streaming route and persist threads and artifacts with your own storage.
---
-OpenUI Cloud handles the backend for you: the provider call, streaming, conversation history, and artifact storage all run behind a single managed endpoint, and `<AgentInterface>` just points at it (see [OpenUI Cloud](/docs/agent/getting-started/openui-cloud)). This page is for the **self-hosted** variant — you run the backend yourself, against your own provider keys, database, and server framework.
+`<AgentInterface>` connects to an agent through your application route. You run the backend with your own provider keys, database, and server framework.
Everything `<AgentInterface>` needs from a backend flows through two independent interfaces:
@@ -12,7 +12,11 @@ Everything `<AgentInterface>` needs from a backend flows through two independent
They are configured separately. You can run a real `llm` with ephemeral (in-memory) storage, or persistent storage with a placeholder `llm`. For the full type signatures of every interface and factory named here, see [Adapters & formats](/docs/agent/reference/adapters-and-formats); this page is the worked-example home for wiring them against your own backend.
-<Callout type="info">The provider key **always** lives server-side. `fetchLLM` only ever talks to your own origin (e.g. `/api/chat`), never directly to `api.openai.com`. The key is read from `process.env` inside your route and is never bundled into the browser.</Callout>
+<Callout type="info">
+ The provider key **always** lives server-side. `fetchLLM` only ever talks to your own origin (e.g.
+ `/api/chat`), never directly to `api.openai.com`. The key is read from `process.env` inside your
+ route and is never bundled into the browser.
+</Callout>
## 1. Connect your LLM
@@ -25,9 +29,9 @@ The `llm` channel is two halves of one loop:
import { AgentInterface, fetchLLM, openAIAdapter, openAIMessageFormat } from "@openuidev/react-ui";
const llm = fetchLLM({
- url: "/api/chat", // your route handler
- streamAdapter: openAIAdapter(), // parses the SDK's raw SSE response
- messageFormat: openAIMessageFormat, // how to shape outgoing messages
+ url: "/api/chat", // your route handler
+ streamAdapter: openAIAdapter(), // parses the SDK's raw SSE response
+ messageFormat: openAIMessageFormat, // how to shape outgoing messages
});
export default function App() {
@@ -43,14 +47,14 @@ Your route always receives a JSON body of `{ threadId, messages }` and returns a
`streamAdapter` governs the **response** (how the streamed bytes are decoded); `messageFormat` governs the **request** (how outgoing `messages` are shaped). They are chosen independently but pair up by provider. Each adapter is a factory — **call it**: `openAIAdapter()`, not the bare reference.
-| Provider / route output | `streamAdapter` | `messageFormat` |
-|---|---|---|
-| OpenAI Chat Completions, NDJSON from `stream.toReadableStream()` | `openAIReadableStreamAdapter()` | `openAIMessageFormat` |
-| OpenAI Chat Completions, raw SSE (`data: {…}\n\n`, `data: [DONE]`) | `openAIAdapter()` | `openAIMessageFormat` |
-| OpenAI **Responses / Conversations** API stream | `openAIResponsesAdapter()` | `openAIConversationMessageFormat` |
-| Vercel AI SDK v6 UIMessage stream from `toUIMessageStreamResponse()` | `vercelAIAdapter()` | `vercelAIMessageFormat` |
-| LangGraph stream (named SSE events) | `langGraphAdapter()` | `langGraphMessageFormat` |
-| A backend that already emits AG-UI events | `agUIAdapter()` | depends on what your route expects |
+| Provider / route output | `streamAdapter` | `messageFormat` |
+| -------------------------------------------------------------------- | ------------------------------- | ---------------------------------- |
+| OpenAI Chat Completions, NDJSON from `stream.toReadableStream()` | `openAIReadableStreamAdapter()` | `openAIMessageFormat` |
+| OpenAI Chat Completions, raw SSE (`data: {…}\n\n`, `data: [DONE]`) | `openAIAdapter()` | `openAIMessageFormat` |
+| OpenAI **Responses / Conversations** API stream | `openAIResponsesAdapter()` | `openAIConversationMessageFormat` |
+| Vercel AI SDK v6 UIMessage stream from `toUIMessageStreamResponse()` | `vercelAIAdapter()` | `vercelAIMessageFormat` |
+| LangGraph stream (named SSE events) | `langGraphAdapter()` | `langGraphMessageFormat` |
+| A backend that already emits AG-UI events | `agUIAdapter()` | depends on what your route expects |
The full catalogue and the precise wire format each adapter expects are in [Adapters & formats](/docs/agent/reference/adapters-and-formats).
@@ -72,7 +76,7 @@ export async function POST(req: Request) {
{
model: "gpt-4o",
stream: true, // ← the part that makes it stream
- messages, // already OpenAI-shaped via openAIMessageFormat
+ messages, // already OpenAI-shaped via openAIMessageFormat
},
{ signal: req.signal }, // propagate browser aborts
)
@@ -103,12 +107,12 @@ Anthropic streams its own format, and OpenUI has **no built-in adapter for it**.
The events a text reply needs:
-| Event `type` | Fields | Meaning |
-|---|---|---|
-| `TEXT_MESSAGE_START` | `messageId` | An assistant text message begins. |
-| `TEXT_MESSAGE_CONTENT` | `messageId`, `delta` | A chunk of assistant text. |
-| `TEXT_MESSAGE_END` | `messageId` | The text message is complete. |
-| `RUN_ERROR` | `message` | The turn failed; surfaces as an error in the UI. |
+| Event `type` | Fields | Meaning |
+| ---------------------- | -------------------- | ------------------------------------------------ |
+| `TEXT_MESSAGE_START` | `messageId` | An assistant text message begins. |
+| `TEXT_MESSAGE_CONTENT` | `messageId`, `delta` | A chunk of assistant text. |
+| `TEXT_MESSAGE_END` | `messageId` | The text message is complete. |
+| `RUN_ERROR` | `message` | The turn failed; surfaces as an error in the UI. |
```ts
// app/api/chat/route.ts
@@ -148,7 +152,10 @@ export async function POST(req: Request) {
}
sse({ type: "TEXT_MESSAGE_END", messageId });
} catch (err) {
- sse({ type: "RUN_ERROR", message: err instanceof Error ? err.message : "Anthropic call failed" });
+ sse({
+ type: "RUN_ERROR",
+ message: err instanceof Error ? err.message : "Anthropic call failed",
+ });
} finally {
controller.close(); // flips the UI loading state off — leave it open and the loader never disappears
}
@@ -156,7 +163,11 @@ export async function POST(req: Request) {
});
return new Response(stream, {
- headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" },
+ headers: {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache",
+ Connection: "keep-alive",
+ },
});
}
```
@@ -205,13 +216,13 @@ export default function App() {
That's the whole frontend change — one prop. You implement the five endpoints `restStorage` calls; the sidebar's thread lifecycle comes for free. With `baseUrl: "/api/threads"`:
-| Operation | Method | Path | Request body | Returns |
-|---|---|---|---|---|
-| List threads | `GET` | `/api/threads/get` | — (append `?cursor={cursor}` to paginate) | `{ threads, nextCursor? }` |
-| Create thread | `POST` | `/api/threads/create` | `{ messages: [...] }` (first user message via the message format) | the new `Thread` |
-| Get messages | `GET` | `/api/threads/get/{threadId}` | — | the thread's `Message[]` |
-| Update thread | `PATCH` | `/api/threads/update/{threadId}` | the full `Thread` | the updated `Thread` |
-| Delete thread | `DELETE` | `/api/threads/delete/{threadId}` | — | nothing |
+| Operation | Method | Path | Request body | Returns |
+| ------------- | -------- | -------------------------------- | ----------------------------------------------------------------- | -------------------------- |
+| List threads | `GET` | `/api/threads/get` | — (append `?cursor={cursor}` to paginate) | `{ threads, nextCursor? }` |
+| Create thread | `POST` | `/api/threads/create` | `{ messages: [...] }` (first user message via the message format) | the new `Thread` |
+| Get messages | `GET` | `/api/threads/get/{threadId}` | — | the thread's `Message[]` |
+| Update thread | `PATCH` | `/api/threads/update/{threadId}` | the full `Thread` | the updated `Thread` |
+| Delete thread | `DELETE` | `/api/threads/delete/{threadId}` | — | nothing |
`restStorage` throws a descriptive error on any non-`ok` response. The `Thread` shape at the boundary is `{ id, title, createdAt: string | number, isPending? }`. By default `restStorage` uses the identity message format; pass `messageFormat` (and optional `headers` / `fetch`) if your backend stores a provider-specific shape — it is applied to the `create` body (`toApi`) and the `get/{threadId}` response (`fromApi`).
@@ -264,7 +275,7 @@ export async function DELETE(_req: NextRequest, { params }: { params: { threadId
}
```
-`db` is a stand-in for your persistence layer — Postgres, SQLite, Redis, a cloud KV store, anything. The endpoints are thin: read/write threads and messages, return the shapes the table describes.
+`db` is a stand-in for your persistence layer—Postgres, SQLite, Redis, a hosted KV store, or anything similar. The endpoints are thin: read and write threads and messages, then return the shapes the table describes.
### Custom `ChatStorage` instead
@@ -301,23 +312,27 @@ export const storage: ChatStorage = {
The five methods map one-to-one onto the sidebar:
-| Method | When it runs |
-|---|---|
-| `listThreads(cursor?)` | Populating the thread list; loading more on scroll. |
+| Method | When it runs |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `listThreads(cursor?)` | Populating the thread list; loading more on scroll. |
| `createThread(firstMessage)` | User sends the first message of a new chat. Receives the `UserMessage`. |
-| `getMessages(threadId)` | User opens a thread. Returns its `Message[]`. |
-| `updateThread(thread)` | A thread changes (e.g. rename). Returns the updated `Thread`. |
-| `deleteThread(id)` | User deletes a thread. |
+| `getMessages(threadId)` | User opens a thread. Returns its `Message[]`. |
+| `updateThread(thread)` | A thread changes (e.g. rename). Returns the updated `Thread`. |
+| `deleteThread(id)` | User deletes a thread. |
## 4. Store artifacts
-Adding an optional `artifact` channel to your storage makes every dashboard, report, and presentation the agent produces a durable, searchable, cross-thread record — and `<AgentInterface>` renders the entire artifact browser (sidebar entry → searchable list → full-page view) for you. `ArtifactStorage` is three methods:
+Adding an optional `artifact` channel to your storage makes every stored dashboard or application view a durable, searchable, cross-thread record. `ArtifactStorage` is three methods:
```ts
interface ArtifactStorage {
// name/type filtering is SERVER-SIDE; cursor-paginated
- list(params?: { name?: string; type?: string[]; cursor?: string; limit?: number }):
- Promise<{ artifacts: ArtifactSummary[]; nextCursor?: string }>;
+ list(params?: {
+ name?: string;
+ type?: string[];
+ cursor?: string;
+ limit?: number;
+ }): Promise<{ artifacts: ArtifactSummary[]; nextCursor?: string }>;
get(id: string): Promise<Artifact>;
update(patch: { id: string; content: unknown }): Promise<ArtifactSummary>; // for editable artifacts
}
@@ -372,12 +387,15 @@ The matching Next.js backend — filtering and pagination live on the server:
// app/api/artifacts/route.ts — list (search + type filter + paginate)
export async function GET(req: NextRequest) {
const sp = req.nextUrl.searchParams;
- const name = sp.get("name") ?? undefined; // search box
- const type = sp.getAll("type"); // category filter (repeatable)
+ const name = sp.get("name") ?? undefined; // search box
+ const type = sp.getAll("type"); // category filter (repeatable)
const cursor = sp.get("cursor") ?? undefined; // pagination
const limit = Number(sp.get("limit") ?? 20);
const { artifacts, nextCursor } = await db.listArtifacts({
- name, type: type.length ? type : undefined, cursor, limit,
+ name,
+ type: type.length ? type : undefined,
+ cursor,
+ limit,
});
// each artifact MUST include threadId
return NextResponse.json({ artifacts, nextCursor });
@@ -393,7 +411,7 @@ export async function PATCH(req: NextRequest, { params }: { params: { id: string
}
```
-The artifact `type` you store must match the `type` a registered renderer declares — it's the contract linking a stored artifact to the renderer that draws it. How artifacts get *written* (a tool call, a background job, a direct write) is up to your agent; the browser only reads, gets, and updates. For organizing the browser into groups and the per-thread Workspace rail (which does **not** require storage), see [Artifacts](/docs/agent/core-concepts/artifacts) and [`<AgentInterface>` props](/docs/agent/reference/agentinterface-props).
+The artifact `type` you store must match the `type` a registered renderer declares — it's the contract linking a stored artifact to the renderer that draws it. How artifacts get _written_ (a tool call, a background job, a direct write) is up to your agent; the browser only reads, gets, and updates. See [`<AgentInterface>` props](/docs/agent/reference/agentinterface-props) for the related API.
## 5. Framework-agnostic (plain Web `Request`/`Response`)
@@ -495,16 +513,20 @@ Because `send` is just a function returning a `Response`, you can layer logic ar
A self-hosted `<AgentInterface>`: a model reply that streams (key server-side), durable threads and artifacts against your own storage, on any server framework — because the contract is two small interfaces over plain Web `Request`/`Response`.
<Cards>
- <Card title="Adapters & formats" href="/docs/agent/reference/adapters-and-formats">
- The full `ChatLLM`, `ChatStorage`, `ThreadStorage`, `ArtifactStorage` interfaces and the `fetchLLM` / `restStorage` factories, plus every stream adapter and message format.
+ <Card
+ title="Adapters & formats"
+ href="/docs/agent/reference/adapters-and-formats"
+ >
+ The full `ChatLLM`, `ChatStorage`, `ThreadStorage`, `ArtifactStorage` interfaces and the
+ `fetchLLM` / `restStorage` factories, plus every stream adapter and message format.
</Card>
- <Card title="<AgentInterface> props" href="/docs/agent/reference/agentinterface-props">
+ <Card
+ title="<AgentInterface> props"
+ href="/docs/agent/reference/agentinterface-props"
+ >
The `llm`, `storage`, `artifactRenderers`, and `artifactCategories` props in full.
</Card>
<Card title="Conversations" href="/docs/agent/core-concepts/conversations">
How threads, messages, and streaming fit together.
</Card>
- <Card title="Artifacts" href="/docs/agent/core-concepts/artifacts">
- The artifact browser, Workspace rail, and how stored artifacts render.
- </Card>
</Cards>
diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdx
index be4f8216d..e118550e0 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/api-reference/cli.mdx
@@ -1,9 +1,9 @@
---
title: "@openuidev/cli"
-description: API reference for the OpenUI CLI to scaffold apps, mint Cloud API keys, and generate system prompts or library specs.
+description: API reference for the OpenUI CLI to scaffold apps, mint Gateway API keys, and generate system prompts or library specs.
---
-A command-line tool for scaffolding OpenUI chat apps, minting OpenUI Cloud API key, and generating system prompts, JSON schemas, or serialized library specs from library definitions.
+A command-line tool for scaffolding OpenUI chat apps, minting OpenUI Gateway API keys, and generating system prompts, JSON schemas, or serialized library specs from library definitions.
## Installation
@@ -56,10 +56,10 @@ openui create [options]
| Flag | Description |
| --------------------------------- | ----------------------------------------------------------------------------- |
| `-n, --name <string>` | Project name (interactive default: `openui-agent`) |
-| `-t, --template <template>` | AI backend: `openui-cloud` (recommended) or `openui-self-hosted` |
+| `-t, --template <template>` | AI backend: `openui-cloud` (Gateway; recommended) or `openui-self-hosted` |
| `--backend-framework <framework>` | Backend integration: `default`, `langgraph`, `vercel-ai-sdk`, or `vercel-eve` |
-| `--api-key <key>` | OpenUI Cloud API key; skips sign-in for the Cloud setup |
-| `--auth <method>` | Cloud auth method: `oauth` or `skip`; `manual` is deprecated |
+| `--api-key <key>` | OpenUI Gateway API key; skips sign-in for the Gateway setup |
+| `--auth <method>` | Gateway auth method: `oauth` or `skip`; `manual` is deprecated |
| `--skill` | Install the OpenUI agent skill for AI coding assistants |
| `--no-skill` | Skip installing the OpenUI agent skill |
| `--no-install` | Scaffold without running dependency installation |
@@ -68,7 +68,9 @@ openui create [options]
| `--no-interactive` | Fail instead of prompting for missing input |
| `--agent-name <name>` | Declare the invoking coding-agent slug (default: `unknown`) |
-When run interactively (default), the CLI prompts for any missing options, including the backend framework, then asks whether to start the development server after installing dependencies with the detected package manager. The start prompt defaults to yes; answering no preserves the existing install-and-exit behavior and prints the `cd` and dev commands. For most prototypes and evaluations, start with **OpenUI Cloud, the recommended default**: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose **self-hosted** when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.
+When run interactively (default), the CLI prompts for any missing options, including the backend framework, then asks whether to start the development server after installing dependencies with the detected package manager. The start prompt defaults to yes; answering no preserves the existing install-and-exit behavior and prints the `cd` and dev commands. For most prototypes and evaluations, start with **OpenUI Gateway, the recommended default**: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose **self-hosted** when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.
+
+`openui-cloud` remains the CLI template identifier for the Gateway-backed setup.
In non-interactive mode, dependencies are installed without starting the long-running development server. Pass `--immediate` to install, start, and open the app, or `--no-install` to scaffold only.
@@ -79,29 +81,29 @@ In non-interactive mode, dependencies are installed without starting the long-ru
1. Resolves the project name, AI setup, and backend framework
2. Copies the selected Next.js template into `<name>/`
3. Rewrites `workspace:*` dependency versions to `latest`
-4. Writes the relevant `.env` values, including Thesys sign-in/API-key setup for OpenUI Cloud
-5. Optionally installs the [OpenUI agent skill](/docs/openui-lang/agent-skill) for AI coding assistants (e.g. Claude, Cursor, Copilot)
+4. Writes the relevant `.env` values, including Thesys sign-in/API-key setup for OpenUI Gateway
+5. Optionally installs the [OpenUI agent skill](/docs/mcp#install-via-the-skills-cli-recommended) for AI coding assistants (e.g. Claude, Cursor, Copilot)
6. Auto-detects your package manager (npm, pnpm, yarn, bun)
7. Installs dependencies unless skipped, then optionally starts the development server in the generated directory
**Backend frameworks**
-| Value | OpenUI Cloud route | Self-hosted route |
+| Value | OpenUI Gateway route | Self-hosted route |
| --------------- | -------------------------------------------- | ---------------------------------------- |
| `default` | Direct OpenAI SDK Responses proxy | Direct OpenAI SDK Chat Completions proxy |
-| `langgraph` | LangGraph Agent Server + Cloud provider | LangGraph Agent Server + your provider |
-| `vercel-ai-sdk` | Vercel AI SDK Next.js agent + Cloud provider | Vercel AI SDK `streamText()` route |
-| `vercel-eve` | Vercel Eve agent + Cloud provider | Vercel Eve agent + your provider |
+| `langgraph` | LangGraph Agent Server + Gateway provider | LangGraph Agent Server + your provider |
+| `vercel-ai-sdk` | Vercel AI SDK Next.js agent + Gateway | Vercel AI SDK `streamText()` route |
+| `vercel-eve` | Vercel Eve agent + Gateway provider | Vercel Eve agent + your provider |
The CLI applies the selected framework's final route/page files, dependencies, and deployment configuration over the base template. Both Vercel AI SDK variants are standard Next.js deployments with `streamText()`, `toUIMessageStreamResponse()`, and `vercelAIAdapter()`. Both LangGraph variants separate the Agent Server described by `langgraph.json` from the Next.js frontend/proxy. The proxy uses `@openuidev/langchain`, and the browser consumes its AG-UI stream with `agUIAdapter()`. Both Eve variants wrap Next.js with `withEve()` and talk to Eve's native `/eve/v1/session*` protocol from the browser; a small client adapter maps Eve events to AG-UI for `agUIAdapter()`.
-For Cloud LangGraph and Vercel AI SDK variants, the framework owns orchestration and application tool execution. OpenUI Cloud is attached as the Responses/Chat Completions model provider and conversation store. Reports, presentations, web search, image search, and configured MCP tools remain provider-executed Cloud tools. The Eve Cloud overlay uses Cloud as the Chat Completions provider and conversation store, without those provider-executed Cloud tools. For either LangGraph template, `pnpm dev` starts the local Agent Server and Next.js together. Deploy the Next.js frontend to Vercel and point `LANGGRAPH_API_URL` at wherever the Agent Server runs. Eve embeds in the Next.js process, so `pnpm dev` is enough for both Eve variants.
+For Gateway-backed LangGraph and Vercel AI SDK variants, the framework owns orchestration and application tool execution. OpenUI Gateway is attached as the Responses/Chat Completions model provider and conversation store. Reports, presentations, web search, image search, and configured MCP tools remain Gateway-hosted tools. The Eve Gateway overlay uses Gateway as the Chat Completions provider and conversation store, without those hosted tools. For either LangGraph template, `pnpm dev` starts the local Agent Server and Next.js together. Deploy the Next.js frontend to Vercel and point `LANGGRAPH_API_URL` at wherever the Agent Server runs. Eve embeds in the Next.js process, so `pnpm dev` is enough for both Eve variants.
Every framework overlay includes a `get_weather` example backed by Open-Meteo. Ask “What’s the weather in Berlin?” to verify the selected framework’s native multi-step tool loop.
**Conversation storage**
-Every OpenUI Cloud variant uses OpenUI Cloud as its only durable conversation and artifact store. The browser connects directly through `useOpenuiCloudStorage()` with a short-lived frontend token. For default, LangGraph, and Vercel AI SDK routes, the `threadId` sent to `/api/chat` is the Cloud conversation id, and each backend appends model turns to it with `conversation: threadId` and `store: true`. The Vercel AI SDK route does not create a second store. The Eve Cloud overlay keeps that Cloud thread store and maps each Cloud `threadId` to an Eve session cursor in the browser; it does not use `/api/chat`. The Cloud LangGraph relay creates and deletes a temporary Agent Server thread for each run; configure a separate LangGraph checkpointer only when graph state, interrupts, or resumable runs must persist independently.
+Every Gateway-backed variant uses Gateway as its durable conversation and artifact store. The browser connects directly through `useOpenuiCloudStorage()` with a short-lived frontend token. For default, LangGraph, and Vercel AI SDK routes, the `threadId` sent to `/api/chat` is the Gateway conversation ID, and each backend appends model turns to it with `conversation: threadId` and `store: true`. The Vercel AI SDK route does not create a second store. The Eve Gateway overlay keeps that Gateway thread store and maps each Gateway `threadId` to an Eve session cursor in the browser; it does not use `/api/chat`. The Gateway-backed LangGraph relay creates and deletes a temporary Agent Server thread for each run; configure a separate LangGraph checkpointer only when graph state, interrupts, or resumable runs must persist independently.
The self-hosted variants do not configure durable storage. `AgentInterface` keeps messages in memory for the current page session; refreshing the page loses it. Default, Vercel AI SDK, and LangGraph send that history to `/api/chat`. The self-hosted LangGraph relay also creates and deletes a temporary Agent Server thread for each run. Eve maps follow-ups onto its session protocol for the page session only. Pass a storage implementation to `AgentInterface` and back it with your own database when persistence is required; add a LangGraph checkpointer only for graph-specific durable state.
@@ -212,7 +214,7 @@ npx @openuidev/cli@latest create --name my-app --no-skill
## `openui generate-api-key`
-Signs in with Thesys in the browser, mints an OpenUI Cloud API key, and writes it to a project env file.
+Signs in with Thesys in the browser, mints an OpenUI Gateway API key, and writes it to a project env file.
```
openui generate-api-key [options]
@@ -431,7 +433,7 @@ its events can be correlated. For `create`, analytics also include `package_mana
immediate-start selection, and best-effort dev-command start and result events. Failure events use
bounded `failure_stage`, `error_class`, and `error_code` values instead of raw error messages.
Dependency failures distinguish peer, registry, network, install-script, workspace, and
-package-compatibility errors. Process failures include duration, exit code, and signal; Cloud-auth
+package-compatibility errors. Process failures include duration, exit code, and signal; Gateway-auth
failures include a bounded auth substage and HTTP status when known; cancellations use separate
events. Dev-command events contain status, duration, exit code, and signal—not project paths,
command output, code, or environment values. Use `--no-telemetry` or `DO_NOT_TRACK=1` to disable
diff --git a/docs/content/docs/api-reference/index.mdx b/docs/content/docs/api-reference/index.mdx
index afc517163..2ec8c19b9 100644
--- a/docs/content/docs/api-reference/index.mdx
+++ b/docs/content/docs/api-reference/index.mdx
@@ -11,7 +11,7 @@ The OpenUI SDK is split into packages that build on each other:
- **`@openuidev/react-headless`** — Headless chat state management. Provides `ChatProvider`, thread/message hooks, streaming protocol adapters (OpenAI, Vercel AI SDK, AG-UI), and message format converters. Use this when you want full control over your chat UI.
-- **`@openuidev/react-ui`** — `AgentInterface`, a ready-to-use artifact chat surface with thread history, plus two built-in component libraries (general-purpose and chat-optimized). Depends on both packages above. Use this for the fastest path to a working chat interface.
+- **`@openuidev/react-ui`** — `AgentInterface`, a ready-to-use chat surface with thread history and support for OpenUI component libraries. Depends on both packages above. Use this for the fastest path to a working chat interface.
- **`@openuidev/assistant-ui`** — OpenUI tool renderers, model instructions, and toolkit wiring for applications built with assistant-ui. The core integration supports any assistant-ui runtime; an optional `/ai-sdk` subpath adds Vercel AI SDK continuation behavior.
@@ -100,7 +100,7 @@ The OpenUI SDK is split into packages that build on each other:
Development-only floating widget surfacing captured events with error messages and stack traces.
</Card>
<Card title="@openuidev/cli" href="/docs/api-reference/cli">
- openui create (scaffold a Next.js app), openui generate-api-key (mint a Cloud key), and openui generate (system prompt + library spec from a library
+ openui create (scaffold a Next.js app), openui generate-api-key (mint a Gateway key), and openui generate (system prompt + library spec from a library
definition).
</Card>
</Cards>
diff --git a/docs/content/docs/api-reference/meta.json b/docs/content/docs/api-reference/meta.json
index 2ad690e79..6bdb9bdee 100644
--- a/docs/content/docs/api-reference/meta.json
+++ b/docs/content/docs/api-reference/meta.json
@@ -6,10 +6,10 @@
"react-lang",
"react-headless",
"react-ui",
+ "assistant-ui",
+ "langchain",
"react-email",
- "cli",
"devtools",
- "langchain",
- "assistant-ui"
+ "cli"
]
}
diff --git a/docs/content/docs/api-reference/react-headless.mdx b/docs/content/docs/api-reference/react-headless.mdx
index f191562fd..ee902f6f3 100644
--- a/docs/content/docs/api-reference/react-headless.mdx
+++ b/docs/content/docs/api-reference/react-headless.mdx
@@ -10,6 +10,8 @@ Use this package when you want headless chat state + streaming, with or without
```ts
import {
ChatProvider,
+ fetchLLM,
+ restStorage,
useThread,
useThreadList,
openAIAdapter,
@@ -25,31 +27,57 @@ import {
MessageProvider,
useMessage,
EventType,
+ type ArtifactCategory,
+ type ArtifactRendererConfig,
+ type ChatLLM,
+ type ChatStorage,
} from "@openuidev/react-headless";
```
## `ChatProvider`
-Provides chat/thread state to UI components.
+Provides chat, thread, streaming, and optional artifact state to its children.
```ts
-type ChatProviderProps = ThreadApiConfig &
- ChatApiConfig & {
- streamProtocol?: StreamProtocolAdapter;
- messageFormat?: MessageFormat;
- children: React.ReactNode;
- };
+interface ChatProviderProps {
+ llm: ChatLLM;
+ storage?: ChatStorage;
+ artifactRenderers?: ReadonlyArray<ArtifactRendererConfig>;
+ artifactCategories?: ArtifactCategory[];
+ artifactAutoOpen?: boolean;
+ children: React.ReactNode;
+}
```
-`ThreadApiConfig`:
+`llm` is required. It sends messages to your backend and specifies the adapter used to parse the
+streaming response. Create one with `fetchLLM()` or implement the `ChatLLM` interface yourself.
+
+```tsx
+const llm = fetchLLM({
+ url: "/api/chat",
+ streamAdapter: agUIAdapter(),
+});
+
+function App() {
+ return (
+ <ChatProvider llm={llm}>
+ <YourChatUI />
+ </ChatProvider>
+ );
+}
+```
-- Provide `threadApiUrl`, **or**
-- Provide custom handlers: `fetchThreadList`, `createThread`, `deleteThread`, `updateThread`, `loadThread`
+`storage` is optional. Without it, conversations are stored in memory and are cleared when the page
+reloads. Use `restStorage()` for the built-in REST conventions, or provide your own `ChatStorage`
+implementation:
-`ChatApiConfig`:
+```tsx
+const storage = restStorage({ baseUrl: "/api/threads" });
-- Provide `apiUrl`, **or**
-- Provide `processMessage({ threadId, messages, abortController })`
+<ChatProvider llm={llm} storage={storage}>
+ <YourChatUI />
+</ChatProvider>;
+```
## `useThread()`
@@ -94,7 +122,7 @@ function useThreadList<T>(selector: (state: ThreadListState & ThreadListActions)
Access the current message inside a message component.
```ts
-function useMessage(): Message;
+function useMessage(): { message: Message };
```
Provided via `MessageProvider` / `MessageContext`.
diff --git a/docs/content/docs/architecture.mdx b/docs/content/docs/architecture.mdx
new file mode 100644
index 000000000..ea67412ae
--- /dev/null
+++ b/docs/content/docs/architecture.mdx
@@ -0,0 +1,146 @@
+---
+title: How OpenUI works
+---
+
+Most AI applications are limited to returning text as Markdown or rendering pre-built UI responses. Markdown isn't interactive, and pre-built responses are rigid—they don't adapt to the context of the conversation.
+
+Generative UI fundamentally changes this relationship. Instead of merely providing content, the AI composes the interface itself. It dynamically selects, configures, and combines components from a predefined library to create a purpose-built interface tailored to the user's immediate request, whether that's an interactive chart, a complex form, or a multi-tab dashboard.
+
+[Try demo](/chat)
+
+## How it works
+
+<img
+ src="/images/openui-architecture.svg"
+ alt="A user request travels from an application through OpenUI Gateway to a model provider. The corrected OpenUI Lang stream returns to a renderer, while Observability traces the flow."
+ className="not-prose my-8 h-auto w-full overflow-hidden rounded-2xl"
+/>
+
+Your application provides a library of components and the relevant context. OpenUI Gateway sends the request to a model and corrects invalid output. The model uses OpenUI Lang to describe the interface, and the OpenUI Lang Renderer renders it using the provided library. Observability traces this process so you can find failures and improve reliability.
+
+## OpenUI Lang
+
+OpenUI Lang is a compact, line-oriented language for describing generated interfaces. You define the components the model can use in a component library:
+
+```tsx
+import { createLibrary } from "@openuidev/react-lang";
+import { Chart, Metric, Stack } from "./components";
+
+export const library = createLibrary({
+ root: "Stack",
+ components: [Stack, Metric, Chart],
+});
+```
+
+OpenUI turns the component library into a system prompt that describes the available components and their properties. The model uses these instructions to generate OpenUI Lang, which streams to your application and renders with your components.
+
+Learn more in the [OpenUI Lang documentation](/docs/openui-lang).
+
+## Gateway
+
+OpenUI Gateway is a reliability layer between your application and AI model providers. It routes requests across providers, validates generated interfaces, and corrects invalid model output before it reaches your application.
+
+<div
+ className="not-prose my-6 rounded-2xl border border-fd-border bg-fd-muted/20 p-4 sm:p-6"
+ role="img"
+ aria-label="A request travels from an application through OpenUI Gateway to an LLM. The LLM streams generated UI through OpenUI Gateway, which validates the stream continuously, fixes errors as they are detected, and forwards the validated stream to the application."
+>
+ <div className="grid items-stretch gap-3 md:grid-cols-[minmax(0,1fr)_7rem_minmax(0,1.15fr)_7rem_minmax(0,1fr)]">
+ <div className="flex min-h-40 flex-col rounded-xl border border-fd-border bg-fd-background p-4">
+ <div className="text-sm font-semibold text-fd-foreground">Your application</div>
+ <div className="mt-4 flex flex-1 flex-col gap-2 rounded-lg border border-fd-border bg-fd-muted/40 p-3">
+ <div className="h-2 w-2/3 rounded-full bg-fd-muted-foreground/25" />
+ <div className="h-2 w-1/2 rounded-full bg-fd-muted-foreground/20" />
+ <div className="mt-2 flex-1 rounded-md border border-[color:color-mix(in_srgb,var(--openui-text-success-primary)_25%,transparent)] bg-[var(--openui-success-background)] p-2">
+ <div className="text-xs font-medium text-[var(--openui-text-success-primary)]">
+ Generated interface
+ </div>
+ <div className="mt-2 h-2 w-full rounded-full bg-fd-muted-foreground/20" />
+ <div className="mt-2 h-2 w-3/4 rounded-full bg-fd-muted-foreground/20" />
+ </div>
+ </div>
+ </div>
+
+ <div className="flex items-center justify-around py-1 text-xs font-medium text-fd-muted-foreground md:hidden">
+ <div className="flex flex-col items-center gap-1">
+ <span>Request</span>
+ <span className="text-lg" aria-hidden="true">↓</span>
+ </div>
+ <div className="flex flex-col items-center gap-1 text-[var(--openui-text-success-primary)]">
+ <span aria-hidden="true">↑</span>
+ <span>Validated UI</span>
+ </div>
+ </div>
+ <div className="hidden flex-col items-center justify-center gap-10 text-xs font-medium md:flex">
+ <div className="whitespace-nowrap text-fd-muted-foreground">Request →</div>
+ <div className="whitespace-nowrap text-[var(--openui-text-success-primary)]">
+ ← Validated UI
+ </div>
+ </div>
+
+ <div className="flex min-h-40 flex-col rounded-xl border border-[var(--openui-text-purple-primary)] bg-[var(--openui-purple-background)] p-4 shadow-sm">
+ <div className="text-sm font-semibold text-fd-foreground">OpenUI Gateway</div>
+ <div className="text-xs font-medium text-[var(--openui-text-purple-primary)]">
+ Reliability middleware
+ </div>
+ <div className="mt-4 flex flex-1 flex-col justify-center gap-2">
+ <div className="rounded-lg border border-[color:color-mix(in_srgb,var(--openui-text-purple-primary)_30%,transparent)] bg-fd-background/70 px-3 py-2 text-xs font-medium text-fd-foreground">
+ Validate generated UI
+ </div>
+ <div className="rounded-lg border border-[color:color-mix(in_srgb,var(--openui-text-purple-primary)_30%,transparent)] bg-fd-background/70 px-3 py-2 text-xs font-medium text-fd-foreground">
+ Fix errors automatically
+ </div>
+ </div>
+ </div>
+
+ <div className="flex items-center justify-around py-1 text-xs font-medium text-fd-muted-foreground md:hidden">
+ <div className="flex flex-col items-center gap-1">
+ <span>Model request</span>
+ <span className="text-lg" aria-hidden="true">↓</span>
+ </div>
+ <div className="flex flex-col items-center gap-1 text-[var(--openui-text-alert-primary)]">
+ <span aria-hidden="true">↑</span>
+ <span>Generated UI</span>
+ </div>
+ </div>
+ <div className="hidden flex-col items-center justify-center gap-10 text-xs font-medium text-fd-muted-foreground md:flex">
+ <div className="whitespace-nowrap">Model request →</div>
+ <div className="whitespace-nowrap text-[var(--openui-text-alert-primary)]">
+ ← Generated UI
+ </div>
+ </div>
+
+ <div className="flex min-h-40 flex-col rounded-xl border border-fd-border bg-fd-background p-4">
+ <div className="text-sm font-semibold text-fd-foreground">LLM</div>
+ <div className="text-xs text-fd-muted-foreground">OpenAI, Anthropic, and others</div>
+ <div className="mt-4 flex flex-1 items-center justify-center rounded-lg border border-[color:color-mix(in_srgb,var(--openui-text-alert-primary)_25%,transparent)] bg-[var(--openui-alert-background)] px-3 text-center text-xs font-medium text-[var(--openui-text-alert-primary)]">
+ Generate interface
+ </div>
+ </div>
+ </div>
+</div>
+
+### Integration options
+
+OpenUI Gateway provides two OpenAI-compatible APIs:
+
+- **[Chat Completions](/docs/gateway/api/chat-completions):** A drop-in endpoint for applications that use the OpenAI Chat Completions API.
+- **[Responses API](/docs/gateway/api/responses):** Build stateful model interactions with persistence and hosted tools.
+
+Learn more in the [OpenUI Gateway documentation](/docs/gateway).
+
+## Observability
+
+Generative UI depends on model providers and model-generated output. Providers can fail, and models can generate invalid or incomplete interfaces.
+
+OpenUI Observability helps you find these failures in production, trace affected generations, and identify recurring patterns. These insights help you improve your system prompt, component library, and model selection.
+
+<img
+ src="/images/openui-lang/reliability-dashboard.png"
+ alt="OpenUI Observability dashboard showing generation errors and affected interfaces"
+ className="w-full rounded-lg border"
+/>
+
+Observability identifies errors but does not correct generated output. Without OpenUI Gateway's validation and correction layer, invalid output can reach users as an incomplete or broken interface.
+
+Learn more in the [OpenUI Observability documentation](/docs/observability).
diff --git a/docs/content/docs/build-agents/assistant-ui.mdx b/docs/content/docs/build-agents/assistant-ui.mdx
new file mode 100644
index 000000000..01f7ed235
--- /dev/null
+++ b/docs/content/docs/build-agents/assistant-ui.mdx
@@ -0,0 +1,34 @@
+---
+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.
+
+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.
+
+## Render OpenUI Lang
+
+```tsx title="src/components/assistant-message.tsx"
+"use client";
+
+import { type TextMessagePartProps } from "@assistant-ui/react";
+import { Renderer } from "@openuidev/react-lang";
+import { openuiLibrary } from "@openuidev/react-ui";
+
+function OpenUIRenderer({ text, status }: TextMessagePartProps) {
+ return (
+ <Renderer response={text} library={openuiLibrary} isStreaming={status.type === "running"} />
+ );
+}
+```
+
+Then update the existing message-parts configuration:
+
+```tsx
+<MessagePrimitive.Parts components={{ Text: OpenUIRenderer }} />
+```
+
+`text` is the accumulated agent response supplied by assistant-ui.
+
+Continue with [The Renderer](/docs/openui-lang/renderer) for the complete API.
diff --git a/docs/content/docs/build-agents/backend-setup.mdx b/docs/content/docs/build-agents/backend-setup.mdx
new file mode 100644
index 000000000..9f28768ba
--- /dev/null
+++ b/docs/content/docs/build-agents/backend-setup.mdx
@@ -0,0 +1,80 @@
+---
+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/copilotkit.mdx b/docs/content/docs/build-agents/copilotkit.mdx
new file mode 100644
index 000000000..85be2f93d
--- /dev/null
+++ b/docs/content/docs/build-agents/copilotkit.mdx
@@ -0,0 +1,36 @@
+---
+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.
+
+## Render OpenUI Lang
+
+```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";
+
+function OpenUIRenderer({ content }: { content: string }) {
+ return <Renderer response={content} library={openuiLibrary} />;
+}
+
+export function Chat() {
+ return (
+ <CopilotChat
+ messageView={{
+ assistantMessage: {
+ markdownRenderer: OpenUIRenderer,
+ },
+ }}
+ />
+ );
+}
+```
+
+`content` is the accumulated agent response supplied by CopilotKit.
+
+Continue with [The Renderer](/docs/openui-lang/renderer) for the complete API.
diff --git a/docs/content/docs/build-agents/custom-chat-ui.mdx b/docs/content/docs/build-agents/custom-chat-ui.mdx
new file mode 100644
index 000000000..0dce263b7
--- /dev/null
+++ b/docs/content/docs/build-agents/custom-chat-ui.mdx
@@ -0,0 +1,23 @@
+---
+title: Custom Chat UI
+description: Render OpenUI Lang in an existing chat interface.
+---
+
+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.
+
+## Render OpenUI Lang
+
+In the assistant-message component, render the streamed response with `<Renderer />` instead of the Markdown renderer:
+
+```tsx title="src/components/assistant-message.tsx"
+import { Renderer } from "@openuidev/react-lang";
+import { library } from "@/lib/openui";
+
+export function AssistantMessage({ content, isStreaming }) {
+ 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.
+
+Continue with [The Renderer](/docs/openui-lang/renderer) for the complete API.
diff --git a/docs/content/docs/build-agents/index.mdx b/docs/content/docs/build-agents/index.mdx
new file mode 100644
index 000000000..bfd13db82
--- /dev/null
+++ b/docs/content/docs/build-agents/index.mdx
@@ -0,0 +1,46 @@
+---
+title: Overview
+description: Add OpenUI Lang to an existing agent framework or chat UI.
+---
+
+Add Generative UI to an agent built with any chat framework. Keep the existing conversation experience and render agent responses with OpenUI Lang.
+
+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.
+
+Every integration has two parts:
+
+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.
+
+<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."
+/>
+
+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.
+
+## 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>
+</Cards>
+
+## Choose a chat UI
+
+<Cards>
+ <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.
+ </Card>
+ <Card title="CopilotKit" href="/docs/build-agents/copilotkit">
+ Add OpenUI rendering to an application whose agent experience 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>
+</Cards>
+
+Starting without an existing chat UI? Use [Agent Interface](/docs/agent/getting-started/introduction) for a complete React chat experience.
diff --git a/docs/content/docs/build-agents/meta.json b/docs/content/docs/build-agents/meta.json
new file mode 100644
index 000000000..025af1f10
--- /dev/null
+++ b/docs/content/docs/build-agents/meta.json
@@ -0,0 +1,12 @@
+{
+ "title": "Build Agents",
+ "root": true,
+ "pages": [
+ "index",
+ "backend-setup",
+ "---Chat UIs---",
+ "assistant-ui",
+ "copilotkit",
+ "custom-chat-ui"
+ ]
+}
diff --git a/docs/content/docs/gateway/api/chat-completions.mdx b/docs/content/docs/gateway/api/chat-completions.mdx
new file mode 100644
index 000000000..f7fccb4d2
--- /dev/null
+++ b/docs/content/docs/gateway/api/chat-completions.mdx
@@ -0,0 +1,72 @@
+---
+title: Chat Completions
+---
+
+Gateway provides OpenAI compatible Chat Completions API endpoints, letting you use multiple AI providers through a familiar interface. You can use existing OpenAI client libraries, switch to Gateway with a URL change, and keep your current tools and workflows without code rewrites.
+
+The Chat Completions API implements the same specification as the [**OpenAI Chat Completions API**](https://platform.openai.com/docs/api-reference/chat).
+
+**Endpoint:** POST [https://api.thesys.dev/v1/embed/chat/completions](https://api.thesys.dev/v1/embed/chat/completions)
+
+## Configure the client
+
+```ts title="lib/gateway.ts"
+import OpenAI from "openai";
+
+export const gateway = new OpenAI({
+ apiKey: process.env.THESYS_API_KEY,
+ baseURL: "https://api.thesys.dev/v1/embed",
+});
+```
+
+See [Authentication](/docs/gateway/authentication) before using the client in a server route.
+
+## Generate OpenUI Lang
+
+Configure the system message for OpenUI generation, then send the same messages shape used by the OpenAI SDK:
+
+```ts title="server.ts"
+import { generateSystemPrompt } from "@openuidev/lang-core";
+import { gateway } from "./lib/gateway";
+import library from "./openui.spec.json";
+
+const completion = await gateway.chat.completions.create({
+ model: "openai/gpt-5",
+ messages: [
+ { role: "system", content: generateSystemPrompt({ cloud: true, library }) },
+ { role: "user", content: "Compare quarterly revenue by region." },
+ ],
+ stream: true,
+});
+```
+
+The assistant message contains OpenUI Lang. When the request is configured for OpenUI generation, the Gateway validates and corrects that language while it streams.
+
+## Plain text requests
+
+The endpoint also supports ordinary model traffic. Send your own system prompt without OpenUI generation instructions, and the Gateway forwards a text-oriented request without applying OpenUI Lang correction.
+
+```ts
+const completion = await gateway.chat.completions.create({
+ model: "anthropic/claude-sonnet-5",
+ messages: [{ role: "user", content: "Summarize this support ticket." }],
+});
+```
+
+Unknown providers can route through OpenRouter where supported. Use [Models](/docs/gateway/models) for the standard provider naming convention.
+
+## Stream to an agent UI
+
+Relay the server response without changing its SSE shape. In the browser, configure [Agent Interface adapters and message formats](/docs/agent/reference/adapters-and-formats) for the Chat Completions stream.
+
+Chat Completions is message-based. Your application owns conversation history and sends the relevant `system`, `user`, `assistant`, and `tool` messages on every turn. Use the [Responses API](/docs/gateway/api/responses) when you want Gateway-managed persistent conversations.
+
+## Function tools
+
+Chat Completions returns function tool calls to the application; it does not execute them. Run the standard loop:
+
+1. Send messages and function declarations.
+2. Read `tool_calls` from the assistant message.
+3. Execute each function in your application.
+4. Append the assistant tool-call message and each tool result.
+5. Continue until the model returns the final OpenUI Lang response.
diff --git a/docs/content/docs/gateway/api/conversations.mdx b/docs/content/docs/gateway/api/conversations.mdx
new file mode 100644
index 000000000..f52b944d6
--- /dev/null
+++ b/docs/content/docs/gateway/api/conversations.mdx
@@ -0,0 +1,63 @@
+---
+title: Conversations API
+description: Create persistent Gateway conversations and use them with the Responses API.
+---
+
+The Conversations API stores persistent threads and their items. Responses can read and append to a conversation so the application does not need to resend the full history on every turn.
+
+**Base URL:** `https://api.thesys.dev/v1`
+
+```ts title="lib/conversations.ts"
+import OpenAI from "openai";
+
+export const conversations = new OpenAI({
+ apiKey: process.env.THESYS_API_KEY,
+ baseURL: "https://api.thesys.dev/v1",
+});
+```
+
+## Create and use a conversation
+
+```ts
+import { generateSystemPrompt } from "@openuidev/lang-core";
+import library from "./openui.spec.json";
+
+const conversation = await conversations.conversations.create({
+ metadata: { workspace: "acme" },
+});
+
+const response = await gateway.responses.create({
+ model: "openai/gpt-5",
+ conversation: conversation.id,
+ input: "Compare quarterly revenue by region.",
+ instructions: generateSystemPrompt({ cloud: true, library }),
+ store: true,
+ stream: true,
+});
+```
+
+Later Responses calls can reuse `conversation.id` and send only the new turn.
+
+## Read conversation items
+
+```ts
+const page = await conversations.conversations.items.list(conversation.id, {
+ order: "asc",
+ limit: 100,
+});
+
+for (const item of page.data) {
+ console.log(item.type, item.id);
+}
+```
+
+## Endpoint summary
+
+| Method | Path | Purpose |
+| ------------------------- | ----------------------------------------------------- | ------------------------------------------- |
+| `GET` / `POST` | `/v1/conversations` | List or create conversations. |
+| `GET` / `POST` / `DELETE` | `/v1/conversations/{conversation_id}` | Retrieve, update, or delete a conversation. |
+| `GET` / `POST` | `/v1/conversations/{conversation_id}/items` | List or add conversation items. |
+| `GET` / `DELETE` | `/v1/conversations/{conversation_id}/items/{item_id}` | Retrieve or delete one item. |
+
+Server calls use the API key described in [Authentication](/docs/gateway/authentication). Browser access should use a scoped, short-lived frontend token rather than the server key.
diff --git a/docs/content/docs/gateway/api/responses/hosted-tools.mdx b/docs/content/docs/gateway/api/responses/hosted-tools.mdx
new file mode 100644
index 000000000..25d43fceb
--- /dev/null
+++ b/docs/content/docs/gateway/api/responses/hosted-tools.mdx
@@ -0,0 +1,39 @@
+---
+title: Hosted Tools
+description: Enable Gateway-hosted search and MCP tools in Responses API requests.
+---
+
+The Responses API can run supported tools inside the Gateway. Application function tools remain in your backend so your authorization and business logic stay under application control.
+
+| Capability | Declaration | Runs in |
+| -------------------- | ------------------------------------------- | ------------ |
+| Web search | `{ type: "web_search" }` | Gateway |
+| Image search | `{ type: "image_search" }` | Gateway |
+| Remote MCP | `{ type: "mcp", server_label, server_url }` | Gateway |
+| Application function | `{ type: "function", name, parameters }` | Your backend |
+
+```ts
+import { generateSystemPrompt } from "@openuidev/lang-core";
+import type { Tool } from "openai/resources/responses/responses";
+import library from "./openui.spec.json";
+
+const response = await gateway.responses.create({
+ model: "openai/gpt-5",
+ input: "Research the market and summarize the most important changes.",
+ instructions: generateSystemPrompt({ cloud: true, library }),
+ tools: [
+ { type: "web_search" },
+ { type: "image_search" } as unknown as Tool,
+ {
+ type: "mcp",
+ server_label: "deepwiki",
+ server_url: "https://mcp.deepwiki.com/mcp",
+ } as unknown as Tool,
+ ],
+ stream: true,
+});
+```
+
+The casts are required while image search and MCP remain Gateway extensions to the OpenAI SDK's published tool union.
+
+For a function tool, execute each returned `function_call` in your backend and continue the response with a matching `function_call_output`.
diff --git a/docs/content/docs/gateway/api/responses/index.mdx b/docs/content/docs/gateway/api/responses/index.mdx
new file mode 100644
index 000000000..0301d43b3
--- /dev/null
+++ b/docs/content/docs/gateway/api/responses/index.mdx
@@ -0,0 +1,71 @@
+---
+title: Responses API
+description: Generate corrected OpenUI Lang with persistent conversations and hosted tools.
+---
+
+Gateway provides OpenAI-compatible Responses API endpoints, letting you use multiple AI providers through a familiar interface. You can use existing OpenAI client libraries, switch to Gateway with a URL change, and keep your current tools and workflows without code rewrites.
+
+The Responses API implements the same specification as the [**OpenAI Responses API**](https://platform.openai.com/docs/api-reference/responses).
+
+**Endpoint:** POST [https://api.thesys.dev/v1/embed/responses](https://api.thesys.dev/v1/embed/responses)
+
+## Configure the client
+
+```ts title="lib/gateway.ts"
+import OpenAI from "openai";
+
+export const gateway = new OpenAI({
+ apiKey: process.env.THESYS_API_KEY,
+ baseURL: "https://api.thesys.dev/v1/embed",
+});
+```
+
+## Make a request
+
+```ts title="server.ts"
+import { generateSystemPrompt } from "@openuidev/lang-core";
+import { gateway } from "./lib/gateway";
+import library from "./openui.spec.json";
+
+const response = await gateway.responses.create({
+ model: "openai/gpt-5",
+ input: "Compare quarterly revenue by region.",
+ instructions: generateSystemPrompt({ cloud: true, library }),
+ stream: true,
+});
+```
+
+Relay the response stream through your server route without changing its event shape. In the browser, configure the appropriate [Agent Interface adapter and message format](/docs/agent/reference/adapters-and-formats) for the Responses stream.
+
+## Conversation history
+
+Choose one state model for each application flow:
+
+| Pattern | Use it when |
+| ------------------------------------ | -------------------------------------------------------------- |
+| Send the full history in `input` | Your application owns all message storage. |
+| Set `previous_response_id` | You want to chain stored responses without a named thread. |
+| Set `conversation` and `store: true` | You want a persistent thread managed by the Conversations API. |
+
+```ts
+const first = await gateway.responses.create({
+ model: "openai/gpt-5",
+ input: "Compare quarterly revenue by region.",
+ instructions: generateSystemPrompt({ cloud: true, library }),
+ store: true,
+});
+
+const followUp = await gateway.responses.create({
+ model: "openai/gpt-5",
+ input: "Focus on Europe and explain the change.",
+ instructions: generateSystemPrompt({ cloud: true, library }),
+ previous_response_id: first.id,
+ store: true,
+});
+```
+
+For named threads, see the [Conversations API](/docs/gateway/api/conversations).
+
+## Tools
+
+Responses supports Gateway-hosted tools and application-run function tools. See [Hosted Tools](/docs/gateway/api/responses/hosted-tools) for declarations and execution ownership.
diff --git a/docs/content/docs/gateway/api/responses/meta.json b/docs/content/docs/gateway/api/responses/meta.json
new file mode 100644
index 000000000..85ecb1a6d
--- /dev/null
+++ b/docs/content/docs/gateway/api/responses/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Responses API",
+ "collapsible": false,
+ "pages": ["index", "hosted-tools"]
+}
diff --git a/docs/content/docs/gateway/authentication.mdx b/docs/content/docs/gateway/authentication.mdx
new file mode 100644
index 000000000..d99682d21
--- /dev/null
+++ b/docs/content/docs/gateway/authentication.mdx
@@ -0,0 +1,92 @@
+---
+title: Authentication
+description: Authenticate server-side generation and scoped browser access to Gateway conversations.
+---
+
+Gateway applications use two credential types with different trust boundaries. Inference API keys authenticate requests from your backend and must never be exposed to the browser. Frontend tokens are short-lived credentials scoped to a specific user, allowing the browser to access that user's conversations directly.
+
+## Inference API key
+
+Create an inference API key in the [Thesys Console](https://console.thesys.dev/keys) and store it in your server environment as `THESYS_API_KEY`.
+
+Server requests authenticate with a bearer token:
+
+```http
+Authorization: Bearer $THESYS_API_KEY
+```
+
+Use the inference API key for Responses, Chat Completions, Conversations operations, and frontend-token minting. Never include it in a client bundle or send it to the browser.
+
+```ts
+import OpenAI from "openai";
+
+export const gateway = new OpenAI({
+ apiKey: process.env.THESYS_API_KEY,
+ baseURL: "https://api.thesys.dev/v1/embed",
+});
+```
+
+## Frontend tokens
+
+Applications that access persistent conversations directly from the browser use short-lived frontend tokens. Each token is scoped to a specific user, so your backend must provide a `user_id` when minting it.
+
+<Mermaid
+ chart={`
+sequenceDiagram
+ participant Browser
+ participant App as Application backend
+ participant Gateway as OpenUI Gateway
+
+ Browser->>App: Request frontend token
+ App->>Gateway: Mint token with inference API key
+ Gateway-->>App: Short-lived scoped token
+ App-->>Browser: Frontend token
+ Browser->>Gateway: Read allowed conversations
+
+`}
+/>
+
+### Mint a frontend token
+
+Mint the token from your backend using the inference API key:
+
+```ts title="server.ts"
+const response = await fetch("https://api.thesys.dev/v1/frontend-tokens", {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${process.env.THESYS_API_KEY}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({ user_id: userId }),
+ cache: "no-store",
+ signal,
+});
+
+if (!response.ok) {
+ throw new Error("Failed to create a frontend token");
+}
+
+const { token, expires_at } = await response.json();
+```
+
+Derive `userId` from the authenticated server session. Do not accept it directly from the browser, because the resulting token grants access to that user's conversations.
+
+Return the short-lived `token` to the browser. Never return `THESYS_API_KEY`.
+
+### Call the Conversations API from the browser
+
+The frontend token lets the browser call the [Conversations API](/docs/gateway/api/conversations) directly:
+
+```ts title="client.ts"
+const response = await fetch("https://api.thesys.dev/v1/conversations", {
+ headers: {
+ Authorization: `Bearer ${frontendToken}`,
+ },
+});
+
+const conversations = await response.json();
+```
+
+Use the frontend token for Conversations endpoints only. When it expires, request a new token from your backend.
+
+Continue with the [Conversations API](/docs/gateway/api/conversations) for the storage endpoints that use these credentials.
diff --git a/docs/content/docs/gateway/byok.mdx b/docs/content/docs/gateway/byok.mdx
new file mode 100644
index 000000000..261e601b6
--- /dev/null
+++ b/docs/content/docs/gateway/byok.mdx
@@ -0,0 +1,20 @@
+---
+title: BYOK
+description: Route Gateway requests through your own OpenAI, Anthropic, or Google provider key.
+---
+
+Bring your own key (BYOK) lets an organization use its existing provider account while keeping the Gateway API, OpenUI Lang correction, and routing layer in the request path.
+
+## Add a provider key
+
+Add an OpenAI, Anthropic, or Google key from the [BYOK page in the Thesys Console](https://console.thesys.dev/byok). Only organization administrators can add or update provider credentials. Once configured, members of the organization can use models from that provider with the normal `{provider}/{model}` identifier.
+
+BYOK is available on every plan, including the free tier.
+
+## Provider-specific routing and billing
+
+A key applies only to its matching provider. For example, an OpenAI key is used for `openai/*` requests. Requests sent to another provider use managed Gateway credits unless that provider also has a configured key.
+
+Provider keys are not exposed to application clients. Applications continue to authenticate to the Gateway with their Gateway API key.
+
+See [Models](/docs/gateway/models) for identifiers and [Pricing](/docs/gateway/pricing-credits) for how managed usage and BYOK relate.
diff --git a/docs/content/docs/gateway/generate-openui-lang.mdx b/docs/content/docs/gateway/generate-openui-lang.mdx
new file mode 100644
index 000000000..cc4a695a3
--- /dev/null
+++ b/docs/content/docs/gateway/generate-openui-lang.mdx
@@ -0,0 +1,118 @@
+---
+title: Generative UI Quickstart
+description: Generate validated OpenUI Lang through OpenUI Gateway.
+---
+
+OpenUI Gateway natively supports Generative UI with OpenUI Lang. It validates model output against your component library, corrects eligible errors as responses stream, and automatically retries requests with other providers when one is unavailable.
+
+<img
+ src="/images/openui-gateway-architecture.svg"
+ alt="A user request travels from an application through the highlighted OpenUI Gateway to a model provider. The corrected OpenUI Lang stream returns to a renderer."
+ className="not-prose my-8 h-auto w-full overflow-hidden rounded-2xl"
+/>
+
+## 1. Create a component library
+
+Create a library containing the components the model can use:
+
+```tsx title="src/lib/openui.tsx"
+import { createLibrary } from "@openuidev/react-lang";
+import { Chart, Metric, Stack } from "./components";
+
+export const library = createLibrary({
+ root: "Stack",
+ components: [Stack, Metric, Chart],
+});
+```
+
+Learn more about defining components in the [OpenUI Lang documentation](/docs/openui-lang/defining-components).
+
+## 2. Export the library specification
+
+Use the OpenUI CLI to serialize the component library for your server:
+
+```bash
+npx @openuidev/cli@latest generate src/lib/openui.tsx --spec --out src/lib/openui.spec.json
+```
+
+The generated specification describes the available components and their properties. Regenerate it whenever the component library changes.
+
+## 3. Create an inference API key
+
+Create an inference key in the [Thesys Console](https://console.thesys.dev/keys), then add it to your server environment:
+
+```bash
+THESYS_API_KEY=sk-th-your-key-here
+```
+
+Keep this key on the server and never expose it to browser code.
+
+## 4. Choose a generation endpoint
+
+Both endpoints accept a system prompt generated from the exported library specification.
+
+```ts title="server.ts" tab="Chat Completions" tab-group="gateway-endpoint"
+import OpenAI from "openai";
+import { generateSystemPrompt } from "@openuidev/lang-core";
+import library from "./openui.spec.json";
+
+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: generateSystemPrompt({ cloud: true, library }) },
+ { role: "user", content: "Compare quarterly revenue by region." },
+ ],
+ stream: true,
+});
+```
+
+```ts title="server.ts" tab="Responses API" tab-group="gateway-endpoint"
+import OpenAI from "openai";
+import { generateSystemPrompt } from "@openuidev/lang-core";
+import library from "./openui.spec.json";
+
+const gateway = new OpenAI({
+ apiKey: process.env.THESYS_API_KEY,
+ baseURL: "https://api.thesys.dev/v1/embed",
+});
+
+const response = await gateway.responses.create({
+ model: "openai/gpt-5",
+ input: "Compare quarterly revenue by region.",
+ instructions: generateSystemPrompt({ cloud: true, library }),
+ stream: true,
+});
+```
+
+Gateway validates the generated OpenUI Lang against the same library specification and corrects invalid output while it streams.
+
+## 5. Render the UI
+
+Pass the accumulated OpenUI Lang text to `<Renderer />`. Set `isStreaming` until the server stream closes.
+
+```tsx title="src/components/generated-interface.tsx"
+"use client";
+
+import { Renderer } from "@openuidev/react-lang";
+import { library } from "@/lib/openui";
+
+export function GeneratedInterface({ response, isStreaming }) {
+ return (
+ <Renderer
+ response={response}
+ library={library}
+ isStreaming={isStreaming}
+ onAction={(action) => console.log(action)}
+ />
+ );
+}
+```
+
+The renderer displays the interface progressively as the Gateway response arrives.
+
+Continue with the [Chat Completions](/docs/gateway/api/chat-completions) or [Responses API](/docs/gateway/api/responses) documentation for endpoint-specific options.
diff --git a/docs/content/docs/gateway/index.mdx b/docs/content/docs/gateway/index.mdx
new file mode 100644
index 000000000..6c421d55e
--- /dev/null
+++ b/docs/content/docs/gateway/index.mdx
@@ -0,0 +1,82 @@
+---
+title: Introduction
+description: Access models across providers with automatic failover and correction for generated interfaces.
+customHeader: true
+full: true
+---
+<div className="not-prose mb-14 grid items-start gap-10 lg:grid-cols-[minmax(0,0.9fr)_minmax(0,1.1fr)] lg:gap-14">
+ <div className="pt-4 lg:pt-10">
+ <h1 className="m-0 text-5xl font-semibold tracking-tight text-fd-foreground sm:text-5xl">
+ OpenUI Gateway
+ </h1>
+ <p className="mt-6 text-lg leading-8 text-fd-muted-foreground">
+ OpenUI Gateway provides a unified API to access models across different providers through a
+ single endpoint. It adds reliability to OpenUI Lang generation with automatic failover and
+ model-output correction.
+ </p>
+ <div className="mt-8 flex flex-wrap gap-3">
+ <a
+ href="/docs/gateway/generate-openui-lang"
+ className="rounded-lg bg-fd-primary px-5 py-3 text-sm font-medium text-fd-primary-foreground no-underline"
+ >
+ Get started
+ </a>
+ </div>
+ </div>
+
+ <Tabs items={["Chat Completions", "Responses API"]}>
+ <Tab value="Chat Completions">
+ ```ts title="server.ts"
+ 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: "user", content: "Compare quarterly revenue by region." },
+ ],
+ stream: true,
+ });
+ ```
+ </Tab>
+ <Tab value="Responses API">
+ ```ts title="server.ts"
+ import OpenAI from "openai";
+
+ const gateway = new OpenAI({
+ apiKey: process.env.THESYS_API_KEY,
+ baseURL: "https://api.thesys.dev/v1/embed",
+ });
+
+ const response = await gateway.responses.create({
+ model: "openai/gpt-5",
+ input: "Compare quarterly revenue by region.",
+ stream: true,
+ });
+ ```
+ </Tab>
+ </Tabs>
+</div>
+ ## Choose an API
+
+ <Cards>
+ <Card title="Chat Completions" href="/docs/gateway/api/chat-completions">
+ Keep the standard messages format when integrating an existing OpenAI-compatible application.
+ </Card>
+ <Card title="Responses API" href="/docs/gateway/api/responses">
+ Build stateful model interactions with persistent conversations and hosted tools.
+ </Card>
+ </Cards>
+
+<div style={{maxWidth: '900px'}}>
+ ## What OpenUI Gateway provides
+
+ - **Validated generated UI.** Validates generated UI during the stream and fixes malformed syntax, invalid component usage, and schema violations before forwarding the response.
+ - **Unified API.** Switch between providers and models with minimal code changes.
+ - **High reliability.** Automatically retries requests with other providers if one fails.
+ - **No markup on tokens.** Tokens cost the same as they would from the provider directly, with zero markup, including with Bring Your Own Key (BYOK).
+</div>
diff --git a/docs/content/docs/gateway/meta.json b/docs/content/docs/gateway/meta.json
new file mode 100644
index 000000000..4ef188263
--- /dev/null
+++ b/docs/content/docs/gateway/meta.json
@@ -0,0 +1,19 @@
+{
+ "title": "Gateway",
+ "root": true,
+ "pages": [
+ "index",
+ "generate-openui-lang",
+ "authentication",
+ "models",
+ "reliability",
+ "prompt-caching",
+ "byok",
+ "pricing-credits",
+ "migrate-to-openui-gateway",
+ "---APIs---",
+ "api/chat-completions",
+ "api/responses",
+ "api/conversations"
+ ]
+}
diff --git a/docs/content/docs/gateway/migrate-to-openui-gateway.mdx b/docs/content/docs/gateway/migrate-to-openui-gateway.mdx
new file mode 100644
index 000000000..fc172a236
--- /dev/null
+++ b/docs/content/docs/gateway/migrate-to-openui-gateway.mdx
@@ -0,0 +1,56 @@
+---
+title: Migrate to OpenUI Gateway
+description: Move an existing OpenAI-compatible application to Gateway with minimal changes.
+---
+
+Move an existing OpenAI Chat Completions integration to OpenUI Gateway by changing the API key, base URL, and model identifier. Your existing messages, streaming, and function-tool workflows can remain unchanged.
+
+## Before you begin
+
+- Create an inference API key in the [Thesys Console](https://console.thesys.dev/keys).
+- Choose a supported model from [Models](/docs/gateway/models).
+- Decide whether to use managed inference or [bring your own provider key](/docs/gateway/byok).
+
+## Update the client
+
+Replace the OpenAI API key and add the Gateway base URL:
+
+```diff title="lib/gateway.ts"
+import OpenAI from "openai";
+
+export const client = new OpenAI({
+- apiKey: process.env.OPENAI_API_KEY,
++ apiKey: process.env.THESYS_API_KEY,
++ baseURL: "https://api.thesys.dev/v1/embed",
+});
+```
+
+Keep the inference API key on the server. See [Authentication](/docs/gateway/authentication) for credential requirements.
+
+## Update the model identifier
+
+Gateway model identifiers use the `{provider}/{model}` format. Add the provider to the model used by your existing request:
+
+```ts
+// Before
+model: "gpt-5";
+
+// After
+model: "openai/gpt-5";
+```
+
+The Chat Completions request and response shapes remain compatible with the OpenAI API. Existing message history, streaming handlers, and function-tool loops do not need to be rewritten.
+
+## Add Generative UI
+
+Migrating the client routes your existing model traffic through Gateway. To generate interfaces, add the OpenUI system prompt and connect the response stream to a renderer.
+
+Follow the [Generative UI Quickstart](/docs/gateway/generate-openui-lang) to configure a component library and generate your first interface.
+
+## Verify the migration
+
+- Confirm requests authenticate with `THESYS_API_KEY`.
+- Confirm the selected model uses the `{provider}/{model}` identifier.
+- Verify streaming responses still reach the application incrementally.
+- Run an existing function-tool flow and confirm tool calls are unchanged.
+- If Generative UI is enabled, confirm the generated interface renders correctly.
diff --git a/docs/content/docs/gateway/models.mdx b/docs/content/docs/gateway/models.mdx
new file mode 100644
index 000000000..287afe1cb
--- /dev/null
+++ b/docs/content/docs/gateway/models.mdx
@@ -0,0 +1,36 @@
+---
+title: Models
+description: Find and use model identifiers supported by OpenUI Gateway.
+---
+
+OpenUI Gateway supports hundreds of models from OpenAI, Anthropic, Google, Meta, Mistral, and other model labs.
+
+Pass the model ID directly to the `model` field in either the Chat Completions or Responses API:
+
+```ts
+const response = await gateway.chat.completions.create({
+ model: "openai/gpt-5.6-sol",
+ messages,
+});
+```
+
+## Supported models
+
+View [supported models on Models.dev](https://models.dev/providers/openrouter/) and copy the value from the **Model ID** column. Model IDs normally follow an `{author}/{model-slug}` format, such as `openai/gpt-5.6-sol`.
+
+Use the complete ID. Do not pass only the model name:
+
+```ts
+model: "openai/gpt-5.6-sol" // Correct
+model: "gpt-5.6-sol" // Missing the author
+```
+
+{/* TODO: Document provider routing after confirming the exact subset of OpenRouter provider options supported by Gateway. */}
+
+## Availability and capabilities
+
+Input and output modalities, context length, tool support, and supported parameters vary by model. Check the model details on Models.dev before selecting a model.
+
+For Generative UI, choose a model that produces text and follows structured output instructions reliably. Use the [OpenUI model benchmarks](/benchmarks/language) as a guide when comparing models, alongside the latency, cost, context length, and capabilities required by your application. Gateway can validate and correct eligible OpenUI Lang errors, but the selected model still determines the quality and latency of the generated interface. See [Reliability](/docs/gateway/reliability) for details.
+
+Add your own provider credentials with [BYOK](/docs/gateway/byok). For managed model usage and Gateway credits, see [Pricing](/docs/gateway/pricing-credits).
diff --git a/docs/content/docs/gateway/pricing-credits.mdx b/docs/content/docs/gateway/pricing-credits.mdx
new file mode 100644
index 000000000..c1c48b88f
--- /dev/null
+++ b/docs/content/docs/gateway/pricing-credits.mdx
@@ -0,0 +1,54 @@
+---
+title: Pricing
+description: Understand Gateway plans, API call charges, model usage, and BYOK.
+---
+
+**Gateway charges no markup on model tokens.** You pay the provider's list price on a pay-as-you-go basis. Purchased Gateway Credits are used automatically as requests are processed.
+
+Every generated response also uses one API call from your plan.
+
+## Free and paid plans
+
+Gateway is available through Free, Build, Grow, and Scale plans. Paid plans include more API calls, higher request priority and rate limits, and additional support.
+
+Annual billing saves up to 20%.
+
+| | Free | Build | Grow | Scale |
+| -------------------------------- | --------------------------------------------- | ------------------ | ------------------------------------------ | ------------------------------------------------------------ |
+| Monthly price | $0 | $49 | $499 | Custom |
+| Included API calls | 3,000/month | 25,000/month | 500,000/month | Custom |
+| Additional API calls | — | $0.002/call | $0.001/call | Custom |
+| Request priority and rate limits | Core limits | Higher | Highest | Custom |
+| Support | Discord community | Email | Priority support and solutions engineering | Support guarantees and SLAs |
+| Additional features | BYOK, style customization, and popular models | Everything in Free | Everything in Build, plus SSO/SAML | Self-hosting, VPC deployment, compliance, and usage controls |
+
+<Callout type="info">
+ Select models are available with no LLM token cost. These models are limited to approximately
+ 100 calls per day and 3,000 calls per month, and request data may be used for training.
+</Callout>
+
+Paid models use zero data retention.
+
+## Gateway rates
+
+The cost of a Gateway request has two parts:
+
+- **API calls:** Included with your plan. Usage above the included amount is billed at your plan's additional-call rate.
+- **Model usage:** Based on the selected provider and model, and the number of input, output, and cache tokens processed.
+
+Model usage is billed at the provider's rates without markup. The Gateway API and OpenUI Lang correction behavior remain the same whether you use managed inference or your own provider key.
+
+### Finding model pricing
+
+Model prices vary by provider and model. View the latest rates on the [Thesys pricing page](https://www.thesys.dev/pricing), including:
+
+- Input tokens per 1 million tokens
+- Output tokens per 1 million tokens
+- Cache read and write rates
+- Models currently available without LLM token charges
+
+## Bring your own key (BYOK)
+
+Gateway supports [Bring Your Own Key](/docs/gateway/byok) on every plan. When a provider key is configured, Gateway uses it for requests to that provider, and the provider bills model usage directly to your account without an additional Gateway markup.
+
+Your Gateway plan's API call limits and additional-call rates still apply. Requests to providers without a configured key use managed inference.
diff --git a/docs/content/docs/gateway/prompt-caching.mdx b/docs/content/docs/gateway/prompt-caching.mdx
new file mode 100644
index 000000000..9bf3a1188
--- /dev/null
+++ b/docs/content/docs/gateway/prompt-caching.mdx
@@ -0,0 +1,51 @@
+---
+title: Prompt Caching
+description: Reuse stable prompt prefixes to reduce model costs and response latency.
+---
+
+Prompt caching is supported on the OpenUI Embed route through the OpenAI [explicit caching option](https://developers.openai.com/api/docs/guides/prompt-caching#how-caching-works).
+
+## Why prompt caching matters
+
+Prompt caching reuses work when requests share the same prompt prefix. This provides three main benefits:
+
+- **Compute-efficient:** Avoid recalculating a prompt prefix that the model has already processed.
+- **Cheaper input tokens:** Pay the model's reduced cached-input rate for reused tokens.
+- **Faster:** Reduce the time spent processing input before the response starts.
+
+## Enabling caching
+
+Mark the end of the reusable prefix with `prompt_cache_breakpoint` on the corresponding content block. Content up to and including that block is cached.
+
+```python
+client.chat.completions.create(
+ model="anthropic/claude-sonnet-5",
+ messages=[
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": SYSTEM_PROMPT,
+ "prompt_cache_breakpoint": {"mode": "explicit"},
+ }
+ ],
+ },
+ {"role": "user", "content": "..."},
+ ],
+)
+```
+
+## Provider behavior
+
+| Provider | Behavior |
+| :------------------------- | :--------------------------------------------------------------------------------------------------------- |
+| Anthropic (Claude) | Content up to and including a marked block is cached. Without a breakpoint, your content is not cached. |
+| OpenAI (GPT) | A stable prompt prefix is cached automatically. Explicit caching requires GPT-5.6 or later (not supported). |
+| Google (Gemini) and others | Prefixes are cached automatically where the provider supports it. The breakpoint is ignored. |
+
+For Anthropic models, caching your content is opt-in. OpenAI and Gemini cache eligible prefixes automatically.
+
+## Limitations
+
+- Setting a cache lifetime (`ttl`) on an individual breakpoint is not supported. The cache lifetime is fixed.
diff --git a/docs/content/docs/gateway/reliability.mdx b/docs/content/docs/gateway/reliability.mdx
new file mode 100644
index 000000000..8e03a6dd3
--- /dev/null
+++ b/docs/content/docs/gateway/reliability.mdx
@@ -0,0 +1,50 @@
+---
+title: Reliability
+description: Keep model requests working when providers are unavailable or models return invalid OpenUI Lang.
+---
+
+Applications that generate interfaces with AI face two common reliability problems. A model provider may be unavailable, or the model may return output that does not follow the OpenUI Lang instructions and component schemas. The first prevents a response; the second can produce an interface the application cannot render.
+
+Gateway handles each problem differently. It automatically retries the request with other providers and corrects eligible errors in model output while the response streams.
+
+## How Gateway improves reliability
+
+| Problem | What happens | How Gateway responds |
+| ------------------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| **Provider unavailable** | An outage, capacity limit, or unavailable route prevents the selected provider from responding. | Gateway retries through a compatible fallback route. |
+| **Invalid model output** | The model returns OpenUI Lang with invalid syntax, references, components, properties, or structure. | Gateway corrects eligible errors and continues the stream. |
+
+## Recover from provider failures
+
+The application continues to use the same Gateway API and `{provider}/{model}` naming convention when Gateway moves a request to a fallback. The Responses or Chat Completions API also remains the same, so the application does not need a separate integration for each provider.
+
+<Callout type="info">
+ The exact fallback route depends on model compatibility and account configuration. Confirm the
+ active behavior for your project in the Thesys Console before relying on it for a strict model or
+ data-residency requirement.
+</Callout>
+
+## Correct invalid model output
+
+Gateway validates OpenUI Lang while the model produces it. It can identify eligible problems such as:
+
+- Malformed OpenUI Lang statements
+- References that cannot be resolved
+- Components that are not in the supplied library
+- Property values that violate a component schema
+- Structures that the renderer cannot safely construct
+
+When an error can be corrected, Gateway repairs the affected output and continues the stream. It does not wait for the complete interface or require the application to retry the entire generation.
+
+Correction applies only to generated OpenUI Lang. Plain text, arbitrary JSON, application tool results, and component code are outside this boundary.
+
+## What your application still controls
+
+Gateway improves the reliability of model access and generated OpenUI Lang. Your application remains responsible for:
+
+- Component behavior and UI error boundaries
+- Authentication and permissions
+- Tool authorization and input validation
+- Business rules and data validation
+
+See [OpenUI Lang reliability](/docs/openui-lang/reliability) for component definitions, prompts, evaluations, and renderer safeguards.
diff --git a/docs/content/docs/getting-started.mdx b/docs/content/docs/getting-started.mdx
new file mode 100644
index 000000000..71369a477
--- /dev/null
+++ b/docs/content/docs/getting-started.mdx
@@ -0,0 +1,89 @@
+---
+title: Getting Started
+description: Create a new OpenUI application or add OpenUI to an existing agent.
+---
+
+Start a new agent application with the OpenUI CLI, or add OpenUI to an application you already have.
+
+## Start a new application
+
+You need Node.js 20 or later. Run the interactive setup to choose your model connection and agent framework:
+
+```bash
+npx @openuidev/cli@latest create
+```
+
+The CLI creates the project, installs its dependencies, and can start the development server for you.
+
+### Choose a model connection
+
+Use OpenUI Gateway for model access, output correction, and provider fallbacks:
+
+```bash
+npx @openuidev/cli@latest create --name my-agent --template openui-cloud
+```
+
+Or connect the generated application directly to your own model provider:
+
+```bash
+npx @openuidev/cli@latest create --name my-agent --template openui-self-hosted
+```
+
+### Choose an agent framework
+
+Add `--backend-framework` to scaffold an integration for a specific agent framework. These options can be combined with either model setup.
+
+```bash tab="Default" tab-group="agent-framework"
+npx @openuidev/cli@latest create \
+ --name my-agent \
+ --template openui-cloud \
+ --backend-framework default
+```
+
+```bash tab="Vercel AI SDK" tab-group="agent-framework"
+npx @openuidev/cli@latest create \
+ --name my-agent \
+ --template openui-cloud \
+ --backend-framework vercel-ai-sdk
+```
+
+```bash tab="LangGraph" tab-group="agent-framework"
+npx @openuidev/cli@latest create \
+ --name my-agent \
+ --template openui-cloud \
+ --backend-framework langgraph
+```
+
+```bash tab="Vercel Eve" tab-group="agent-framework"
+npx @openuidev/cli@latest create \
+ --name my-agent \
+ --template openui-cloud \
+ --backend-framework vercel-eve
+```
+
+The generated application includes [Agent Interface](/docs/agent/getting-started/introduction) and an OpenUI Lang component library. Follow the [Agent Interface Quickstart](/docs/agent/getting-started/quickstart) to understand the generated project.
+
+## Add OpenUI to an existing application
+
+<Cards>
+ <Card title="assistant-ui or CopilotKit" href="/docs/build-agents">
+ Keep your existing conversation experience and add OpenUI Lang rendering.
+ </Card>
+ <Card title="Custom chat UI" href="/docs/build-agents/custom-chat-ui">
+ Render generated interfaces inside your existing message list.
+ </Card>
+ <Card title="Agent backend" href="/docs/gateway/generate-openui-lang">
+ Route model requests through OpenUI Gateway and generate validated OpenUI Lang.
+ </Card>
+</Cards>
+
+## Build only with OpenUI Lang
+
+Use OpenUI Lang without adopting a complete agent interface or hosted model service:
+
+1. [Define the components](/docs/openui-lang/defining-components) the model can use.
+2. [Generate the system prompt](/docs/openui-lang/system-prompts) from the component library.
+3. Send those instructions to your chosen model or agent framework.
+4. [Render the streamed response](/docs/openui-lang/renderer) with your application components.
+
+Learn more in the [OpenUI Lang documentation](/docs/openui-lang).
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
new file mode 100644
index 000000000..e1b7c3448
--- /dev/null
+++ b/docs/content/docs/index.mdx
@@ -0,0 +1,31 @@
+---
+title: Introduction
+---
+
+import { TryItOut } from "./openui-lang/components/try-it-out";
+
+OpenUI is a Generative UI toolkit for creating agents that respond with live, interactive interfaces instead of only text. It provides the building blocks for interfaces that adapt to each request while remaining consistent with your product and design system.
+
+<TryItOut />
+
+## OpenUI stack
+
+OpenUI includes three products for building and running Generative UI:
+
+<Cards>
+ <Card title="OpenUI Lang" href="/docs/openui-lang">
+ A compact, line-based language for AI models to generate interfaces from your components. It is
+ predictable, stream-friendly, and uses up to [**67% fewer
+ tokens**](/docs/openui-lang/benchmarks) than JSON.
+ </Card>
+ <Card title="Gateway" href="/docs/gateway">
+ OpenRouter for Generative UI. Use one API to access models across providers, with automatic
+ failover and model-output correction that prevents broken interfaces.
+ </Card>
+ <Card title="Observability" href="/docs/observability">
+ Production visibility for Generative UI. Trace generated interfaces and improve their
+ reliability.
+ </Card>
+</Cards>
+
+Ready to build? [Get started with OpenUI](/docs/getting-started).
diff --git a/docs/content/docs/mcp/index.mdx b/docs/content/docs/mcp/index.mdx
index 616b2b615..e2bbccfbf 100644
--- a/docs/content/docs/mcp/index.mdx
+++ b/docs/content/docs/mcp/index.mdx
@@ -1,5 +1,5 @@
---
-title: AI-Assisted Development
+title: Coding Agent Setup
description: Connect OpenUI documentation to your AI coding tools via MCP, agent skills, or LLM-friendly doc formats.
---
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 9d8d002f9..003aa943f 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -1,11 +1,14 @@
{
"title": "OpenUI",
"pages": [
- "overview",
+ "index",
+ "getting-started",
+ "architecture",
"openui-lang",
- "components",
+ "build-agents",
"agent",
- "openui-cloud",
+ "gateway",
+ "observability",
"api-reference"
]
}
diff --git a/docs/content/docs/observability/dashboard.mdx b/docs/content/docs/observability/dashboard.mdx
new file mode 100644
index 000000000..7637415db
--- /dev/null
+++ b/docs/content/docs/observability/dashboard.mdx
@@ -0,0 +1,38 @@
+---
+title: Dashboard
+description: Use the hosted dashboard to find recurring OpenUI errors and inspect affected generations.
+---
+
+After production setup, open the [Reliability dashboard](https://console.thesys.dev/reliability) to understand how generated interfaces behave across real requests.
+
+Use the dashboard to answer three questions:
+
+1. **How often does generation fail?** Track the share of responses with OpenUI parsing, validation, or rendering errors.
+2. **What fails repeatedly?** Group failures by error kind to identify components, schemas, prompt rules, or model choices that need attention.
+3. **Which generations were affected?** Inspect the context attached to an event so the failure can be reproduced in development.
+
+## Reliability dashboard
+
+![OpenUI Reliability dashboard showing successful requests, errors over time, and errors grouped by category](/images/observability/reliability-dashboard.png)
+
+The dashboard summarizes the percentage of requests rendered successfully, the total number of requests, and the number of errors for the selected time period. The timeline shows when errors occurred, making spikes and changes in reliability easier to identify.
+
+Errors are also grouped by category, with their share, count, and most recent occurrence. Use this breakdown to find the failure types affecting the most generations and decide what to investigate first.
+
+## Inspect an error category
+
+Select an error category to open a sidebar with every occurrence in the chosen time range.
+
+![Error category sidebar showing its occurrence timeline and affected renders](/images/observability/error-category-list.png)
+
+The timeline shows when the error occurred and helps reveal whether it is isolated or recurring. The list below identifies each affected render with the number of errors, related error codes, occurrence time. Use these details to narrow when the issue started occuring.
+
+## Inspect a single occurrence
+
+Click on an error occurance to inspect the errors associated with a specific generated interface.
+
+![Error occurrence sidebar showing its timestamp, stream ID, generated output, and individual errors](/images/observability/single-error.png)
+
+The detail view shows when the occurrence was recorded, and the generated OpenUI Lang that caused the failure. Each error includes a code, a readable explanation, and relevant details such as the component or statement involved.
+
+See [Optimizing with Observability](/docs/observability/optimizing) for a repeatable improvement loop.
diff --git a/docs/content/docs/observability/index.mdx b/docs/content/docs/observability/index.mdx
new file mode 100644
index 000000000..c85ea1e22
--- /dev/null
+++ b/docs/content/docs/observability/index.mdx
@@ -0,0 +1,12 @@
+---
+title: Overview
+description: Find and understand OpenUI generation and rendering errors across production traffic.
+---
+
+Generative UI turns model output into interfaces that people use directly. Models usually follow the component contract they receive, but they can still invent components, use unsupported values, leave references unresolved, or stop early. This can produce incomplete or broken interfaces.
+
+![OpenUI reliability dashboard](/images/observability/reliability-dashboard.png)
+
+In our [**Reliability benchmark**](/blog/generative-ui-benchmark), every tested format, including OpenUI, A2UI, and json-render, produced incomplete generations. OpenUI completed 92.9% of evaluated tasks and produced 2 blank screens across 1,104 runs. Its strongest model pairing reached 99.5%, not 100%.
+
+OpenUI Observability helps teams find and trace these failures after deployment so they can improve the reliability of generated interfaces.
diff --git a/docs/content/docs/observability/installation.mdx b/docs/content/docs/observability/installation.mdx
new file mode 100644
index 000000000..72118588d
--- /dev/null
+++ b/docs/content/docs/observability/installation.mdx
@@ -0,0 +1,48 @@
+---
+title: Installation
+description: Connect an OpenUI application to hosted Observability with the official production SDK.
+---
+
+Install `@openuidev/observability-cloud` in the application that renders OpenUI interfaces. The SDK sends supported runtime telemetry to the hosted Observability product.
+
+## 1. Install the SDK
+
+```bash tab="pnpm" tab-group="pkg"
+pnpm add @openuidev/observability-cloud
+```
+
+```bash tab="bun" tab-group="pkg"
+bun add @openuidev/observability-cloud
+```
+
+```bash tab="yarn" tab-group="pkg"
+yarn add @openuidev/observability-cloud
+```
+
+```bash tab="npm" tab-group="pkg"
+npm install @openuidev/observability-cloud
+```
+
+## 2. Create a client key
+
+Create a client API key in the [Thesys Console](https://console.thesys.dev/client-api-keys). Client keys are intended for application runtime telemetry; do not substitute a Gateway server API key.
+
+## 3. Initialize once
+
+Initialize Observability at the root of the application before rendering OpenUI responses:
+
+```ts
+import * as Observability from "@openuidev/observability-cloud";
+
+Observability.init({
+ apiKey: "pk-th-…",
+});
+```
+
+Deploy the application and exercise representative generative UI flows. Runtime errors will begin appearing in the Console's reliability views.
+
+## Works with any generation path
+
+The SDK captures supported OpenUI runtime signals whether the application generated the response through the [Gateway](/docs/gateway) or called a model provider directly.
+
+Continue with [Dashboard](/docs/observability/dashboard) to interpret the data.
diff --git a/docs/content/docs/observability/meta.json b/docs/content/docs/observability/meta.json
new file mode 100644
index 000000000..10b2741d6
--- /dev/null
+++ b/docs/content/docs/observability/meta.json
@@ -0,0 +1,10 @@
+{
+ "title": "Observability",
+ "root": true,
+ "pages": [
+ "index",
+ "installation",
+ "dashboard",
+ "optimizing"
+ ]
+}
diff --git a/docs/content/docs/observability/optimizing.mdx b/docs/content/docs/observability/optimizing.mdx
new file mode 100644
index 000000000..e3dfe5f24
--- /dev/null
+++ b/docs/content/docs/observability/optimizing.mdx
@@ -0,0 +1,30 @@
+---
+title: Optimizing with Observability
+description: Turn recurring runtime errors into focused improvements to components, prompts, and model selection.
+---
+
+Observability is most useful as a feedback loop, not only an incident log. Use production evidence to choose the smallest change likely to improve reliability, then verify the result against the same signal.
+
+## 1. Find a repeated failure
+
+Prioritize high-frequency errors and failures that make the interface unusable. Record the event kind, affected component or statement, model, and a representative request.
+
+## 2. Reproduce it locally
+
+Copy the affected OpenUI Lang into [OpenUI Debug](/debug) or replay the request in a test environment with the same component library. A reproducible failure is easier to classify than a dashboard symptom.
+
+## 3. Change the right layer
+
+| Failure pattern | First intervention |
+| ---------------------------------------------- | ------------------------------------------------------------------------- |
+| Model invents a component or property | Clarify names, descriptions, and schemas. |
+| Model repeatedly chooses the wrong composition | Add a focused rule or valid example to the system prompt. |
+| One model fails much more often | Evaluate a different model against the same request set. |
+| Valid output fails in the browser | Fix the component renderer or application integration. |
+| Provider availability interrupts streams | Review [Gateway fallbacks](/docs/gateway/reliability#recover-from-provider-failures). |
+
+## 4. Verify the change
+
+Deploy one focused change and compare the same error group over a meaningful traffic window. Watch for new error kinds rather than assuming a lower count means the underlying problem is gone.
+
+For broader design guidance, see [OpenUI Lang Reliability](/docs/openui-lang/reliability).
diff --git a/docs/content/docs/openui-cloud/api/artifacts.mdx b/docs/content/docs/openui-cloud/api/artifacts.mdx
deleted file mode 100644
index 29e61b031..000000000
--- a/docs/content/docs/openui-cloud/api/artifacts.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: Chat Completions (Artifacts)
-description: "Generate and edit standalone OpenUI Cloud presentations and reports with a Chat Completions-compatible endpoint."
----
-
-The Artifact Chat Completions API generates a standalone slide deck or report as an OpenUI Lang program. Use it when the artifact lifecycle is separate from an agent's Responses stream.
-
-**Endpoint:** `POST https://api.thesys.dev/v1/artifact/chat/completions`
-
-Use the `artifactClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration.
-
-## Generate an artifact
-
-Every request includes `metadata.thesys` as a JSON string with your artifact `id` and a `c1_artifact_type` of `"slides"` or `"report"`.
-
-```ts
-const artifact = await artifactClient.chat.completions.create({
- model: "openai/gpt-5",
- messages: [{ role: "user", content: "Create a three-slide deck on Q4 results." }],
- metadata: {
- thesys: JSON.stringify({
- id: "art_1",
- c1_artifact_type: "slides",
- }),
- },
-});
-
-const program = artifact.choices[0].message.content;
-```
-
-The response content is a raw OpenUI Lang program rooted at `SlideShow` or `ReportView`. OpenUI Cloud validates and repairs it before returning it. Set `stream: true` to receive the program progressively.
-
-## Render an artifact
-
-Render the returned program with the matching managed viewer:
-
-```tsx
-import { Presentation, Report } from "@openuidev/thesys";
-import "@openuidev/thesys/styles.css";
-
-export function Artifact({ kind, program }: { kind: "slides" | "report"; program: string }) {
- return kind === "slides" ? (
- <Presentation response={program} preview={false} />
- ) : (
- <Report response={program} preview={false} />
- );
-}
-```
-
-Pass `isStreaming` while accumulating a streamed program.
-
-## Edit an artifact
-
-Send the current OpenUI Lang program as an assistant message, describe the change in the next user message, and set `is_edit: true`.
-
-```ts
-const edited = await artifactClient.chat.completions.create({
- model: "openai/gpt-5",
- messages: [
- { role: "assistant", content: previousProgram },
- { role: "user", content: "Make slide 2 about European revenue." },
- ],
- metadata: {
- thesys: JSON.stringify({
- id: "art_1",
- c1_artifact_type: "slides",
- is_edit: true,
- }),
- },
- stream: true,
-});
-```
-
-The response is a patch-mode OpenUI Lang program merged against the assistant-message base.
-
-Use the [Responses API](/docs/openui-cloud/api/responses#generate-slides-and-reports) instead when artifacts should be stored, opened, and edited as part of a persistent agent conversation.
diff --git a/docs/content/docs/openui-cloud/api/chat-completions.mdx b/docs/content/docs/openui-cloud/api/chat-completions.mdx
deleted file mode 100644
index 8b44cf59b..000000000
--- a/docs/content/docs/openui-cloud/api/chat-completions.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: Chat Completions
-description: "Use the OpenAI-compatible embed endpoint for text, managed or self-hosted generative UI, and function tools."
----
-
-The Embed Chat Completions API is a drop-in endpoint for applications that already use `chat.completions.create()`. It preserves the standard message format and supports text or OpenUI Lang responses.
-
-**Endpoint:** `POST https://api.thesys.dev/v1/embed/chat/completions`
-
-Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration.
-
-## Make a managed UI request
-
-Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library.
-
-```ts title="server.ts"
-import { generateSystemPrompt } from "@openuidev/lang-core";
-
-const completion = await embedClient.chat.completions.create({
- model: "openai/gpt-5",
- messages: [
- { role: "system", content: generateSystemPrompt({ cloud: true }) },
- { role: "user", content: "Compare quarterly revenue by region." },
- ],
-});
-
-console.log(completion.choices[0].message.content);
-```
-
-The returned message content is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and using your own library.
-
-## Stream and render responses
-
-Set `stream: true` on the server. In the browser, pair the Chat Completions stream adapter with the OpenAI message format:
-
-```tsx title="cloud-chat.tsx"
-"use client";
-
-import { AgentInterface, fetchLLM, openAIAdapter, openAIMessageFormat } from "@openuidev/react-ui";
-import { chatLibrary } from "@openuidev/thesys";
-import "@openuidev/thesys/styles.css";
-
-const llm = fetchLLM({
- url: "/api/chat",
- streamAdapter: openAIAdapter(),
- messageFormat: openAIMessageFormat,
-});
-
-export function Chat() {
- return <AgentInterface llm={llm} componentLibrary={chatLibrary} />;
-}
-```
-
-Use `openAIAdapter()` when your route preserves the raw `data:` SSE response. If it returns the OpenAI SDK stream through `.toReadableStream()` instead, use `openAIReadableStreamAdapter()`. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats) for the exact pairings.
-
-## Manage conversation history
-
-Chat Completions is message-based. Keep the conversation in your application and include the system message plus the relevant `user`, `assistant`, and `tool` messages on every turn.
-
-The [Conversations API](/docs/openui-cloud/api/conversations) integrates with Responses, not Embed Chat Completions. Choose Responses when you want Cloud-managed persistent history.
-
-## Use function tools
-
-Embed Chat Completions accepts `function` tools only and does not execute them. Run the standard loop in your application:
-
-1. Send the messages and function declarations.
-2. Read `tool_calls` from the assistant message.
-3. Execute each function in your application.
-4. Append the assistant tool-call message and each `role: "tool"` result.
-5. Repeat until the model returns a final response.
-
-Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are available on the [Responses API](/docs/openui-cloud/api/responses#use-tools). For standalone slides or reports, use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts).
-
-## Use other generation modes
-
-### Plain text passthrough
-
-Use a `{provider}/{model}` model ID without the managed `generateSystemPrompt({ cloud: true })` sentinel. OpenUI Cloud forwards your messages and system prompt without injecting a generative UI prompt or component schema.
-
-```ts
-const completion = await embedClient.chat.completions.create({
- model: "openai/gpt-5",
- messages: [
- { role: "system", content: "You are a concise product analyst." },
- { role: "user", content: "Summarize the risks in this launch plan." },
- ],
-});
-
-console.log(completion.choices[0].message.content);
-```
-
-OpenAI, Anthropic, and Google model IDs route to those providers. Unknown providers route through OpenRouter.
-
-### Self-hosted generative UI
-
-Compile the complete system prompt in your application from a generated OpenUI library spec. The endpoint forwards that prompt verbatim; the model returns OpenUI Lang for your client-side renderer.
-
-```ts
-import { generateSystemPrompt } from "@openuidev/lang-core";
-import library from "./generated/library.spec.json";
-
-const completion = await embedClient.chat.completions.create({
- model: "openai/gpt-5",
- messages: [
- {
- role: "system",
- content: generateSystemPrompt({
- library,
- promptOptions,
- }),
- },
- ...messages,
- ],
- stream: true,
-});
-```
-
-In this mode, prompt assembly, output validation, and rendering are owned by your application.
diff --git a/docs/content/docs/openui-cloud/api/conversations.mdx b/docs/content/docs/openui-cloud/api/conversations.mdx
deleted file mode 100644
index eb5d83cfd..000000000
--- a/docs/content/docs/openui-cloud/api/conversations.mdx
+++ /dev/null
@@ -1,93 +0,0 @@
----
-title: Conversations API
-description: "Create persistent OpenUI Cloud conversations, inspect their items, and connect them to Responses and Agent Interface."
----
-
-The Conversations API stores persistent threads and their items. Responses can read and append to a conversation, while `AgentInterface` uses the same API to list threads and reload messages.
-
-**Base URL:** `https://api.thesys.dev/v1`
-
-Use the `conversationClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication and the shared OpenAI SDK clients.
-
-<Callout type="info">
- Conversations integrate with the Responses API. Embed Chat Completions applications own and resend
- their own `messages` history.
-</Callout>
-
-## Create a conversation
-
-Create the conversation before the first stored response:
-
-```ts
-const conversation = await conversationClient.conversations.create({
- metadata: { workspace: "acme" },
-});
-```
-
-Then send only the new turn to Responses and set `store: true`:
-
-```ts
-import { generateSystemPrompt } from "@openuidev/lang-core";
-
-const response = await embedClient.responses.create({
- model: "openai/gpt-5",
- conversation: conversation.id,
- input: "Compare quarterly revenue by region.",
- instructions: generateSystemPrompt({ cloud: true }),
- store: true,
- stream: true,
-});
-```
-
-Every later response with the same `conversation` ID can use the stored context without resending the full history.
-
-## Read conversation items
-
-List the messages, tool calls, and tool outputs stored in a conversation:
-
-```ts
-const page = await conversationClient.conversations.items.list(conversation.id, {
- order: "asc",
- limit: 100,
-});
-
-for (const item of page.data) {
- console.log(item.type, item.id);
-}
-```
-
-The OpenAI SDK also exposes `retrieve`, `update`, and `delete` for conversations, and create, retrieve, list, and delete operations for conversation items.
-
-## Endpoint summary
-
-| Method | Path | Purpose |
-| ------------------------- | ----------------------------------------------------- | ------------------------------------------- |
-| `GET` / `POST` | `/v1/conversations` | List or create conversations. |
-| `GET` / `POST` / `DELETE` | `/v1/conversations/{conversation_id}` | Retrieve, update, or delete a conversation. |
-| `GET` / `POST` | `/v1/conversations/{conversation_id}/items` | List or add conversation items. |
-| `GET` / `DELETE` | `/v1/conversations/{conversation_id}/items/{item_id}` | Retrieve or delete one item. |
-
-Server-side requests authenticate with the API key described in the [API overview](/docs/openui-cloud/api/overview#authenticate).
-
-## Connect Agent Interface
-
-In the browser, use `useOpenuiCloudStorage()` instead of calling the raw endpoints. It lists conversations, loads their items, and persists artifact state for `AgentInterface`.
-
-```tsx
-import { AgentInterface } from "@openuidev/react-ui";
-import { useOpenuiCloudStorage } from "@openuidev/thesys";
-
-export function Chat() {
- const storage = useOpenuiCloudStorage({
- token: "/api/frontend-token",
- apiBaseUrl: "https://api.thesys.dev",
- features: { artifact: true },
- });
-
- return <AgentInterface llm={llm} storage={storage} />;
-}
-```
-
-The `/api/frontend-token` server route mints a short-lived token with `POST /v1/frontend-tokens`, binding it to your authenticated `user_id` and optional `app_id`. The browser sends that token as `x-thesys-frontend-token`; the server API key never leaves your backend.
-
-Use the current [frontend-token route](https://github.com/thesysdev/openui/blob/main/templates/openui-cloud/src/app/api/frontend-token/route.ts) and [Cloud storage setup](https://github.com/thesysdev/openui/blob/main/templates/openui-cloud/src/components/cloud-chat.tsx) as complete references.
diff --git a/docs/content/docs/openui-cloud/api/overview.mdx b/docs/content/docs/openui-cloud/api/overview.mdx
deleted file mode 100644
index 655ee4ae5..000000000
--- a/docs/content/docs/openui-cloud/api/overview.mdx
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: API Overview
-description: "Choose an OpenUI Cloud API and configure the shared authentication, clients, models, and persistence behavior."
----
-
-OpenUI Cloud exposes four related API surfaces. Choose the generation shape and state model that fit your application, then use the focused API guide for implementation details.
-
-## Choose an API
-
-| API | Endpoint | Use it for |
-| ------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
-| [Responses](/docs/openui-cloud/api/responses) | `POST /v1/embed/responses` | New agent applications, hosted tools, persistent conversations, and artifacts inside the agent stream. |
-| [Chat Completions (Embed)](/docs/openui-cloud/api/chat-completions) | `POST /v1/embed/chat/completions` | Existing Chat Completions applications, plain text, managed or self-hosted generative UI, and app-run function tools. |
-| [Chat Completions (Artifacts)](/docs/openui-cloud/api/artifacts) | `POST /v1/artifact/chat/completions` | Standalone slide or report generation and explicit program-based edits. |
-| [Conversations](/docs/openui-cloud/api/conversations) | `/v1/conversations` | Persistent Responses threads, items, and the storage plane used by `AgentInterface`. |
-
-Responses is the recommended starting point for new agent applications. The two Chat Completions endpoints let existing integrations keep their message format, while Conversations provides persistent state for Responses.
-
-## Authenticate
-
-Create an API key in the [Thesys console](https://console.thesys.dev/keys) and configure `THESYS_API_KEY` on your server. Server-side requests use:
-
-```http
-Authorization: Bearer $THESYS_API_KEY
-```
-
-Never expose this key to browser code. Browser access to conversations and artifacts uses a scoped, short-lived frontend token instead; see the [Conversations API](/docs/openui-cloud/api/conversations#connect-agent-interface).
-
-## Configure the clients
-
-The generation endpoints and core Conversations operations are compatible with the stock OpenAI SDK. Use a client for each base URL your application needs:
-
-```ts title="lib/openui-cloud.ts"
-import OpenAI from "openai";
-
-const common = { apiKey: process.env.THESYS_API_KEY };
-
-export const embedClient = new OpenAI({
- ...common,
- baseURL: "https://api.thesys.dev/v1/embed",
-});
-
-export const artifactClient = new OpenAI({
- ...common,
- baseURL: "https://api.thesys.dev/v1/artifact",
-});
-
-export const conversationClient = new OpenAI({
- ...common,
- baseURL: "https://api.thesys.dev/v1",
-});
-```
-
-The Embed and Artifact generation endpoints support streaming and non-streaming requests.
-
-## Choose a state model
-
-| Flow | Where history lives |
-| ----------------------------------------------- | ------------------------------------------------------------------- |
-| Responses with `conversation` and `store: true` | OpenUI Cloud stores the persistent conversation and response items. |
-| Responses with `previous_response_id` | OpenUI Cloud chains stored responses without a named conversation. |
-| Responses with full `input` history | Your application stores and resends history. |
-| Embed Chat Completions | Your application stores and resends the `messages` array. |
-| Artifact Chat Completions | Each edit request includes the current artifact program explicitly. |
-
-## Shared configuration
-
-- Use `{provider}/{model}` model IDs across generation endpoints. See [Models and BYOK](/docs/openui-cloud/models-and-byok) for supported models and provider credentials.
-- Use the built-in chat library or provide your own components. See [Component Library](/docs/openui-cloud/build/component-library).
-- Keep generation behind a server route and match the browser adapter to the selected response protocol. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats).
-- For the relationship between generation, storage, and rendering, see [How it works](/docs/openui-cloud/how-it-works).
diff --git a/docs/content/docs/openui-cloud/api/responses.mdx b/docs/content/docs/openui-cloud/api/responses.mdx
deleted file mode 100644
index 61d03d9e2..000000000
--- a/docs/content/docs/openui-cloud/api/responses.mdx
+++ /dev/null
@@ -1,149 +0,0 @@
----
-title: Responses API
-description: "Generate managed UI with persistent conversations, hosted tools, and artifacts in the agent stream."
----
-
-The Responses API is the recommended generation endpoint for new OpenUI Cloud agent applications.
-
-**Endpoint:** `POST https://api.thesys.dev/v1/embed/responses`
-
-Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration.
-
-## Make a request
-
-Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library.
-
-```ts title="server.ts"
-import { generateSystemPrompt } from "@openuidev/lang-core";
-
-const response = await embedClient.responses.create({
- model: "openai/gpt-5",
- input: "Compare quarterly revenue by region.",
- instructions: generateSystemPrompt({ cloud: true }),
-});
-
-console.log(response.output_text);
-```
-
-The returned `output_text` is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and using your own library.
-
-## Stream and render responses
-
-Set `stream: true` on the server. In the browser, pair the Responses stream adapter with the conversation message format:
-
-```tsx title="cloud-chat.tsx"
-"use client";
-
-import {
- AgentInterface,
- fetchLLM,
- openAIConversationMessageFormat,
- openAIResponsesAdapter,
-} from "@openuidev/react-ui";
-import { chatLibrary } from "@openuidev/thesys";
-import "@openuidev/thesys/styles.css";
-
-const llm = fetchLLM({
- url: "/api/chat",
- streamAdapter: openAIResponsesAdapter(),
- messageFormat: openAIConversationMessageFormat,
-});
-
-export function Chat() {
- return <AgentInterface llm={llm} componentLibrary={chatLibrary} />;
-}
-```
-
-Your `/api/chat` route should forward the OpenUI Cloud response stream without changing its event shape. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats) for lower-level transport details.
-
-## Manage conversation history
-
-The Responses API supports three history patterns:
-
-| Pattern | Use it when |
-| -------------------------------- | --------------------------------------------------------------------------------- |
-| Send the full history in `input` | Your application owns all message storage. |
-| Set `previous_response_id` | You want to chain turns without a named conversation. Use `store: true`. |
-| Set `conversation` | You want a persistent thread managed by the Conversations API. Use `store: true`. |
-
-Chain a follow-up to an earlier response:
-
-```ts
-const first = await embedClient.responses.create({
- model: "openai/gpt-5",
- input: "Compare quarterly revenue by region.",
- instructions: generateSystemPrompt({ cloud: true }),
- store: true,
-});
-
-const followUp = await embedClient.responses.create({
- model: "openai/gpt-5",
- input: "Focus on Europe and explain the change.",
- instructions: generateSystemPrompt({ cloud: true }),
- previous_response_id: first.id,
- store: true,
-});
-```
-
-For persistent named threads, see the [Conversations API](/docs/openui-cloud/api/conversations).
-
-## Use tools
-
-OpenUI Cloud runs hosted tools inside the platform. App-owned function tools still run on your server.
-
-| Capability | Tool declaration | Runs on |
-| -------------------- | --------------------------------------------------- | ------------ |
-| Slides and reports | `artifactTool({ artifacts: ["slides", "report"] })` | OpenUI Cloud |
-| Web search | `{ type: "web_search" }` | OpenUI Cloud |
-| Image search | `{ type: "image_search" }` | OpenUI Cloud |
-| Remote MCP server | `{ type: "mcp", server_label, server_url }` | OpenUI Cloud |
-| Application function | `{ type: "function", name, parameters }` | Your server |
-
-```ts
-import type { Tool } from "openai/resources/responses/responses";
-
-const response = await embedClient.responses.create({
- model: "openai/gpt-5",
- input: "Research the market and summarize the most important changes.",
- instructions: generateSystemPrompt({ cloud: true }),
- tools: [
- { type: "web_search" },
- { type: "image_search" } as unknown as Tool,
- {
- type: "mcp",
- server_label: "deepwiki",
- server_url: "https://mcp.deepwiki.com/mcp",
- } as unknown as Tool,
- ],
- stream: true,
- store: true,
-});
-```
-
-The casts are needed because image search and MCP are OpenUI Cloud extensions to the stock OpenAI tool union.
-
-For a `function` tool, execute each returned `function_call` on your server and continue with a `function_call_output`. The OpenUI Cloud scaffold includes a complete tool loop; see [Tools](/docs/agent/core-concepts/tools) for the execution model.
-
-## Generate slides and reports
-
-Add `artifactTool()` to generate editable slides or reports inside the agent stream:
-
-```ts
-import { generateSystemPrompt } from "@openuidev/lang-core";
-import { artifactTool } from "@openuidev/thesys-server";
-import type { Tool } from "openai/resources/responses/responses";
-
-const response = await embedClient.responses.create({
- model: "openai/gpt-5",
- conversation: threadId,
- input: "Create a three-slide deck on Q4 results.",
- instructions: generateSystemPrompt({ cloud: true }),
- tools: [artifactTool({ artifacts: ["slides", "report"] }) as unknown as Tool],
- store: true,
- stream: true,
-});
-```
-
-Artifacts are stored separately from chat messages. Register `presentationArtifactRenderer`, `reportArtifactRenderer`, and `useOpenuiCloudStorage()` with `AgentInterface` to render and persist them. The [OpenUI Cloud scaffold](https://github.com/thesysdev/openui/blob/main/templates/openui-cloud/src/components/cloud-chat.tsx) contains the complete client setup.
-
-Follow-up requests in the same stored conversation edit the existing artifact automatically. Use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts) when you need standalone generation or explicitly managed edits outside an agent stream.
diff --git a/docs/content/docs/openui-cloud/build/chat.mdx b/docs/content/docs/openui-cloud/build/chat.mdx
deleted file mode 100644
index 343fe8d42..000000000
--- a/docs/content/docs/openui-cloud/build/chat.mdx
+++ /dev/null
@@ -1,66 +0,0 @@
----
-title: Generative UI for agents
-description: "Agents respond with interactive interfaces that use forms, charts, and layout components suited to the conversation."
----
-
-Agents can respond with interfaces that match the task instead of returning only text. OpenUI Cloud validates and streams each response so it renders live in the application. Use the built-in component library or bring your own.
-
-## Built-in component library
-
-OpenUI Cloud includes a pre-tested, responsive, and accessible set of components for forms, inputs, charts, content organization, and interactive actions.
-
-### Forms and inputs
-
-Form components include text fields, selects, options, and defaults. They compose into forms that collect structured input in one step instead of over several text messages.
-
-<video
- src="/videos/agent/generative-ui-form-interaction.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-### Charts and visualizations
-
-Interactive chart components include pie, bar, line, area, and radial charts. Agents can select the format that matches the data, such as pie charts for shares, bar charts for comparisons, and line charts for trends.
-
-<video
- src="/videos/openui-cloud/chat/charts-visualizations.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-### Content organization
-
-Layout components include tabs, accordions, tables, and cards. They organize long responses into scannable sections, such as alternatives in tabs, details in accordions, and comparisons in tables.
-
-<video
- src="/videos/openui-cloud/chat/content-organization.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-### Buttons and actions
-
-Action components include buttons and controls for next steps such as confirming, booking, or refining. Interactions feed back into the conversation as structured events instead of typed commands.
-
-<video
- src="/videos/openui-cloud/chat/buttons-and-actions.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-## Bring your own component library
-
-Connect your own design system and domain-specific components. Agents can use them to generate interfaces while OpenUI Cloud provides model reliability, output validation, and observability.
diff --git a/docs/content/docs/openui-cloud/build/component-library.mdx b/docs/content/docs/openui-cloud/build/component-library.mdx
deleted file mode 100644
index 9243cd481..000000000
--- a/docs/content/docs/openui-cloud/build/component-library.mdx
+++ /dev/null
@@ -1,172 +0,0 @@
----
-title: Component Library
-description: Use OpenUI Cloud with its built-in chat library, or bring your own components.
----
-
-## Using the built-in library
-
-Out of the box, OpenUI Cloud ships a general-purpose chat library with text, headers, tables, charts, forms, tabs, buttons, and more.
-
-Use it with `AgentInterface` on the client:
-
-```tsx
-import { chatLibrary } from "@openuidev/thesys";
-
-<AgentInterface llm={llm} componentLibrary={chatLibrary} />;
-```
-
-On the backend, `generateSystemPrompt({ cloud: true })` uses the built-in library by default. Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview); the placement of the generated instructions depends on the API:
-
-<Tabs groupId="cloud-api" items={["Responses", "Chat Completions"]} persist>
- <Tab value="Responses">
-
-```ts
-import { generateSystemPrompt } from "@openuidev/lang-core";
-
-const response = await embedClient.responses.create({
- model: "openai/gpt-5",
- input: "Show revenue by region as an interactive dashboard.",
- instructions: generateSystemPrompt({
- cloud: true,
- instructions: "Optional instructions for the model.",
- }),
-});
-```
-
- </Tab>
- <Tab value="Chat Completions">
-
-```ts
-import { generateSystemPrompt } from "@openuidev/lang-core";
-
-const completion = await embedClient.chat.completions.create({
- model: "openai/gpt-5",
- messages: [
- {
- role: "system",
- content: generateSystemPrompt({
- cloud: true,
- instructions: "Optional instructions for the model.",
- }),
- },
- { role: "user", content: "Show revenue by region as an interactive dashboard." },
- ],
-});
-```
-
- </Tab>
-</Tabs>
-
-OpenUI Cloud takes care of everything in between: the system prompt, output validation, and automatic repair all target the built-in library.
-
-## Using your own library
-
-Use your own library when the domain calls for components the generic set cannot express or when the application follows its own design system.
-
-**Define the library.** Create one [`defineComponent`](/docs/openui-lang/defining-components) per component in the frontend where your React components live. Prop schemas and descriptions are what the model sees; `id` is an optional free-form revision tag.
-
-```tsx title="src/lib/chat-library.tsx"
-import { Metric, Panel } from "@/components";
-import { createLibrary, defineComponent } from "@openuidev/react-lang";
-import { z } from "zod/v4";
-
-const MetricDef = defineComponent({
- name: "Metric",
- description: "A single KPI stat with an optional trend arrow.",
- props: z.object({
- label: z.string(),
- value: z.string(),
- trend: z.enum(["up", "down"]).optional(),
- }),
- component: ({ props }) => <Metric {...props} />,
-});
-
-const PanelDef = defineComponent({
- name: "Panel",
- description: "Top-level container. Children stack vertically.",
- props: z.object({ children: z.array(MetricDef.ref) }),
- component: ({ props, renderNode }) => <Panel>{renderNode(props.children)}</Panel>,
-});
-
-export const myLibrary = createLibrary({
- id: "acme-chat@1",
- root: "Panel",
- components: [PanelDef, MetricDef],
-});
-```
-
-**Generate the spec handover file.** [`openui generate`](/docs/api-reference/cli#openui-generate) turns the library module into a self-contained JSON file for the backend:
-
-```bash tab="pnpm" tab-group="pkg"
-pnpx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json
-```
-
-```bash tab="bun" tab-group="pkg"
-bunx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json
-```
-
-```bash tab="yarn" tab-group="pkg"
-yarn dlx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json
-```
-
-```bash tab="npm" tab-group="pkg"
-npx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json
-```
-
-**Declare it in the backend call.** Import the generated JSON and pass it as `library`.
-
-<Tabs groupId="cloud-api" items={["Responses", "Chat Completions"]} persist>
- <Tab value="Responses">
-
-```diff
-+ import librarySpec from "./generated/library-spec.json";
-
- const response = await embedClient.responses.create({
- model: "openai/gpt-5",
- input,
- instructions: generateSystemPrompt({
- cloud: true,
- instructions: "Optional instructions for the model.",
-+ library: librarySpec,
-+ promptOptions: { preamble: "You build dashboards for Acme operators." },
- }),
- });
-```
-
- </Tab>
- <Tab value="Chat Completions">
-
-```diff
-+ import librarySpec from "./generated/library-spec.json";
-
- const completion = await embedClient.chat.completions.create({
- model: "openai/gpt-5",
- messages: [
- {
- role: "system",
- content: generateSystemPrompt({
- cloud: true,
- instructions: "Optional instructions for the model.",
-+ library: librarySpec,
-+ promptOptions: { preamble: "You build dashboards for Acme operators." },
- }),
- },
- ...messages,
- ],
- });
-```
-
- </Tab>
-</Tabs>
-
-`promptOptions` is valid only alongside `library`. Use `preamble`, `additionalRules`, and `examples` to tune the generated prompt.
-
-**Swap the client library:**
-
-```diff
-- import { chatLibrary } from "@openuidev/thesys";
-+ import { myLibrary } from "@/lib/chat-library";
-
-- <AgentInterface llm={llm} componentLibrary={chatLibrary} />;
-+ <AgentInterface llm={llm} componentLibrary={myLibrary} />;
-```
diff --git a/docs/content/docs/openui-cloud/build/reports.mdx b/docs/content/docs/openui-cloud/build/reports.mdx
deleted file mode 100644
index abe4cc554..000000000
--- a/docs/content/docs/openui-cloud/build/reports.mdx
+++ /dev/null
@@ -1,84 +0,0 @@
----
-title: Reports
-description: "Generate long-form reports with rich components, manual editing, a dedicated viewer, and PDF export."
----
-
-Using OpenUI Cloud, agents can generate long-form reports from a prompt or conversation with rich components for metrics, charts, tables, images, and structured content.
-
-Generated reports open in a dedicated viewer for reading, review, and manual editing. Reports can also be refined through conversation, every version is stored, and the finished document can be exported to PDF.
-
-<video
- src="/videos/openui-cloud/reports/full-report.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-Reports are built with the following components.
-
-### Pages
-
-Page components include standard, minimal, and dramatic front pages, content pages, and a generated table of contents. They give a report its overall structure.
-
-<video
- src="/videos/openui-cloud/reports/report-pages.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-### Text
-
-Text components include prose, inline headers, headlines, and statements that carry the narrative sections of a document.
-
-<video
- src="/videos/openui-cloud/reports/report-section.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-### Metrics
-
-Metric components include key metrics, key statements, spotlight metrics, and numbered key points that present the figures a report is built around.
-
-<video
- src="/videos/openui-cloud/reports/report-metrics.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-### Tables and collections
-
-Collection components include lists, tables, summary grids, mini cards, feature highlights, tags, and visual cards that organize comparisons and groupings.
-
-<video
- src="/videos/openui-cloud/reports/report-tables.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-### Charts and media
-
-Chart and image components include interactive bar, line, area, and pie charts, along with image blocks that visualize data and illustrate the content.
-
-<video
- src="/videos/openui-cloud/reports/report-chart-media.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
diff --git a/docs/content/docs/openui-cloud/build/slides.mdx b/docs/content/docs/openui-cloud/build/slides.mdx
deleted file mode 100644
index becbd3624..000000000
--- a/docs/content/docs/openui-cloud/build/slides.mdx
+++ /dev/null
@@ -1,180 +0,0 @@
----
-title: Slides
-description: "Generate presentations with well-designed templates, manual editing, an interactive viewer, and PowerPoint export."
----
-
-Using OpenUI Cloud, agents can generate presentations from a prompt or conversation with well-designed templates for titles, charts, images, comparisons, and other common slide layouts.
-
-Generated decks open in an interactive viewer where you can review the presentation, edit slides manually, and export the finished deck to PowerPoint. Decks can also be refined through conversation, and every version is stored automatically.
-
-## Title slides
-
-### Standard title
-
-A bold heading with an optional subtitle and helper label, and an image placed beside or below the text.
-
-<img src="/images/openui-cloud/slides/slide_1.png" alt="Template preview: Standard title" className="w-full rounded-lg border" />
-
-### Minimal title
-
-A large heading with an optional subtitle and a meta row carrying an author block and helper label. Supports a full-bleed background image.
-
-<img src="/images/openui-cloud/slides/slide_2.png" alt="Template preview: Minimal title" className="w-full rounded-lg border" />
-
-### Dramatic title
-
-An oversized heading for high-impact openings, stacked or side-by-side with a subtitle column, with an optional full-bleed background image.
-
-<img src="/images/openui-cloud/slides/slide_3.png" alt="Template preview: Dramatic title" className="w-full rounded-lg border" />
-
-## Content slides
-
-### Content classic
-
-A numbered list with a section title and up to 16 items; typography scales and items flow into two columns as the list grows.
-
-<img src="/images/openui-cloud/slides/slide_4.png" alt="Template preview: Content classic" className="w-full rounded-lg border" />
-
-### Content expressive
-
-A titleless numbered list at large display size, suited to short, emphatic lists.
-
-<img src="/images/openui-cloud/slides/slide_5.png" alt="Template preview: Content expressive" className="w-full rounded-lg border" />
-
-## Section breaks
-
-### Section break classic
-
-A single centered heading marking a new chapter, with an optional full-bleed background image.
-
-<img src="/images/openui-cloud/slides/slide_6.png" alt="Template preview: Section break classic" className="w-full rounded-lg border" />
-
-### Section break dramatic
-
-A dominant title with a supporting paragraph, in horizontal or stacked arrangements, with an optional background image.
-
-<img src="/images/openui-cloud/slides/slide_7.png" alt="Template preview: Section break dramatic" className="w-full rounded-lg border" />
-
-## Key figure slides
-
-### Hero metric
-
-A single headline metric with a caption, stacked or side-by-side, with an optional full-bleed background.
-
-<img src="/images/openui-cloud/slides/slide_8.png" alt="Template preview: Hero metric" className="w-full rounded-lg border" />
-
-### Insight grid
-
-A grid of five to nine insight tiles, each with primary and secondary text on a color or image background.
-
-<img src="/images/openui-cloud/slides/slide_9.png" alt="Template preview: Insight grid" className="w-full rounded-lg border" />
-
-### Feature highlights
-
-Two to four feature tiles, each with an icon, text, and a color or image background.
-
-<img src="/images/openui-cloud/slides/slide_10.png" alt="Template preview: Feature highlights" className="w-full rounded-lg border" />
-
-### Headline statement
-
-A two-line statement with an eyebrow and headline, plus an optional full-bleed background image.
-
-<img src="/images/openui-cloud/slides/slide_11.png" alt="Template preview: Headline statement" className="w-full rounded-lg border" />
-
-### Key info
-
-Up to six title-and-description items distributed across one or two columns.
-
-<img src="/images/openui-cloud/slides/slide_12.png" alt="Template preview: Key info" className="w-full rounded-lg border" />
-
-### Key info with title
-
-A titled set of two to six key info items in grid or list arrangements.
-
-<img src="/images/openui-cloud/slides/slide_13.png" alt="Template preview: Key info with title" className="w-full rounded-lg border" />
-
-### Numbered key points
-
-Two to eight numbered points with title and body, arranged to fit the count.
-
-<img src="/images/openui-cloud/slides/slide_14.png" alt="Template preview: Numbered key points" className="w-full rounded-lg border" />
-
-## Chart slides
-
-### Chart with context
-
-A titled slide with one chart and an optional body paragraph, in five layout variants.
-
-<img src="/images/openui-cloud/slides/slide_15.png" alt="Template preview: Chart with context" className="w-full rounded-lg border" />
-
-### Chart with metrics
-
-Up to four metric callouts on the left with a chart on the right.
-
-<img src="/images/openui-cloud/slides/slide_16.png" alt="Template preview: Chart with metrics" className="w-full rounded-lg border" />
-
-### Dual charts with context
-
-One or two side-by-side chart cards, each with a short title and caption, suited to comparisons.
-
-<img src="/images/openui-cloud/slides/slide_17.png" alt="Template preview: Dual charts with context" className="w-full rounded-lg border" />
-
-### Pie and radial with context
-
-A slide dedicated to pie or radial charts, with a large title on the left and the chart filling the right.
-
-<img src="/images/openui-cloud/slides/slide_18.png" alt="Template preview: Pie and radial with context" className="w-full rounded-lg border" />
-
-## Image slides
-
-### Images
-
-One to four images in an adaptive grid, suited to photo-forward moments with no text.
-
-<img src="/images/openui-cloud/slides/slide_19.png" alt="Template preview: Images" className="w-full rounded-lg border" />
-
-## Image with text slides
-
-### Content with image
-
-A title and optional body paired with an image grid, with image-right and image-center layouts.
-
-<img src="/images/openui-cloud/slides/slide_20.png" alt="Template preview: Content with image" className="w-full rounded-lg border" />
-
-### List with image
-
-Up to four icon list items on the left, paired with a square image grid on the right.
-
-<img src="/images/openui-cloud/slides/slide_21.png" alt="Template preview: List with image" className="w-full rounded-lg border" />
-
-### Metrics with image
-
-Up to four metrics on the left, paired with a square image grid on the right.
-
-<img src="/images/openui-cloud/slides/slide_22.png" alt="Template preview: Metrics with image" className="w-full rounded-lg border" />
-
-### Personnel showcase
-
-A titled grid of up to eight people, with a portrait, name, title, and optional bio for each.
-
-<img src="/images/openui-cloud/slides/slide_23.png" alt="Template preview: Personnel showcase" className="w-full rounded-lg border" />
-
-### Visual cards
-
-A titled row of up to four cards combining image, title, and body.
-
-<img src="/images/openui-cloud/slides/slide_24.png" alt="Template preview: Visual cards" className="w-full rounded-lg border" />
-
-## Text slides
-
-### Text body
-
-A title with multiple body paragraphs, in centered or left-anchored layouts.
-
-<img src="/images/openui-cloud/slides/slide_25.png" alt="Template preview: Text body" className="w-full rounded-lg border" />
-
-### Pull quote
-
-A quotation with an optional author line, centered or top-anchored, over an optional background image.
-
-<img src="/images/openui-cloud/slides/slide_26.png" alt="Template preview: Pull quote" className="w-full rounded-lg border" />
diff --git a/docs/content/docs/openui-cloud/get-started.mdx b/docs/content/docs/openui-cloud/get-started.mdx
deleted file mode 100644
index 0467047f6..000000000
--- a/docs/content/docs/openui-cloud/get-started.mdx
+++ /dev/null
@@ -1,69 +0,0 @@
----
-title: Get Started
-description: "Scaffold an application with generative UI, slides, reports, and conversation history on OpenUI Cloud."
----
-
-The OpenUI CLI scaffolds a Next.js application connected to OpenUI Cloud with streaming generative UI, slides, reports, and conversation history. The CLI walks through setup, including the API key.
-
-<video
- src="/videos/agent/quickstart-inline-generative-ui.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-## Create
-
-Run the create command and answer the prompts. The template option selects **OpenUI Cloud**.
-
-```bash tab="pnpm" tab-group="pkg"
-pnpx @openuidev/cli@latest create --template openui-cloud
-```
-
-```bash tab="bun" tab-group="pkg"
-bunx @openuidev/cli@latest create --template openui-cloud
-```
-
-```bash tab="yarn" tab-group="pkg"
-yarn dlx @openuidev/cli@latest create --template openui-cloud
-```
-
-```bash tab="npm" tab-group="pkg"
-npx @openuidev/cli@latest create --template openui-cloud
-```
-
-To add a provider key or choose a supported model, see [Models and BYOK](/docs/openui-cloud/models-and-byok).
-
-## Run
-
-Start the dev server:
-
-```bash tab="pnpm" tab-group="pkg"
-pnpm dev
-```
-
-```bash tab="bun" tab-group="pkg"
-bun dev
-```
-
-```bash tab="yarn" tab-group="pkg"
-yarn dev
-```
-
-```bash tab="npm" tab-group="pkg"
-npm run dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) and send a message. Ask for a chart, then a slide deck on the same topic. Close the tab and return. The conversation is still there.
-
-## What the scaffold includes
-
-- A working chat interface where responses render as interactive components.
-- A server route connected to the [Responses API](/docs/openui-cloud/api/responses).
-- Slides and reports enabled out of the box.
-- Conversation history and artifact storage, with no database to set up.
-- A codebase ready to be shaped into a product.
-
-For the capabilities in detail, see [Introduction](/docs/openui-cloud). For a technical overview of the architecture, see [How it works](/docs/openui-cloud/how-it-works).
diff --git a/docs/content/docs/openui-cloud/how-it-works.mdx b/docs/content/docs/openui-cloud/how-it-works.mdx
deleted file mode 100644
index c874c7149..000000000
--- a/docs/content/docs/openui-cloud/how-it-works.mdx
+++ /dev/null
@@ -1,130 +0,0 @@
----
-title: How it works
-description: "Learn how OpenUI Cloud handles model access, automatic fallbacks, output validation, slides, reports, and conversation persistence."
----
-
-## Overview
-
-Generative UI puts model output directly in front of users, and raw model output is not reliable enough for that. OpenUI Cloud sits between the application and the model. It can act as a compatible model gateway or assemble and validate renderable OpenUI Lang for generative UI.
-
-OpenUI Cloud exposes four API surfaces, summarized in the [API overview](/docs/openui-cloud/api/overview):
-
-- **[Responses API](/docs/openui-cloud/api/responses):** The recommended generation endpoint for new agent applications. It accepts a conversation turn and streams validated UI as **OpenUI Lang**, with persistent conversations, hosted tools, and slide and report generation in the same API.
-- **[Chat Completions (Embed)](/docs/openui-cloud/api/chat-completions):** A drop-in endpoint for applications that already use the OpenAI Chat Completions message format. It supports plain text passthrough, self-hosted or managed generative UI, and application-run function tools.
-- **[Chat Completions (Artifacts)](/docs/openui-cloud/api/artifacts):** A standalone endpoint for generating and explicitly editing slide and report programs.
-- **[Conversations API](/docs/openui-cloud/api/conversations):** Provides read and write access to stored conversation threads and items. The browser calls it directly using short-lived frontend tokens.
-
-The generation APIs integrate with AgentInterface through their matching stream adapters, while the Conversations API and artifact storage endpoints supply thread history and stored artifacts. Applications with their own UI consume the same OpenUI Lang stream with the open-source renderer.
-
-Rendering stays in the browser: responses render client-side with the application's component library, exactly as in open-source OpenUI.
-
-<Mermaid
- chart={`
-flowchart LR
- subgraph App[The application]
- P[Product code] --> A[AgentInterface]
- B[Backend route]
- end
- subgraph Cloud[OpenUI Cloud]
- R[Responses API]
- C["Chat Completions (Embed)"]
- AR["Chat Completions (Artifacts)"]
- PA[Conversations API]
- M["Model routing and fallbacks"]
- V["Output validation and correction"]
- G[Artifact generation]
- S["Conversation and artifact storage"]
- end
- A --> B
- B --> R
- B --> C
- B --> AR
- A -->|frontend token| PA
- R --> M
- R --> V
- R --> G
- R --> S
- C --> M
- C -. managed GenUI .-> V
- AR --> M
- AR --> V
- AR --> G
- PA --> S
-`}
-/>
-
-The application consists of product code, AgentInterface or a custom UI, and a backend route that holds the API key. OpenUI Cloud runs model routing, managed output validation, artifact generation, and storage.
-
-## Responses request lifecycle
-
-<Mermaid chart={`
-sequenceDiagram
- participant Browser as User's browser
- participant App as Application backend
- participant Cloud as OpenUI Cloud
- participant Models as Model providers
-
- Browser->>App: Message from AgentInterface
- App->>Cloud: Responses API call (new turn + conversation reference)
- Cloud->>Models: Request to the selected model
- Models-->>Cloud: Raw model output
- Note over Cloud: Output validated and corrected
- Cloud-->>App: Stream of renderable UI
- App-->>Browser: Stream relayed, interface renders progressively
- Note over Cloud: Turn persisted to the conversation
-
-`} />
-
-1. The user sends a message. AgentInterface posts it to the application backend.
-2. The backend makes one Responses API call for the new turn. The call names the model to use and references the server-side conversation, so the backend sends only the new message. Cloud supplies the earlier turns.
-3. Cloud routes the request to that model. If the model or provider is unavailable, the request reroutes to a fallback.
-4. Model output is validated and corrected before it leaves Cloud.
-5. The response streams back through the backend to the browser, and the interface renders progressively as it arrives.
-6. The turn's messages, actions, and outputs persist to the conversation. Actions include user interactions with generated components, such as button clicks and form submissions.
-
-## Chat Completions request lifecycle
-
-Chat Completions uses the application's existing `messages` array. The application sends the relevant conversation history, OpenUI Cloud routes the request to the selected provider model, and the endpoint returns either text or OpenUI Lang in the standard Chat Completions response shape.
-
-Plain passthrough requests receive no injected generative UI prompt. For managed generative UI, a server helper places an OpenUI configuration sentinel in the system message so Cloud can assemble the prompt and validate the generated program. Function tools are returned to the application for execution; hosted search and MCP tools remain on the Responses API.
-
-Standalone slides and reports use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts). The application sends artifact metadata with a prompt and receives a raw OpenUI Lang artifact program. Editing sends the current program back as an assistant message with `is_edit: true`.
-
-## Output validation
-
-Each managed generative UI and artifact response is checked against the component library it was generated for. By default, that is OpenUI Cloud's pre-tested, responsive, and accessible component library. An application can instead register its own component library, including its component schema, generated prompt, and custom components. Invalid output, including malformed structures, unknown components, and unrenderable content, is corrected in the streaming path before it reaches the client. Differences between model providers and versions are normalized at the same stage, so rendered behavior stays consistent when the underlying model changes.
-
-Plain text passthrough and self-hosted generative UI prompts do not use managed validation; the application owns validation in those modes.
-
-## Artifact generation
-
-With the Responses API, a request declares which artifact types are allowed and the model produces them inside the same stream as the conversation. Slides and reports are stored and versioned automatically, and follow-up turns can edit them.
-
-With Chat Completions, the dedicated artifact endpoint returns a raw OpenUI Lang program. The application supplies the current program explicitly when requesting an edit. Both APIs use the same managed presentation and report viewers. Slides can be exported to PowerPoint, and reports can be exported to PDF.
-
-## Conversation persistence
-
-Responses API conversations can be stored server-side. Each turn's messages, actions, and outputs attach to a conversation thread, and generation calls reference the thread instead of resending its history. The application backend stores no chat history and runs no database. On load, AgentInterface reads threads from the Conversations API and artifacts from the storage plane.
-
-Chat Completions applications own their message history and resend the relevant messages on each turn. Choose the Responses API when Cloud-managed conversation persistence is required.
-
-## Authentication
-
-Two credentials with different scopes:
-
-- **API key:** Authorizes generation calls and frontend-token minting. It is held by the application backend and is never sent to the browser.
-- **Frontend tokens:** Short-lived tokens that the application backend requests from Cloud and returns to the browser. The browser uses them to read conversations and artifacts without the backend proxying each read. Tokens expire within minutes, and AgentInterface requests a fresh token from the backend before expiry.
-
-<Mermaid chart={`
-sequenceDiagram
- participant Browser as User's browser
- participant App as Application backend
- participant Cloud as OpenUI Cloud
-
- Browser->>App: Frontend token request
- App->>Cloud: Mint request, authorized with the API key
- Cloud-->>App: Short-lived frontend token
- App-->>Browser: Frontend token
- Browser->>Cloud: Reads conversations and artifacts
-
-`} />
diff --git a/docs/content/docs/openui-cloud/index.mdx b/docs/content/docs/openui-cloud/index.mdx
deleted file mode 100644
index e14d28cc7..000000000
--- a/docs/content/docs/openui-cloud/index.mdx
+++ /dev/null
@@ -1,128 +0,0 @@
----
-title: Introduction
-description: "Build production-ready AI experiences with generative UI, presentations, and reports, backed by reliable model access and output validation."
----
-
-OpenUI Cloud is a managed platform for building production-ready AI experiences that go beyond text. Agents can respond with interactive interfaces, generate editable presentations, and create rich long-form reports, all directly from a conversation.
-
-It combines OpenUI's generative UI capabilities with reliable model access, automatic fallbacks, and output validation.
-
-<video
- src="/videos/agent/agent-interface-hero.mp4"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-## What you get
-
-1. **Production hardening:** Run generative UI reliably in production with managed model access, automatic fallbacks, and output validation. Requests are rerouted when a model or provider is unavailable, and generated output is validated before it reaches the interface.
-2. **Bring your own model key (BYOK):** Use your own OpenAI, Anthropic, or Google API key with OpenUI Cloud on any plan, including the free tier. See [Models and BYOK](/docs/openui-cloud/models-and-byok).
-3. **Generative UI for agents:** Let agents respond with rich, interactive interfaces instead of walls of text. Each response can assemble the components best suited to the task.
- - **Built-in component library:** Use a pre-tested, responsive, and accessible set of components: forms, inputs, interactive charts, accordions, tabs, and other layout components.
- - **Bring your own component library:** Generate interfaces using your own components and design system while OpenUI Cloud provides model reliability, output validation, and observability.
-4. **Slides:** Generate presentations from conversations using well-designed templates for charts, images, and structured content. Review decks in an interactive viewer, edit slides manually, and export them to PowerPoint.
-5. **Reports:** Generate long-form documents from conversations using rich components for metrics, charts, tables, images, and structured content. Review reports in a dedicated viewer and export them to PDF.
-
-## OpenUI vs. OpenUI Cloud
-
-| Capability | OpenUI | OpenUI Cloud |
-|---|---|---|
-| Generative UI rendering | Included | Included |
-| Streaming and progressive rendering | Included | Included |
-| Component library | ⚠️ Basic component library | Production-ready built-in library or bring your own |
-| Model access and automatic fallbacks | Not included | Included |
-| Output validation | Not included | Included |
-| Observability | Not included | Included |
-| Slides | Not included | Interactive viewer, manual editing, and PowerPoint export |
-| Reports | Not included | Dedicated viewer, manual editing, and PDF export |
-
-## Production hardening
-
-Generative UI depends on models and providers that can fail, slow down, or return invalid output. OpenUI Cloud handles these production concerns for you.
-
-Requests are automatically routed to a fallback when the selected model or provider is unavailable. Generated output is validated against the component library before it reaches the interface, preventing malformed structures and unsupported components from being rendered.
-
-<div className="my-6 rounded-lg border p-4">
- <div className="flex flex-col items-center gap-3 md:flex-row">
- <div className="w-full rounded-md border p-3 text-center text-sm font-medium">
- Request
- </div>
- <span className="rotate-90 text-xl text-fd-muted-foreground md:rotate-0" aria-hidden="true">→</span>
- <div className="w-full rounded-md border p-3 text-center text-sm font-medium">
- Model routing and fallback
- </div>
- <span className="rotate-90 text-xl text-fd-muted-foreground md:rotate-0" aria-hidden="true">→</span>
- <div className="w-full rounded-md border p-3 text-center text-sm font-medium">
- Output validation
- </div>
- <span className="rotate-90 text-xl text-fd-muted-foreground md:rotate-0" aria-hidden="true">→</span>
- <div className="w-full rounded-md border p-3 text-center text-sm font-medium">
- Interface
- </div>
- </div>
- <div className="mt-3 rounded-md border border-dashed p-3 text-center text-sm text-fd-muted-foreground">
- <span className="font-medium text-fd-foreground">Observability</span> across model usage, latency, errors, and render success
- </div>
-</div>
-
-## Choose an API
-
-<Cards>
- <Card title="API overview" href="/docs/openui-cloud/api/overview">
- Compare the Responses, Embed Chat Completions, Artifact Chat Completions, and Conversations
- APIs, then open the focused guide for the surface you need.
- </Card>
-</Cards>
-
-## Generative UI for agents
-
-Agents can respond with interfaces that match the task instead of returning only text. They can present a form to collect information, visualize data with a chart, or organize a detailed response with tabs and accordions.
-
-### Built-in component library
-
-OpenUI Cloud includes a pre-tested, responsive, and accessible set of components for forms, inputs, charts, content organization, and interactive actions.
-
-<div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
- <video src="/videos/agent/generative-ui-form-interaction.mp4" poster="/images/openui-cloud/posters/generative-ui-form-interaction.jpg" autoPlay loop muted playsInline className="w-full rounded-lg border" />
- <video src="/videos/openui-cloud/chat/charts-visualizations.mp4" poster="/images/openui-cloud/posters/charts-visualizations.jpg" autoPlay loop muted playsInline className="w-full rounded-lg border" />
- <video src="/videos/openui-cloud/chat/content-organization.mp4" poster="/images/openui-cloud/posters/content-organization.jpg" autoPlay loop muted playsInline className="w-full rounded-lg border" />
- <video src="/videos/openui-cloud/chat/buttons-and-actions.mp4" poster="/images/openui-cloud/posters/buttons-and-actions.jpg" autoPlay loop muted playsInline className="w-full rounded-lg border" />
-</div>
-
-### Bring your own component library
-
-Connect your own design system and domain-specific components. Agents can use them to generate interfaces while OpenUI Cloud provides model reliability, output validation, and observability.
-
-## Slides
-
-Using OpenUI Cloud, agents can generate presentations from conversations with well-designed templates for titles, charts, images, comparisons, and other common slide layouts.
-
-Generated decks open in an interactive viewer where you can review the presentation, edit slides manually, and export the finished deck to PowerPoint.
-
-<div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
- <img src="/images/openui-cloud/slides/slide_3.png" alt="Dramatic title slide" className="w-full rounded-lg border" />
- <img src="/images/openui-cloud/slides/slide_9.png" alt="Insight grid slide" className="w-full rounded-lg border" />
- <img src="/images/openui-cloud/slides/slide_15.png" alt="Chart with context slide" className="w-full rounded-lg border" />
- <img src="/images/openui-cloud/slides/slide_23.png" alt="Personnel showcase slide" className="w-full rounded-lg border" />
-</div>
-
-## Reports
-
-Using OpenUI Cloud, agents can generate long-form reports from conversations with rich components for metrics, charts, tables, images, and structured content.
-
-Generated reports open in a dedicated viewer for reading and review, and can be exported to PDF.
-
-<video
- src="/videos/openui-cloud/reports/full-report.mp4"
- poster="/images/openui-cloud/posters/full-report.jpg"
- autoPlay
- loop
- muted
- playsInline
- className="w-full rounded-lg border"
-/>
-
-To build your first application, see [Get Started](/docs/openui-cloud/get-started). To learn more about the architecture, see [How it works](/docs/openui-cloud/how-it-works).
diff --git a/docs/content/docs/openui-cloud/meta.json b/docs/content/docs/openui-cloud/meta.json
deleted file mode 100644
index 89042e5e9..000000000
--- a/docs/content/docs/openui-cloud/meta.json
+++ /dev/null
@@ -1,22 +0,0 @@
-{
- "title": "OpenUI Cloud",
- "root": true,
- "pages": [
- "index",
- "get-started",
- "how-it-works",
- "---APIs---",
- "api/overview",
- "api/responses",
- "api/chat-completions",
- "api/artifacts",
- "api/conversations",
- "models-and-byok",
- "---Features---",
- "build/component-library",
- "build/chat",
- "build/slides",
- "build/reports",
- "production-readiness"
- ]
-}
diff --git a/docs/content/docs/openui-cloud/models-and-byok.mdx b/docs/content/docs/openui-cloud/models-and-byok.mdx
deleted file mode 100644
index 3db5e981d..000000000
--- a/docs/content/docs/openui-cloud/models-and-byok.mdx
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: Models and BYOK
-description: "Configure provider keys and choose supported models for OpenUI Cloud generation APIs."
----
-
-import { CopyableModelId } from "@/components/copyable-model-id";
-
-OpenUI Cloud supports both managed model access and bring your own key (BYOK). Both use the same `provider/model` identifiers.
-
-## Bring your own key
-
-Add an OpenAI, Anthropic, or Google API key from the [BYOK page in the Thesys console](https://console.thesys.dev/byok). BYOK is available on every plan, including the free tier.
-
-Only organization admins can add or update provider keys. Once a key is added, every member of the organization can use models from that provider through BYOK.
-
-### Provider-specific billing
-
-BYOK applies only to the matching provider. For example, if your organization adds an OpenAI key, requests to OpenAI models use that key. Requests to Anthropic or Google Vertex AI models are billed against OpenUI Cloud credits instead. If the organization has no credits, those requests fail with an out-of-credits error; otherwise, its credits are used for the requests.
-
-## Supported BYOK models
-
-Model identifiers follow the `provider/model` convention. For example, use `openai/gpt-5.6-sol`, not `gpt-5.6-sol`.
-
-| Provider | Model name | Model identifier |
-| --------- | ---------------------- | --------------------------------------------------------- |
-| Anthropic | Claude Opus 5 | <CopyableModelId value="anthropic/claude-opus-5" /> |
-| Anthropic | Claude Sonnet 5 | <CopyableModelId value="anthropic/claude-sonnet-5" /> |
-| Anthropic | Claude Opus 4.7 | <CopyableModelId value="anthropic/claude-opus-4-7" /> |
-| Google | Gemini 3.6 Flash | <CopyableModelId value="google/gemini-3.6-flash" /> |
-| Google | Gemini 3.5 Flash | <CopyableModelId value="google/gemini-3.5-flash" /> |
-| Google | Gemini 3.1 Pro Preview | <CopyableModelId value="google/gemini-3.1-pro-preview" /> |
-| OpenAI | GPT-5.6 Sol | <CopyableModelId value="openai/gpt-5.6-sol" /> |
-| OpenAI | GPT-5.5 | <CopyableModelId value="openai/gpt-5.5" /> |
-| OpenAI | GPT-5.4 | <CopyableModelId value="openai/gpt-5.4" /> |
-
-_This is an example list; all models available from these providers are supported with BYOK._
diff --git a/docs/content/docs/openui-cloud/production-readiness.mdx b/docs/content/docs/openui-cloud/production-readiness.mdx
deleted file mode 100644
index 8e5189a83..000000000
--- a/docs/content/docs/openui-cloud/production-readiness.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
----
-title: Production readiness
-description: "Managed model access, automatic fallbacks, output validation, conversation persistence, and observability for generative UI in production."
----
-
-OpenUI Cloud handles the reliability work required to run generative UI in production.
-
-## Reliable model access
-
-OpenUI Cloud provides managed access to models from multiple providers and automatically reroutes requests when a model or provider is unavailable.
-
-- **Model access across providers:** Applications access models from supported providers through OpenUI Cloud's APIs. Provider accounts, credentials, and connections are managed by Cloud, and model usage is billed at cost. The application names a model per request, so switching models requires no application change.
-- **Automatic fallbacks:** When a selected model or provider is unavailable, Cloud reroutes the request to a fallback without application involvement. Requests can continue during a provider outage or slowdown.
-- **Output normalization:** Generated output is normalized across providers and model versions, so an interface behaves consistently when the underlying model changes.
-
-## Output validation and correction
-
-OpenUI Cloud validates every model response before it reaches the interface and corrects invalid output in real time.
-
-- **Validation against the component library:** Each response is checked against the component library it was generated for, either the built-in library or one the application registered. Validation detects malformed structures, nonexistent components, and unrenderable content.
-- **Real-time correction:** Correction happens in the streaming path instead of as a retry the user waits through. Invalid output is corrected before it leaves Cloud.
-- **Consistency across models:** Validation and correction run server-side, so behavior stays consistent as model providers and versions change. Provider-specific differences are normalized before rendering.
-
-## Conversation persistence
-
-OpenUI Cloud stores conversations and artifacts server-side, so applications run no database or storage layer for them.
-
-- **Automatic thread storage:** Each turn's messages, actions, and outputs attach to a conversation thread. Threads can be created, read, renamed, deleted, and listed.
-- **Slide and report versioning:** Generated slides and reports are stored alongside their conversations, and every version is kept.
-- **Reload on return:** AgentInterface reloads threads, slides, and reports when the application loads. Returning users find their conversations and generated content intact.
-
-## Observability
-
-OpenUI Cloud provides built-in visibility into model usage, latency, errors, and render success across a deployment.
diff --git a/docs/content/docs/openui-lang/how-it-works.mdx b/docs/content/docs/openui-lang/architecture.mdx
similarity index 94%
rename from docs/content/docs/openui-lang/how-it-works.mdx
rename to docs/content/docs/openui-lang/architecture.mdx
index 3f52d7f90..6b633f8b1 100644
--- a/docs/content/docs/openui-lang/how-it-works.mdx
+++ b/docs/content/docs/openui-lang/architecture.mdx
@@ -3,7 +3,7 @@ title: Architecture
description: Build dashboards, CRUD interfaces, and monitoring tools. The LLM generates the UI once, then your app runs independently.
---
-import { OpenUICloudCallout } from "./components/openui-cloud-callout";
+import { GatewayCallout } from "./components/gateway-callout";
## The problem today
@@ -28,7 +28,7 @@ The Renderer parses the generated code. When it encounters a `Query("list_ticket
The LLM generated the wiring. The runtime executes it.
-<OpenUICloudCallout description="Keep generative UI reliable with output correction, model fallbacks, and monitoring." />
+<GatewayCallout description="Keep this generation path reliable in production with streaming error correction and provider fallbacks." />
## What this enables
@@ -141,16 +141,22 @@ const tools: ToolSpec[] = [
```ts
// route.ts
+import OpenAI from "openai";
import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";
import componentSpec from "./generated/component-spec.json";
+const gateway = new OpenAI({
+ apiKey: process.env.THESYS_API_KEY,
+ baseURL: "https://api.thesys.dev/v1/embed",
+});
+
const systemPrompt = generateSystemPrompt({
library: componentSpec as LibrarySpec,
promptOptions: { tools, toolCalls: true, bindings: true },
});
-const completion = await openai.chat.completions.create({
- model: "gpt-5.4-mini",
+const completion = await gateway.chat.completions.create({
+ model: "openai/gpt-5",
stream: true,
messages: [
{ role: "system", content: systemPrompt },
diff --git a/docs/content/docs/openui-lang/comparison.mdx b/docs/content/docs/openui-lang/comparison.mdx
index 2810007c4..e84c2baf3 100644
--- a/docs/content/docs/openui-lang/comparison.mdx
+++ b/docs/content/docs/openui-lang/comparison.mdx
@@ -1,15 +1,23 @@
---
-title: Feature Comparison
+title: OpenUI vs others
description: OpenUI vs json-render (Vercel), A2UI (Google), and CopilotKit OpenGenerativeUI.
---
-# The Generative UI Landscape
+Open-source Generative UI projects share a common goal: enabling agents to respond with interactive interfaces instead of only text. They differ in what the model generates, how applications control the available UI, and where the result can be rendered.
-**Four frameworks. Which one ships to production?**
+This page compares OpenUI with json-render, A2UI, and OpenGenerativeUI. These projects do not all solve the same part of the Generative UI stack, so the comparison focuses on their approach and intended use.
----
+## Generative UI frameworks
+
+- **[OpenUI](https://github.com/thesysdev/openui)** uses a compact, line-based language designed for models to generate interfaces from registered components. Its runtime supports streamed rendering, application state, data access, and user interactions.
+
+- **[json-render](https://github.com/vercel-labs/json-render)** uses streaming JSONL patches generated from a component catalog.
+
+- **[A2UI](https://github.com/google/A2UI)** is a protocol for sending declarative interface descriptions from agents to client applications. The client maps those descriptions to trusted, platform-native components.
+
+- **[OpenGenerativeUI](https://github.com/CopilotKit/OpenGenerativeUI)** focuses on open-ended visual experiences built with CopilotKit. It supports registered React components and free-form HTML or SVG rendered inside sandboxed iframes.
-## At a Glance
+## Feature comparison
| | **[OpenUI](https://github.com/thesysdev/openui)** | **[json-render](https://github.com/vercel-labs/json-render)** (Vercel) | **[A2UI](https://github.com/google/A2UI)** (Google) | **[CopilotKit OpenGenUI](https://github.com/CopilotKit/OpenGenerativeUI)** |
| -------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------- |
@@ -27,7 +35,7 @@ description: OpenUI vs json-render (Vercel), A2UI (Google), and CopilotKit OpenG
---
-## Best For
+## Choosing a framework
- **Data-driven chat UIs and dashboards** → OpenUI
- **One UI across web, mobile, PDF and email** → OpenUI
diff --git a/docs/content/docs/openui-lang/components/openui-cloud-callout.tsx b/docs/content/docs/openui-lang/components/gateway-callout.tsx
similarity index 81%
rename from docs/content/docs/openui-lang/components/openui-cloud-callout.tsx
rename to docs/content/docs/openui-lang/components/gateway-callout.tsx
index 2ecc1a961..dcfcd54ef 100644
--- a/docs/content/docs/openui-lang/components/openui-cloud-callout.tsx
+++ b/docs/content/docs/openui-lang/components/gateway-callout.tsx
@@ -1,19 +1,19 @@
import { ArrowRight } from "lucide-react";
import Link from "next/link";
-interface OpenUICloudCalloutProps {
+interface GatewayCalloutProps {
description: string;
}
-export function OpenUICloudCallout({ description }: OpenUICloudCalloutProps) {
+export function GatewayCallout({ description }: GatewayCalloutProps) {
return (
<aside className="not-prose my-6 rounded-xl border border-fd-border bg-fd-muted/30 px-4 py-3.5 text-fd-foreground">
<p className="m-0 text-base leading-7">{description}</p>
<Link
- href="/compare?pair=markdown-cloud"
+ href="/docs/gateway"
className="group mt-3 inline-flex items-center gap-1.5 rounded-lg border border-fd-border bg-transparent px-3 py-1.5 text-sm font-semibold text-fd-foreground no-underline transition-colors hover:bg-fd-accent/60 focus-visible:ring-2 focus-visible:ring-fd-ring focus-visible:ring-offset-2 focus-visible:outline-none"
>
- Try OpenUI Cloud
+ Explore the Gateway
<ArrowRight
className="size-4 transition-transform group-hover:translate-x-0.5"
aria-hidden="true"
diff --git a/docs/content/docs/openui-lang/defining-components.mdx b/docs/content/docs/openui-lang/defining-components.mdx
index 217f305ff..59373dea7 100644
--- a/docs/content/docs/openui-lang/defining-components.mdx
+++ b/docs/content/docs/openui-lang/defining-components.mdx
@@ -3,11 +3,11 @@ title: Defining Components
description: Define OpenUI components with Zod and React renderers.
---
-import { OpenUICloudCallout } from "./components/openui-cloud-callout";
+import { GatewayCallout } from "./components/gateway-callout";
Use `defineComponent(...)` to register each component and `createLibrary(...)` to assemble the library.
-<OpenUICloudCallout description="Start with responsive, accessible components for dashboards, forms, reports, and slides." />
+<GatewayCallout description="The Gateway validates generated OpenUI Lang against these component definitions and corrects schema violations in the stream." />
## Core API
@@ -76,12 +76,8 @@ To define container components that accepts multiple child components, you can u
import { defineComponent } from "@openuidev/react-lang";
import { z } from "zod/v4";
-const TextBlock = defineComponent({
- /* ... */
-});
-const CalloutBlock = defineComponent({
- /* ... */
-});
+const TextBlock = defineComponent({/* ... */});
+const CalloutBlock = defineComponent({/* ... */});
const TabItemSchema = z.object({
value: z.string(),
@@ -144,9 +140,7 @@ For the built-in libraries: `openuiLibrary` uses `Stack` (flexible layout contai
```ts
const library = createLibrary({
root: "Stack",
- components: [
- /* ... */
- ],
+ components: [/* ... */],
componentGroups: [
{ name: "Forms", components: ["Form", "FormControl", "Input", "Button", "Buttons"] },
],
diff --git a/docs/content/docs/openui-lang/examples/app-frameworks/react-native.mdx b/docs/content/docs/openui-lang/examples/app-frameworks/react-native.mdx
deleted file mode 100644
index 602694849..000000000
--- a/docs/content/docs/openui-lang/examples/app-frameworks/react-native.mdx
+++ /dev/null
@@ -1,159 +0,0 @@
----
-title: React Native
-description: stream LLM-generated UI to an Expo app that renders real native components.
----
-
-OpenUI Lang runs on React Native. This example streams LLM-generated UI to an Expo app, where `<Renderer />` turns it into real native components — not a webview, not markdown, native `Text`, `View`, and SVG charts. The stack is an Expo app paired with a Next.js backend that handles the OpenAI call.
-
-[View source on GitHub →](https://github.com/thesysdev/openui/tree/main/examples/app-frameworks/react-native)
-
-<div className="bg-[rgba(0,0,0,0.05)] dark:bg-gray-900 rounded-2xl p-2">
- <video
- src="/videos/react-native-demo.mp4"
- noControls
- playsInline
- muted
- preload="metadata"
- className="h-[600px] rounded-lg m-auto"
- autoPlay
- loop
- />
-</div>
-
-## What changes on native
-
-Three things differ from a web OpenUI Lang integration:
-
-### 1. Native primitives only
-
-There is no DOM, no HTML, no CSS. Components use `Text`, `View`, `StyleSheet` from `react-native`, and `react-native-svg` for charts:
-
-```tsx
-component: ({ props }) => <RNText style={styles.textBody}>{props.content}</RNText>;
-```
-
-### 2. Two mirror libraries
-
-`@openuidev/cli` runs in Node.js to generate the system prompt, but it can't import React Native. This will be fixed in future versions of the CLI. The solution is two files with identical schemas — one with real renderers for the app, one with null renderers for the backend:
-
-| File | Purpose |
-| ------------------------ | ------------------------------------------------------------------------- |
-| `chat-app/library.tsx` | Real React Native renderers — what runs on device |
-| `backend/src/library.ts` | Null renderers (`() => null`) — used only to generate `system-prompt.txt` |
-
-Keep these in sync: same component names, same prop schemas, same root component.
-
-## Architecture
-
-```
-Expo app -- POST /api/chat --> Next.js backend --> OpenAI
- <-- text/plain stream -- (OpenUI Lang)
-```
-
-The backend loads `src/generated/system-prompt.txt`, which is generated locally before the backend starts, forwards the conversation to OpenAI with streaming enabled, and returns raw `text/plain` chunks. The Expo app accumulates those chunks and passes the growing string into `<Renderer />`, which progressively parses and renders native UI as the response arrives.
-
-## Project layout
-
-```
-examples/app-frameworks/react-native/
-|- backend/ # Next.js API that talks to OpenAI
-\- chat-app/ # Expo app that renders streamed OpenUI Lang
-```
-
-## Run the example
-
-Run these commands from `examples/app-frameworks/react-native`.
-
-1. Install dependencies:
-
-```bash tab="pnpm" tab-group="pkg"
-cd examples/app-frameworks/react-native
-pnpm install
-```
-
-```bash tab="bun" tab-group="pkg"
-cd examples/app-frameworks/react-native
-bun install
-```
-
-```bash tab="yarn" tab-group="pkg"
-cd examples/app-frameworks/react-native
-yarn install
-```
-
-```bash tab="npm" tab-group="pkg"
-cd examples/app-frameworks/react-native
-npm install
-```
-
-2. Configure the backend:
-
-```bash
-cp backend/env.example backend/.env.local
-```
-
-Then add your OpenAI key to `backend/.env.local`:
-
-```bash
-OPENAI_API_KEY=sk-...
-```
-
-3. Generate the prompt file used by the backend:
-
-```bash tab="pnpm" tab-group="pkg"
-pnpm generate:prompt
-```
-
-```bash tab="bun" tab-group="pkg"
-bun generate:prompt
-```
-
-```bash tab="yarn" tab-group="pkg"
-yarn generate:prompt
-```
-
-```bash tab="npm" tab-group="pkg"
-npm generate:prompt
-```
-
-This generates the ignored file `backend/src/generated/system-prompt.txt` from `backend/src/library.ts`. The backend dev and build commands run this automatically; invoke it directly when you only want to refresh or inspect the generated artifacts.
-
-4. Start the Next.js backend:
-
-```bash tab="pnpm" tab-group="pkg"
-pnpm dev:backend
-```
-
-```bash tab="bun" tab-group="pkg"
-bun dev:backend
-```
-
-```bash tab="yarn" tab-group="pkg"
-yarn dev:backend
-```
-
-```bash tab="npm" tab-group="pkg"
-npm dev:backend
-```
-
-5. Start the Expo app in a second terminal:
-
-```bash tab="pnpm" tab-group="pkg"
-pnpm dev:mobile
-```
-
-```bash tab="bun" tab-group="pkg"
-bun dev:mobile
-```
-
-```bash tab="yarn" tab-group="pkg"
-yarn dev:mobile
-```
-
-```bash tab="npm" tab-group="pkg"
-npm dev:mobile
-```
-
-By default, `chat-app/metro.config.js` auto-detects your local IP address and sets `EXPO_PUBLIC_BACKEND_URL` to `http://<your-ip>:3000/api/chat`. If you need to point the app somewhere else, set `EXPO_PUBLIC_BACKEND_URL` yourself before starting Expo.
-
-If you are testing on a physical device, make sure the phone and your development machine are on the same network.
diff --git a/docs/content/docs/openui-lang/examples/design-systems/shadcn.mdx b/docs/content/docs/openui-lang/examples/design-systems/shadcn.mdx
index 1367b9b84..aa5f05cdf 100644
--- a/docs/content/docs/openui-lang/examples/design-systems/shadcn.mdx
+++ b/docs/content/docs/openui-lang/examples/design-systems/shadcn.mdx
@@ -64,11 +64,11 @@ See [Defining Components](/docs/openui-lang/defining-components) for the full `d
## Architecture
```
-Browser (AgentInterface) -- POST /api/chat --> Next.js route --> OpenAI
- <-- SSE stream -- (OpenUI Lang + tool calls)
+Browser (AgentInterface) -- POST /api/chat --> Next.js route --> Gateway --> model
+ <-- SSE stream -- (corrected OpenUI Lang)
```
-The client sends a conversation to `/api/chat`. The API route loads a generated `system-prompt.txt`, forwards the messages to the LLM with streaming and tool definitions, and returns SSE events. On the client, `openAIAdapter()` parses the SSE stream and `shadcnChatLibrary` maps each OpenUI Lang node to a shadcn/ui component that renders progressively as tokens arrive.
+The client sends a conversation to `/api/chat`. The API route loads the generated component instructions, sends the messages through the [Gateway](/docs/gateway), and returns SSE events. On the client, the stream adapter parses the response and `shadcnChatLibrary` maps each OpenUI Lang node to a shadcn/ui component that renders progressively as tokens arrive.
The key decoupling: the server streams OpenUI Lang — an abstract description of UI structure. The client's `shadcnChatLibrary` decides how each node renders. That's where shadcn/ui enters, and that's also where you'd plug in any other design system.
@@ -114,7 +114,7 @@ npm install
2. Create a `.env.local` file with your API key:
```bash
-OPENAI_API_KEY=sk-...
+THESYS_API_KEY=sk-th-...
```
3. Start the dev server:
diff --git a/docs/content/docs/openui-lang/examples/miscellaneous/react-email.mdx b/docs/content/docs/openui-lang/examples/miscellaneous/react-email.mdx
index 3f0f616de..b0ef6de3e 100644
--- a/docs/content/docs/openui-lang/examples/miscellaneous/react-email.mdx
+++ b/docs/content/docs/openui-lang/examples/miscellaneous/react-email.mdx
@@ -68,11 +68,11 @@ See [Defining Components](/docs/openui-lang/defining-components) for the full `d
## Architecture
```
-Browser (email editor) -- POST /api/chat --> Next.js route --> OpenAI
- <-- SSE stream -- (OpenUI Lang)
+Browser (email editor) -- POST /api/chat --> Next.js route --> Gateway --> model
+ <-- SSE stream -- (corrected OpenUI Lang)
```
-The client sends a conversation to `/api/chat`. The API route loads `system-prompt.txt`, generated locally from `emailLibrary.prompt(emailPromptOptions)`, forwards messages to the LLM with streaming, and returns SSE events. On the client, `emailLibrary` maps each OpenUI Lang node to a React Email component that renders progressively as tokens arrive.
+The client sends a conversation to `/api/chat`. The API route loads the generated `emailLibrary` instructions, sends messages through the [Gateway](/docs/gateway) with streaming, and returns SSE events. On the client, `emailLibrary` maps each OpenUI Lang node to a React Email component that renders progressively as tokens arrive.
The key difference from other examples: the output isn't interactive UI — it's static email content. The split-view editor shows a live preview on the right and formatted HTML on the left, with copy buttons for both the HTML and the subject line.
@@ -124,7 +124,7 @@ npm install
2. Create a `.env.local` file with your API key:
```bash
-OPENAI_API_KEY=sk-...
+THESYS_API_KEY=sk-th-...
```
3. Start the dev server:
diff --git a/docs/content/docs/openui-lang/index.mdx b/docs/content/docs/openui-lang/index.mdx
index 002a5d3c6..730528630 100644
--- a/docs/content/docs/openui-lang/index.mdx
+++ b/docs/content/docs/openui-lang/index.mdx
@@ -3,20 +3,11 @@ title: Introduction
---
import { StreamingComparison } from "@/app/docs/openui-lang/streaming-comparison";
-import { OpenUICloudCallout } from "./components/openui-cloud-callout";
-import { TryItOut } from "./components/try-it-out";
+import { GatewayCallout } from "./components/gateway-callout";
-OpenUI is a full-stack, renderer-agnostic Generative UI framework built around a compact, streaming-first language. It offers official React support with built-in component libraries and ready-to-use chat interfaces, plus community-supported integrations for other frameworks. OpenUI Lang uses up to **[67% fewer tokens](/docs/openui-lang/benchmarks)** than JSON. Generate anything from rich chat responses to [fully interactive dashboards](/docs/openui-lang/how-it-works).
+OpenUI Lang is an open, compact language for describing interfaces with components your application controls. Models generate it efficiently, renderers can display it progressively, and applications can use it with any model provider, agent framework, or chat library.
-<OpenUICloudCallout description="Take generative UI to production with responsive interfaces, editable artifacts, and built-in reliability." />
-
-## What is Generative UI?
-
-Most AI applications are limited to returning text (as markdown) or rendering pre-built UI responses. Markdown isn't interactive, and pre-built responses are rigid (they don't adapt to the context of the conversation).
-
-Generative UI fundamentally changes this relationship. Instead of merely providing content, the AI composes the interface itself. It dynamically selects, configures, and composes components from a predefined library to create a purpose-built interface tailored to the user's immediate request, be it an interactive chart, a complex form, or a multi-tab dashboard.
-
-<TryItOut />
+<GatewayCallout description="For production, route generation through the Gateway to correct invalid OpenUI Lang while it streams and recover from provider failures." />
## Architecture at a Glance
@@ -28,7 +19,7 @@ Generative UI fundamentally changes this relationship. Instead of merely providi
3. **Streaming render**: On the client, the `<Renderer />` component parses each line as it arrives and maps it to your React components in real-time. Structure renders first, then data fills in progressively.
-The result is a native UI dynamically composed by the AI, streamed efficiently, and rendered safely from your own components. For data-driven apps with live tools and reactive state, see [Architecture](/docs/openui-lang/how-it-works).
+The result is a native UI dynamically composed by the AI, streamed efficiently, and rendered safely from your own components. For data-driven apps with live tools and reactive state, see [Architecture](/docs/openui-lang/architecture).
## OpenUI Lang
@@ -51,7 +42,7 @@ OpenUI Lang was created to solve these core issues:
## What can you build?
<Cards>
- <Card title="Dashboards & Apps" href="/docs/openui-lang/how-it-works">
+ <Card title="Dashboards & Apps" href="/docs/openui-lang/architecture">
Data-driven dashboards, CRUD interfaces, and monitoring tools, powered by live data from your
tools.
</Card>
diff --git a/docs/content/docs/openui-lang/meta.json b/docs/content/docs/openui-lang/meta.json
index 3f408c896..d3224b208 100644
--- a/docs/content/docs/openui-lang/meta.json
+++ b/docs/content/docs/openui-lang/meta.json
@@ -1,9 +1,8 @@
{
- "title": "OpenUI",
+ "title": "OpenUI Lang",
"root": true,
"pages": [
"index",
- "comparison",
"quickstart",
"---Core Concepts---",
"overview",
@@ -13,15 +12,15 @@
"interactivity",
"reliability",
"---Building Apps---",
- "how-it-works",
+ "architecture",
"reactive-state",
"queries-mutations",
"incremental-editing",
"builtins",
"patterns",
"---Language Specification---",
- "specification-v01",
"specification-v05",
+ "specification-v01",
"evolution-guide",
"---Advanced---",
"developer-tools",
@@ -30,12 +29,6 @@
"telemetry",
"---Examples---",
"examples/design-systems/shadcn",
- "examples/app-frameworks/react-native",
- "examples/agent-frameworks/vercel-ai-sdk",
- "examples/agent-frameworks/langgraph-platform",
- "examples/miscellaneous/react-email",
- "---Harnesses---",
- "examples/harnesses/pi",
- "examples/agent-frameworks/vercel-eve"
+ "examples/miscellaneous/react-email"
]
}
diff --git a/docs/content/docs/openui-lang/overview.mdx b/docs/content/docs/openui-lang/overview.mdx
index ac700f27a..46c830b48 100644
--- a/docs/content/docs/openui-lang/overview.mdx
+++ b/docs/content/docs/openui-lang/overview.mdx
@@ -1,83 +1,43 @@
---
title: Overview
-description: Key building blocks of the OpenUI framework and the built-in component libraries.
+description: Understand the language, prompt, parser, and renderer that turn model output into application UI.
---
import { LangExample } from "./components/lang-example";
-import { OpenUICloudCallout } from "./components/openui-cloud-callout";
+import { GatewayCallout } from "./components/gateway-callout";
-OpenUI is built around four core building blocks that work together to turn LLM output into rendered UI:
+OpenUI Lang is the contract between a model and your application. You define the components the
+model may use, generate instructions from those definitions, and stream the model's OpenUI Lang
+response into a renderer.
-- **Library**: A collection of components defined with Zod schemas and React renderers. The library is the contract between your app and the AI, defining what components the LLM can use and how they render.
+Four pieces make that flow work:
-- **Prompt Generator**: Converts your library into a system prompt that instructs the LLM to output valid OpenUI Lang. Includes syntax rules, component signatures, streaming guidelines, and your custom examples/rules.
+- **Component library:** Your Zod schemas and framework components define what the model can use and
+ how each element behaves in your application.
+- **System prompt:** The prompt generator turns that library into component signatures, language
+ rules, examples, and streaming instructions for the model.
+- **Parser:** The streaming parser turns OpenUI Lang into a typed element tree, validates component
+ usage, and handles partial output while tokens arrive.
+- **Renderer:** The renderer maps the parsed tree to your components so the result uses your design
+ system and application behavior.
-- **Parser**: Parses OpenUI Lang text (line-by-line, streaming-compatible) into a typed element tree. Validates against your library's JSON Schema and gracefully handles partial/invalid output.
+<GatewayCallout description="Use the Gateway as the default production generation path, then add Observability to inspect errors from real traffic." />
-- **Renderer**: The `<Renderer />` React component takes parsed output and maps each element to your library's React components, rendering the UI progressively as the stream arrives.
+## The core loop
-<OpenUICloudCallout description="Monitor model usage, latency, errors, and render success." />
+1. Define the components your application supports.
+2. Generate model instructions from those definitions.
+3. Send the instructions and conversation through the Gateway.
+4. Stream the resulting OpenUI Lang into the renderer.
+5. Handle component interactions with application state, tools, queries, and mutations.
-## Built-in Component Libraries
+The language and renderer do not depend on a model provider, chat library, or hosted service. The
+Gateway is the default in these docs because it adds streaming correction and provider fallbacks
+without changing the component contract in your application.
-OpenUI ships with two ready-to-use libraries via `@openuidev/react-ui`. Both include layouts, content blocks, charts, forms, tables, and more.
-
-### General-purpose library (`openuiLibrary`)
-
-Root component is `Stack`. Includes the full component suite with flexible layout primitives. Use this for standalone rendering, playgrounds, and non-chat interfaces.
-
-```ts
-import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui/genui-lib";
-import { Renderer } from "@openuidev/react-lang";
-
-// Generate system prompt
-const systemPrompt = openuiLibrary.prompt(openuiPromptOptions);
-
-// Render streamed output
-<Renderer library={openuiLibrary} response={streamedText} isStreaming={isStreaming} />
-```
-
-### Chat-optimized library (`openuiChatLibrary`)
-
-Root component is `Card` (vertical container, no layout params). Adds chat-specific components like `FollowUpBlock`, `ListBlock`, and `SectionBlock`. Does not include `Stack`; responses are always single-card, vertically stacked.
-
-```tsx
-import { AgentInterface, openAIAdapter } from "@openuidev/react-ui";
-import { openuiChatLibrary } from "@openuidev/react-ui/genui-lib";
-
-// Use with AgentInterface, the artifact chat interface with thread history
-<AgentInterface
- llm={{ send, streamProtocol: openAIAdapter() }}
- componentLibrary={openuiChatLibrary}
-/>
-```
-
-Both libraries expose a `.prompt()` method to generate the system prompt your LLM needs. See [System Prompts](/docs/openui-lang/system-prompts) for CLI and programmatic generation options.
-
-### Extend a built-in library
-
-```ts
-import { createLibrary, defineComponent } from "@openuidev/react-lang";
-import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
-import { z } from "zod";
-
-const ProductCard = defineComponent({
- name: "ProductCard",
- description: "Product tile",
- props: z.object({
- name: z.string(),
- price: z.number(),
- }),
- component: ({ props }) => <div>{props.name}: ${props.price}</div>,
-});
-
-const myLibrary = createLibrary({
- root: openuiLibrary.root ?? "Stack",
- componentGroups: openuiLibrary.componentGroups,
- components: [...Object.values(openuiLibrary.components), ProductCard],
-});
-```
-
-## Usage Example
+## Example
<LangExample />
+
+Continue with [Defining Components](/docs/openui-lang/defining-components), then read
+[System Prompts](/docs/openui-lang/system-prompts) and [The Renderer](/docs/openui-lang/renderer).
diff --git a/docs/content/docs/openui-lang/quickstart.mdx b/docs/content/docs/openui-lang/quickstart.mdx
index f3332ec0f..11cf0031b 100644
--- a/docs/content/docs/openui-lang/quickstart.mdx
+++ b/docs/content/docs/openui-lang/quickstart.mdx
@@ -1,6 +1,6 @@
---
title: Quick Start
-description: Build a Recipe Remix agent with OpenUI Cloud in about 10 minutes.
+description: Build a Recipe Remix agent with OpenUI Gateway in about 10 minutes.
---
import { CopyableDiff } from "@/components/copyable-diff";
@@ -10,7 +10,7 @@ finds an image, and renders the results as interactive Generative UI.
![Recipe Remix calling the pantry tool and rendering three interactive recipe cards](/images/openui-lang/recipe-remix-quickstart.gif)
-The Cloud starter already includes streaming chat, conversation history, web
+The Gateway-backed starter already includes streaming chat, conversation history, web
search, image search, reports, presentations, and an example function tool.
You will keep those features and add one tool and one component.
@@ -318,8 +318,8 @@ Then update the `componentLibrary` prop:
<Callout type="info">
`recipeLibrary` extends the built-in `chatLibrary`, so the existing inline components remain
- available alongside `RecipeRemix`. Cloud's search tools and artifact renderers also remain
- available. See [Extend a built-in library](/docs/openui-lang/overview#extend-a-built-in-library).
+ available alongside `RecipeRemix`. Gateway's search tools and artifact renderers also remain
+ available. See [Built-in component libraries](/docs/api-reference/react-ui#component-library-exports).
</Callout>
## 5. Try it
diff --git a/docs/content/docs/openui-lang/reliability.mdx b/docs/content/docs/openui-lang/reliability.mdx
index 4baee490f..7a265ea22 100644
--- a/docs/content/docs/openui-lang/reliability.mdx
+++ b/docs/content/docs/openui-lang/reliability.mdx
@@ -26,7 +26,7 @@ There are four main ways to improve the reliability of LLM-generated interfaces:
- **Simplify the component schema.** Use distinct component names, clear descriptions, focused properties, and unambiguous enum values. Remove overlapping components and group related ones with `componentGroups`. See [Defining Components](/docs/openui-lang/defining-components).
- **Refine the system prompt.** Add targeted rules for recurring errors and provide valid examples for combinations the model finds difficult. In our benchmark, a single rule improved one model's completion rate by 13 percentage points, while an incorrect example caused double-digit regressions. See [System Prompts](/docs/openui-lang/system-prompts).
- **Evaluate model selection.** Test models using your own component library and representative prompts. Run each prompt multiple times and compare reliability alongside latency and cost.
-- **Validate and correct generated output.** Detect invalid output at runtime and fix it before it reaches users. OpenUI Cloud provides this reliability layer for production applications.
+- **Validate and correct generated output.** Detect invalid output at runtime and fix it before it reaches users. OpenUI Gateway provides this reliability layer for production applications.
Measure reliability before and after making these changes so you can identify the right intervention and verify that it worked.
@@ -99,14 +99,14 @@ After deploying, open the [Reliability dashboard](https://console.thesys.dev/rel
skill](/docs/mcp#install-via-the-skills-cli-recommended).
</Callout>
-## Production reliability with OpenUI Cloud
+## Production reliability with OpenUI Gateway
-OpenUI Cloud sits between your application and the LLM. It validates generated UI and fixes errors as it streams to your application.
+OpenUI Gateway sits between your application and the LLM. It validates generated UI and fixes errors as it streams to your application.
<div
className="not-prose my-6 rounded-2xl border border-fd-border bg-fd-muted/20 p-4 sm:p-6"
role="img"
- aria-label="A request travels from an application through OpenUI Cloud to an LLM. The LLM streams generated UI through OpenUI Cloud, which validates the stream continuously, fixes errors as they are detected, and forwards the validated stream to the application."
+ aria-label="A request travels from an application through OpenUI Gateway to an LLM. The LLM streams generated UI through OpenUI Gateway, which validates the stream continuously, fixes errors as they are detected, and forwards the validated stream to the application."
>
<div className="grid items-stretch gap-3 md:grid-cols-[minmax(0,1fr)_7rem_minmax(0,1.15fr)_7rem_minmax(0,1fr)]">
<div className="flex min-h-40 flex-col rounded-xl border border-fd-border bg-fd-background p-4">
@@ -142,7 +142,7 @@ OpenUI Cloud sits between your application and the LLM. It validates generated U
</div>
<div className="flex min-h-40 flex-col rounded-xl border border-[var(--openui-text-purple-primary)] bg-[var(--openui-purple-background)] p-4 shadow-sm">
- <div className="text-sm font-semibold text-fd-foreground">OpenUI Cloud</div>
+ <div className="text-sm font-semibold text-fd-foreground">OpenUI Gateway</div>
<div className="text-xs font-medium text-[var(--openui-text-purple-primary)]">
Reliability middleware
</div>
@@ -184,24 +184,24 @@ OpenUI Cloud sits between your application and the LLM. It validates generated U
</div>
</div>
-For every generation, OpenUI Cloud:
+For every generation, OpenUI Gateway:
- **Validates** generated UI as it streams.
- **Fixes** malformed output and schema violations on the fly.
- **Recovers** from model or provider failures using fallbacks.
-In production data from our [Reliability benchmark](/blog/generative-ui-benchmark), OpenUI Cloud fixed **96% of generations** that initially failed validation.
+In production data from our [Reliability benchmark](/blog/generative-ui-benchmark), OpenUI Gateway fixed **96% of generations** that initially failed validation.
<Callout type="tip">
- **Using a coding agent?** The OpenUI skill can help your agent integrate OpenUI Cloud into your
+ **Using a coding agent?** The OpenUI skill can help your agent integrate OpenUI Gateway into your
application. [Install the OpenUI skill](/docs/mcp#install-via-the-skills-cli-recommended).
</Callout>
### Integrations options
-OpenUI Cloud provides two OpenAI-compatible APIs for this generation flow:
+OpenUI Gateway provides two OpenAI-compatible APIs for this generation flow:
-- **[Chat Completions](/docs/openui-cloud/api/chat-completions):** A drop-in endpoint for applications that already use the OpenAI Chat Completions API for generative UI.
-- **[Responses API](/docs/openui-cloud/api/responses):** Build stateful model interactions that continue from previous responses, with built-in persistence and hosted tools such as web search, image search, presentation generation, and more.
+- **[Chat Completions](/docs/gateway/api/chat-completions):** A drop-in endpoint for applications that already use the OpenAI Chat Completions API for generative UI.
+- **[Responses API](/docs/gateway/api/responses):** Build stateful model interactions that continue from previous responses, with built-in persistence and hosted tools such as web search, image search, presentation generation, and more.
-Learn more in the [OpenUI Cloud documentation](/docs/openui-cloud/how-it-works).
+Learn more in the [OpenUI Gateway documentation](/docs/gateway).
diff --git a/docs/content/docs/openui-lang/system-prompts.mdx b/docs/content/docs/openui-lang/system-prompts.mdx
index d2dbae0e7..ac4a5e449 100644
--- a/docs/content/docs/openui-lang/system-prompts.mdx
+++ b/docs/content/docs/openui-lang/system-prompts.mdx
@@ -7,7 +7,7 @@ The system prompt tells the LLM how to output valid OpenUI Lang. Generate a seri
## 1. CLI (recommended for most setups)
-`openui generate` emits two artifacts from the same library: a prebuilt prompt and a serialized library spec. Use the **spec** with `generateSystemPrompt`; retain the prompt only for static or legacy integrations.
+`openui generate` emits two outputs from the same library: a prebuilt prompt and a serialized library spec. Use the **spec** with `generateSystemPrompt`; retain the prompt only for static or legacy integrations.
```bash tab="pnpm" tab-group="pkg"
pnpx @openuidev/cli@latest generate ./src/library.ts
@@ -85,17 +85,21 @@ const systemPrompt = generateSystemPrompt({
| `editMode` | Incremental editing - LLM outputs only changed statements | `false` |
| `inlineMode` | Text + fenced code responses - LLM can answer questions without generating UI | `false` |
-### OpenUI Cloud
+### OpenUI Gateway
-Pass `cloud: true` to emit Cloud's managed config block instead of a local prompt. OpenUI Cloud assembles the real system prompt on the server. `instructions` is Cloud-only extra prose appended after the config block.
+Pass `cloud: true` with the generated library specification to emit Gateway's managed config block instead of a local prompt. The option name is retained for compatibility. OpenUI Gateway assembles the full system prompt on the server, and `instructions` adds extra prose after the config block.
```ts
import { generateSystemPrompt } from "@openuidev/lang-core";
+import librarySpec from "./generated/system-prompt.spec.json";
-const instructions = generateSystemPrompt({ cloud: true });
+const instructions = generateSystemPrompt({
+ cloud: true,
+ library: librarySpec,
+});
```
-With your own library, pass the generated spec:
+Add Gateway-compatible prompt options when needed:
```ts
const instructions = generateSystemPrompt({
@@ -105,7 +109,7 @@ const instructions = generateSystemPrompt({
});
```
-See [Component Library](/docs/openui-cloud/build/component-library) for the Cloud workflow.
+See the [Generative UI Quickstart](/docs/gateway/generate-openui-lang) for the Gateway workflow.
Built-in functions (`@Count`, `@Filter`, `@Sort`, `@Each`, etc.) are automatically included when either `toolCalls` or `bindings` is enabled. For static UI libraries without data fetching, they are omitted to keep the prompt concise.
diff --git a/docs/content/docs/overview/index.mdx b/docs/content/docs/overview/index.mdx
deleted file mode 100644
index 93a88b5ec..000000000
--- a/docs/content/docs/overview/index.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
----
-title: Overview
-description: "OpenUI is a generative UI toolkit for building agents that respond with interactive interfaces, not just text. Agents compose the interface best suited to each request, from inline forms and data visualizations to dashboards, reports, and presentations."
-full: true
----
-
-import { OpenUIArchitectureOverview } from "@/components/openui-architecture-overview";
-
-<OpenUIArchitectureOverview />
diff --git a/docs/content/docs/overview/meta.json b/docs/content/docs/overview/meta.json
deleted file mode 100644
index 5d12ffcb6..000000000
--- a/docs/content/docs/overview/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "title": "Overview",
- "root": true,
- "pages": ["index"]
-}
diff --git a/docs/lib/docs-navigation.test.ts b/docs/lib/docs-navigation.test.ts
new file mode 100644
index 000000000..544fc5b5b
--- /dev/null
+++ b/docs/lib/docs-navigation.test.ts
@@ -0,0 +1,311 @@
+import type * as PageTree from "fumadocs-core/page-tree";
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+ GLOBAL_DOCS_TREE,
+ getDefaultSidebarMode,
+ getGlobalActiveItemUrl,
+ getNestedDocsTree,
+ getNestedRootForEntryUrl,
+ getNestedRootForPathname,
+ getSidebarModeForPathname,
+} from "./docs-navigation";
+
+describe("global docs navigation", () => {
+ it("exposes the agreed information architecture", () => {
+ const entries = GLOBAL_DOCS_TREE.children.map((node) => ({
+ type: node.type,
+ name: node.name,
+ url: node.type === "page" ? node.url : undefined,
+ children: undefined,
+ }));
+
+ assert.deepEqual(entries, [
+ { type: "separator", name: "Overview", url: undefined, children: undefined },
+ { type: "page", name: "Introduction", url: "/docs", children: undefined },
+ {
+ type: "page",
+ name: "Getting Started",
+ url: "/docs/getting-started",
+ children: undefined,
+ },
+ {
+ type: "page",
+ name: "How OpenUI works",
+ url: "/docs/architecture",
+ children: undefined,
+ },
+ {
+ type: "page",
+ name: "OpenUI vs others",
+ url: "/docs/openui-lang/comparison",
+ children: undefined,
+ },
+ { type: "page", name: "Coding Agent Setup", url: "/docs/mcp", children: undefined },
+ { type: "separator", name: "Build", url: undefined, children: undefined },
+ {
+ type: "page",
+ name: "OpenUI Lang",
+ url: "/docs/openui-lang",
+ children: undefined,
+ },
+ {
+ type: "page",
+ name: "Build Agents",
+ url: "/docs/build-agents",
+ children: undefined,
+ },
+ { type: "separator", name: "Production", url: undefined, children: undefined },
+ { type: "page", name: "Gateway", url: "/docs/gateway", children: undefined },
+ {
+ type: "page",
+ name: "Observability",
+ url: "/docs/observability",
+ children: undefined,
+ },
+ { type: "separator", name: "Reference", url: undefined, children: undefined },
+ {
+ type: "page",
+ name: "API Reference",
+ url: "/docs/api-reference",
+ children: undefined,
+ },
+ ]);
+ });
+
+ 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/gateway"), "gateway");
+ assert.equal(getNestedRootForEntryUrl("/docs/observability"), "observability");
+ assert.equal(getNestedRootForEntryUrl("/docs/api-reference"), "api-reference");
+ assert.equal(getNestedRootForEntryUrl("/docs/openui-lang/quickstart"), undefined);
+ });
+
+ it("uses a nested sidebar for direct links into a nested section", () => {
+ assert.deepEqual(getDefaultSidebarMode("/docs"), { kind: "global" });
+ assert.deepEqual(getDefaultSidebarMode("/docs/overview"), { kind: "global" });
+ assert.deepEqual(getDefaultSidebarMode("/docs/getting-started"), { kind: "global" });
+ assert.deepEqual(getDefaultSidebarMode("/docs/openui-lang/comparison"), { kind: "global" });
+ assert.deepEqual(getDefaultSidebarMode("/docs/openui-lang/quickstart"), {
+ kind: "nested",
+ root: "openui-lang",
+ });
+ assert.deepEqual(getDefaultSidebarMode("/docs/agent/core-concepts/tools"), {
+ kind: "nested",
+ root: "build-agents",
+ });
+ assert.deepEqual(getDefaultSidebarMode("/docs/build-agents/assistant-ui"), {
+ kind: "nested",
+ root: "build-agents",
+ });
+ assert.deepEqual(
+ getDefaultSidebarMode("/docs/agent/agent-runtimes/vercel-ai-sdk"),
+ { kind: "nested", root: "build-agents" },
+ );
+ assert.deepEqual(getDefaultSidebarMode("/docs/api-reference/cli"), {
+ kind: "nested",
+ root: "api-reference",
+ });
+ assert.deepEqual(getDefaultSidebarMode("/docs/gateway/reliability/error-correction"), {
+ kind: "nested",
+ root: "gateway",
+ });
+ assert.deepEqual(getDefaultSidebarMode("/docs/observability/installation"), {
+ kind: "nested",
+ root: "observability",
+ });
+ assert.deepEqual(getDefaultSidebarMode("/docs/mcp"), { kind: "global" });
+ });
+
+ it("shows the destination section after client-side navigation", () => {
+ const globalOverride = {
+ pathname: "/docs",
+ mode: { kind: "global" } as const,
+ };
+
+ assert.deepEqual(getSidebarModeForPathname("/docs/openui-lang/renderer", globalOverride), {
+ kind: "nested",
+ root: "openui-lang",
+ });
+ assert.deepEqual(getSidebarModeForPathname("/docs", globalOverride), { kind: "global" });
+
+ const nestedPathname = "/docs/openui-lang/renderer";
+ const showGlobalOverride = {
+ pathname: nestedPathname,
+ mode: { kind: "global" } as const,
+ };
+
+ assert.deepEqual(getSidebarModeForPathname(nestedPathname, showGlobalOverride), {
+ kind: "global",
+ });
+ assert.deepEqual(getSidebarModeForPathname("/docs/gateway", showGlobalOverride), {
+ kind: "nested",
+ root: "gateway",
+ });
+ });
+
+ it("promotes overview pages while grouping product pages under their roots", () => {
+ assert.equal(getGlobalActiveItemUrl("/docs/getting-started"), "/docs/getting-started");
+ assert.equal(
+ getGlobalActiveItemUrl("/docs/openui-lang/comparison"),
+ "/docs/openui-lang/comparison",
+ );
+ 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/build-agents/copilotkit"), "/docs/build-agents");
+ assert.equal(getGlobalActiveItemUrl("/docs/gateway/api/responses"), "/docs/gateway");
+ assert.equal(getGlobalActiveItemUrl("/docs/observability/dashboard"), "/docs/observability");
+ });
+});
+
+describe("nested docs navigation", () => {
+ const fullTree: PageTree.Root = {
+ name: "OpenUI",
+ children: [
+ {
+ type: "folder",
+ name: "OpenUI Lang",
+ root: true,
+ $ref: { folder: "openui-lang" },
+ children: [
+ { type: "page", name: "Introduction", url: "/docs/openui-lang" },
+ { type: "page", name: "Quick Start", url: "/docs/openui-lang/quickstart" },
+ ],
+ },
+ {
+ type: "folder",
+ name: "API Reference",
+ root: true,
+ $ref: { folder: "api-reference" },
+ children: [{ type: "page", name: "Overview", url: "/docs/api-reference" }],
+ },
+ {
+ type: "folder",
+ name: "Build Agents",
+ root: true,
+ $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: "page", name: "assistant-ui", url: "/docs/build-agents/assistant-ui" },
+ ],
+ },
+ {
+ type: "folder",
+ name: "Agent Interface",
+ $ref: { folder: "agent" },
+ children: [
+ { type: "separator", name: "Getting Started" },
+ {
+ 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" },
+ { type: "separator", name: "Examples" },
+ { type: "page", name: "Vercel AI SDK", url: "/docs/agent/agent-runtimes/vercel-ai-sdk" },
+ ],
+ },
+ ],
+ };
+
+ it("extracts a maintained nested tree from the Fumadocs tree", () => {
+ assert.deepEqual(getNestedDocsTree(fullTree, "openui-lang"), {
+ type: "root",
+ $id: "docs:nested:openui-lang",
+ name: "OpenUI Lang",
+ children: [
+ { type: "page", name: "Introduction", url: "/docs/openui-lang" },
+ { type: "page", name: "Quick Start", url: "/docs/openui-lang/quickstart" },
+ ],
+ });
+ });
+
+ it("combines Agent Interface and existing chat integrations under Build Agents", () => {
+ 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: "folder",
+ name: "Agent Interface",
+ defaultOpen: true,
+ 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",
+ },
+ ],
+ },
+ {
+ type: "folder",
+ name: "Existing Chat UIs",
+ defaultOpen: true,
+ children: [
+ { type: "page", name: "assistant-ui", url: "/docs/build-agents/assistant-ui" },
+ ],
+ },
+ {
+ type: "folder",
+ name: "Agent Runtime Examples",
+ defaultOpen: true,
+ children: [
+ {
+ type: "page",
+ name: "Vercel AI SDK",
+ url: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ },
+ ],
+ },
+ ],
+ });
+ });
+
+ 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"), "api-reference");
+ assert.equal(
+ getNestedRootForPathname("/docs/agent/customize/sidebar"),
+ "build-agents",
+ );
+ assert.equal(getNestedRootForPathname("/docs/build-agents/custom-chat-ui"), "build-agents");
+ assert.equal(getNestedRootForPathname("/docs"), undefined);
+ });
+
+ it("fails clearly when the requested nested root is absent", () => {
+ assert.throws(
+ () => getNestedDocsTree(fullTree, "gateway"),
+ /Nested docs root "gateway" was not found/,
+ );
+ });
+});
diff --git a/docs/lib/docs-navigation.ts b/docs/lib/docs-navigation.ts
new file mode 100644
index 000000000..5cfd9e3a1
--- /dev/null
+++ b/docs/lib/docs-navigation.ts
@@ -0,0 +1,220 @@
+import type * as PageTree from "fumadocs-core/page-tree";
+
+export type NestedDocsRoot = "openui-lang" | "build-agents" | "gateway" | "observability" | "api-reference";
+
+export type SidebarMode =
+ | { kind: "global" }
+ | {
+ kind: "nested";
+ root: NestedDocsRoot;
+ };
+
+export type SidebarModeOverride = {
+ pathname: string;
+ mode: SidebarMode;
+};
+
+type NestedSection = {
+ title: string;
+ entryUrl: string;
+ pathPrefix: string;
+ treeFolder: string;
+};
+
+export const NESTED_DOCS_SECTIONS: Record<NestedDocsRoot, NestedSection> = {
+ "openui-lang": {
+ title: "OpenUI Lang",
+ entryUrl: "/docs/openui-lang",
+ pathPrefix: "/docs/openui-lang",
+ treeFolder: "openui-lang",
+ },
+ "build-agents": {
+ title: "Build Agents",
+ entryUrl: "/docs/build-agents",
+ pathPrefix: "/docs/build-agents",
+ treeFolder: "build-agents",
+ },
+ gateway: {
+ title: "Gateway",
+ entryUrl: "/docs/gateway",
+ pathPrefix: "/docs/gateway",
+ treeFolder: "gateway",
+ },
+ observability: {
+ title: "Observability",
+ entryUrl: "/docs/observability",
+ pathPrefix: "/docs/observability",
+ treeFolder: "observability",
+ },
+ "api-reference": {
+ title: "API Reference",
+ entryUrl: "/docs/api-reference",
+ pathPrefix: "/docs/api-reference",
+ treeFolder: "api-reference",
+ },
+};
+
+const promotedGlobalUrls = new Set([
+ "/docs",
+ "/docs/getting-started",
+ "/docs/architecture",
+ "/docs/openui-lang/comparison",
+ "/docs/mcp",
+]);
+
+export const GLOBAL_DOCS_TREE: PageTree.Root = {
+ type: "root",
+ $id: "docs:global",
+ name: "OpenUI",
+ children: [
+ { type: "separator", name: "Overview" },
+ { type: "page", name: "Introduction", url: "/docs" },
+ { type: "page", name: "Getting Started", url: "/docs/getting-started" },
+ {
+ type: "page",
+ name: "How OpenUI works",
+ url: "/docs/architecture",
+ },
+ {
+ type: "page",
+ name: "OpenUI vs others",
+ url: "/docs/openui-lang/comparison",
+ },
+ { type: "page", name: "Coding Agent Setup", url: "/docs/mcp" },
+ { type: "separator", name: "Build" },
+ {
+ type: "page",
+ name: NESTED_DOCS_SECTIONS["openui-lang"].title,
+ url: NESTED_DOCS_SECTIONS["openui-lang"].entryUrl,
+ },
+ {
+ type: "page",
+ name: NESTED_DOCS_SECTIONS["build-agents"].title,
+ url: NESTED_DOCS_SECTIONS["build-agents"].entryUrl,
+ },
+ { type: "separator", name: "Production" },
+ {
+ type: "page",
+ name: NESTED_DOCS_SECTIONS.gateway.title,
+ url: NESTED_DOCS_SECTIONS.gateway.entryUrl,
+ },
+ {
+ type: "page",
+ name: NESTED_DOCS_SECTIONS.observability.title,
+ url: NESTED_DOCS_SECTIONS.observability.entryUrl,
+ },
+ { type: "separator", name: "Reference" },
+ {
+ type: "page",
+ name: NESTED_DOCS_SECTIONS["api-reference"].title,
+ url: NESTED_DOCS_SECTIONS["api-reference"].entryUrl,
+ },
+ ],
+};
+
+function isPathWithin(pathname: string, prefix: string): boolean {
+ return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+
+export function getNestedRootForEntryUrl(url: string): NestedDocsRoot | undefined {
+ return (Object.entries(NESTED_DOCS_SECTIONS) as [NestedDocsRoot, NestedSection][]).find(
+ ([, section]) => section.entryUrl === url,
+ )?.[0];
+}
+
+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];
+}
+
+export function getDefaultSidebarMode(pathname: string): SidebarMode {
+ if (pathname === "/docs/overview" || promotedGlobalUrls.has(pathname)) {
+ return { kind: "global" };
+ }
+
+ const root = getNestedRootForPathname(pathname);
+ return root ? { kind: "nested", root } : { kind: "global" };
+}
+
+export function getSidebarModeForPathname(
+ pathname: string,
+ override?: SidebarModeOverride,
+): SidebarMode {
+ return override?.pathname === pathname ? override.mode : getDefaultSidebarMode(pathname);
+}
+
+export function getGlobalActiveItemUrl(pathname: string): string | undefined {
+ if (promotedGlobalUrls.has(pathname)) return pathname;
+
+ const root = getNestedRootForPathname(pathname);
+ return root ? NESTED_DOCS_SECTIONS[root].entryUrl : undefined;
+}
+
+function findNestedFolder(nodes: PageTree.Node[], treeFolder: string): PageTree.Folder | undefined {
+ for (const node of nodes) {
+ if (node.type !== "folder") continue;
+ if (node.$ref?.folder === treeFolder) return node;
+
+ const nested = findNestedFolder(node.children, treeFolder);
+ if (nested) return nested;
+ }
+
+ return undefined;
+}
+
+export function getNestedDocsTree(tree: PageTree.Root, root: NestedDocsRoot): PageTree.Root {
+ const folder = findNestedFolder(tree.children, NESTED_DOCS_SECTIONS[root].treeFolder);
+ 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",
+ );
+ if (chatUIsIndex < 0 || examplesIndex < 0) {
+ throw new Error("Build Agents navigation groups were not found in the page tree.");
+ }
+
+ 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),
+ },
+ ],
+ };
+ }
+
+ return {
+ type: "root",
+ $id: `docs:nested:${root}`,
+ name: folder.name,
+ children: folder.children,
+ };
+}
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index 97f8d0dbd..f901ef2dd 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -65,9 +65,179 @@ const config = {
permanent: true,
},
{
- source: "/docs",
- destination: "/docs/overview",
- permanent: false,
+ source: "/docs/overview",
+ destination: "/docs",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-lang/how-it-works",
+ destination: "/docs/openui-lang/architecture",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent",
+ destination: "/docs/agent/getting-started/introduction",
+ permanent: true,
+ },
+ ...["assistant-ui", "copilotkit"].map((integration) => ({
+ source: `/docs/agent/${integration}`,
+ destination: `/docs/build-agents/${integration}`,
+ permanent: true,
+ })),
+ {
+ source: "/docs/agent/build-your-own-ui",
+ destination: "/docs/build-agents/custom-chat-ui",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent/vercel-ai-sdk",
+ destination: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent/langchain",
+ destination: "/docs/agent/agent-runtimes/langgraph-platform",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent/harnesses/:path*",
+ destination: "/docs/agent/agent-runtimes/:path*",
+ permanent: true,
+ },
+ {
+ source: "/docs/integrations",
+ destination: "/docs/build-agents",
+ permanent: true,
+ },
+ ...["assistant-ui", "copilotkit"].map((integration) => ({
+ source: `/docs/integrations/${integration}`,
+ destination: `/docs/build-agents/${integration}`,
+ permanent: true,
+ })),
+ {
+ source: "/docs/integrations/build-your-own-ui",
+ destination: "/docs/build-agents/custom-chat-ui",
+ permanent: true,
+ },
+ {
+ source: "/docs/integrations/vercel-ai-sdk",
+ destination: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ permanent: true,
+ },
+ {
+ source: "/docs/integrations/langchain",
+ destination: "/docs/agent/agent-runtimes/langgraph-platform",
+ permanent: true,
+ },
+ {
+ source: "/docs/integrations/harnesses/:path*",
+ destination: "/docs/agent/agent-runtimes/:path*",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-lang/examples/agent-frameworks/vercel-ai-sdk",
+ destination: "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-lang/examples/agent-frameworks/langchain",
+ destination: "/docs/agent/agent-runtimes/langgraph-platform",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-lang/examples/agent-frameworks/langgraph-platform",
+ destination: "/docs/agent/agent-runtimes/langgraph-platform",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-lang/examples/agent-frameworks/vercel-eve",
+ destination: "/docs/agent/agent-runtimes/vercel-eve",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-lang/examples/harnesses/pi",
+ destination: "/docs/agent/agent-runtimes/pi",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-lang/examples/app-frameworks/react-native",
+ destination: "/docs/openui-lang",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent/getting-started/openui-cloud",
+ destination: "/docs/agent/getting-started/quickstart",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent/agent-interface",
+ destination: "/docs/agent/getting-started/introduction",
+ permanent: true,
+ },
+ {
+ source: "/docs/agent/agent-interface/:path*",
+ destination: "/docs/agent/:path*",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud/get-started",
+ destination: "/docs/gateway/generate-openui-lang",
+ permanent: true,
+ },
+ {
+ source: "/docs/gateway/quickstart",
+ destination: "/docs/gateway/generate-openui-lang",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud/how-it-works",
+ destination: "/docs/gateway",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud/production-readiness",
+ destination: "/docs/gateway/reliability",
+ permanent: true,
+ },
+ {
+ source: "/docs/gateway/reliability/error-correction",
+ destination: "/docs/gateway/reliability",
+ permanent: true,
+ },
+ {
+ source: "/docs/gateway/reliability/provider-fallbacks",
+ destination: "/docs/gateway/reliability",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud/models-and-byok",
+ destination: "/docs/gateway/models",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud/api/chat-completions",
+ destination: "/docs/gateway/api/chat-completions",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud/api/responses",
+ destination: "/docs/gateway/api/responses",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud/api/conversations",
+ destination: "/docs/gateway/api/conversations",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud",
+ destination: "/docs/gateway",
+ permanent: true,
+ },
+ {
+ source: "/docs/openui-cloud/:path*",
+ destination: "/docs/gateway",
+ permanent: true,
},
{
source: "/docs/add-ons",
diff --git a/docs/public/images/build-agents-architecture.svg b/docs/public/images/build-agents-architecture.svg
new file mode 100644
index 000000000..fbe383e09
--- /dev/null
+++ b/docs/public/images/build-agents-architecture.svg
@@ -0,0 +1,133 @@
+<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/docs/public/images/observability/error-category-list.png b/docs/public/images/observability/error-category-list.png
new file mode 100644
index 000000000..92b71a2e2
Binary files /dev/null and b/docs/public/images/observability/error-category-list.png differ
diff --git a/docs/public/images/observability/reliability-dashboard.png b/docs/public/images/observability/reliability-dashboard.png
new file mode 100644
index 000000000..f11712e29
Binary files /dev/null and b/docs/public/images/observability/reliability-dashboard.png differ
diff --git a/docs/public/images/observability/single-error.png b/docs/public/images/observability/single-error.png
new file mode 100644
index 000000000..250669934
Binary files /dev/null and b/docs/public/images/observability/single-error.png differ
diff --git a/docs/public/images/openui-architecture.svg b/docs/public/images/openui-architecture.svg
new file mode 100644
index 000000000..d7e6db2cd
--- /dev/null
+++ b/docs/public/images/openui-architecture.svg
@@ -0,0 +1,149 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 1600 650"
+ role="img"
+ aria-labelledby="openui-architecture-title openui-architecture-description"
+>
+ <title id="openui-architecture-title">How OpenUI turns a request into an interactive interface</title>
+ <desc id="openui-architecture-description">
+ A user request travels from an application to its backend, through OpenUI Gateway, and to a model provider. The corrected OpenUI Lang stream returns to a renderer, which displays the generated interface. Observability traces the flow.
+ </desc>
+
+ <defs>
+ <linearGradient id="openui-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="openui-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="openui-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="openui-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="openui-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="openui-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="openui-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="openui-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(#openui-architecture-bg)" />
+ <rect width="1600" height="650" rx="24" fill="url(#openui-architecture-glow)" />
+
+ <g font-family="ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif">
+ <g filter="url(#openui-architecture-shadow)">
+ <rect x="35" y="42" width="365" height="565" rx="58" fill="url(#openui-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(#openui-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(#openui-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(#openui-architecture-arrow)" />
+ <path d="M 770 175 H 900" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 1150 175 H 1260" markerStart="url(#openui-architecture-arrow)" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 1410 265 V 300" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 1200 420 H 770" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 685 460 V 540" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 540 575 H 400" markerEnd="url(#openui-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(#openui-architecture-shadow)">
+ <rect x="600" y="130" width="170" height="330" rx="22" fill="url(#openui-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(#openui-architecture-shadow)">
+ <rect x="900" y="125" width="250" height="145" rx="22" fill="url(#openui-architecture-card)" stroke="#54505f" stroke-width="1.5" vector-effect="non-scaling-stroke" />
+ <text x="925" y="170" fill="#d8d3ff" font-size="30" font-weight="600">Gateway</text>
+ <text x="925" y="207" fill="#9993ae" font-size="20">Route and failover</text>
+ <text x="925" y="239" fill="#9993ae" font-size="20">Correct model output</text>
+ </g>
+
+ <g filter="url(#openui-architecture-shadow)">
+ <rect x="1260" y="60" width="300" height="205" rx="26" fill="url(#openui-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(#openui-architecture-logo-light)" aria-label="OpenAI" />
+ <image href="/brand-icons/anthropic.svg" x="1350" y="188" width="36" height="36" filter="url(#openui-architecture-logo-light)" aria-label="Anthropic" />
+ <image href="/brand-icons/gemini.svg" x="1408" y="188" width="36" height="36" filter="url(#openui-architecture-logo-light)" aria-label="Google Gemini" />
+ <image href="/brand-icons/meta.svg" x="1466" y="188" width="36" height="36" filter="url(#openui-architecture-logo-light)" aria-label="Meta" />
+ </g>
+
+ <text x="835" y="130" text-anchor="middle" fill="#a7adad" font-size="20">Components</text>
+ <text x="835" y="156" text-anchor="middle" fill="#a7adad" font-size="20">and context</text>
+ <text x="1205" y="130" text-anchor="middle" fill="#a7adad" font-size="20">Route</text>
+ <text x="1205" y="156" text-anchor="middle" fill="#a7adad" font-size="20">and failover</text>
+
+ <g filter="url(#openui-architecture-shadow)">
+ <rect x="1200" y="300" width="360" height="250" rx="28" fill="url(#openui-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">Corrected 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(#openui-architecture-shadow)">
+ <rect x="540" y="540" width="300" height="70" rx="18" fill="url(#openui-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>
+ <path d="M 890 590 H 1570" stroke="#fb7185" stroke-opacity="0.38" stroke-width="1.5" stroke-dasharray="5 7" fill="none" vector-effect="non-scaling-stroke" />
+ <rect x="1010" y="555" width="220" height="70" rx="18" fill="#fb7185" fill-opacity="0.1" stroke="#fb7185" stroke-opacity="0.45" vector-effect="non-scaling-stroke" />
+ <text x="1120" y="599" text-anchor="middle" fill="#fda4af" font-size="24" font-weight="500">Observability</text>
+ </g>
+ </g>
+</svg>
diff --git a/docs/public/images/openui-gateway-architecture.svg b/docs/public/images/openui-gateway-architecture.svg
new file mode 100644
index 000000000..e74526488
--- /dev/null
+++ b/docs/public/images/openui-gateway-architecture.svg
@@ -0,0 +1,149 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 1600 650"
+ role="img"
+ aria-labelledby="openui-architecture-title openui-architecture-description"
+>
+ <title id="openui-architecture-title">How OpenUI turns a request into an interactive interface</title>
+ <desc id="openui-architecture-description">
+ A user request travels from an application to its backend, through OpenUI Gateway, and to a model provider. The corrected OpenUI Lang stream returns to a renderer, which displays the generated interface. Observability traces the flow.
+ </desc>
+
+ <defs>
+ <linearGradient id="openui-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="openui-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="openui-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="openui-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="openui-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="openui-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="openui-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="openui-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(#openui-architecture-bg)" />
+ <rect width="1600" height="650" rx="24" fill="url(#openui-architecture-glow)" />
+
+ <g font-family="ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif">
+ <g filter="url(#openui-architecture-shadow)">
+ <rect x="35" y="42" width="365" height="565" rx="58" fill="url(#openui-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(#openui-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(#openui-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(#openui-architecture-arrow)" />
+ <path d="M 770 175 H 900" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 1150 175 H 1260" markerStart="url(#openui-architecture-arrow)" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 1410 265 V 300" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 1200 420 H 770" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 685 460 V 540" markerEnd="url(#openui-architecture-arrow)" />
+ <path d="M 540 575 H 400" markerEnd="url(#openui-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(#openui-architecture-shadow)">
+ <rect x="600" y="130" width="170" height="330" rx="22" fill="url(#openui-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(#openui-architecture-shadow)">
+ <rect x="900" y="125" width="250" height="145" rx="22" fill="#4c1d95" fill-opacity="0.72" stroke="#c4b5fd" stroke-width="3" vector-effect="non-scaling-stroke" />
+ <text x="925" y="170" fill="#ffffff" font-size="30" font-weight="600">Gateway</text>
+ <text x="925" y="207" fill="#ddd6fe" font-size="20">Route and failover</text>
+ <text x="925" y="239" fill="#ddd6fe" font-size="20">Correct model output</text>
+ </g>
+
+ <g filter="url(#openui-architecture-shadow)">
+ <rect x="1260" y="60" width="300" height="205" rx="26" fill="url(#openui-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(#openui-architecture-logo-light)" aria-label="OpenAI" />
+ <image href="/brand-icons/anthropic.svg" x="1350" y="188" width="36" height="36" filter="url(#openui-architecture-logo-light)" aria-label="Anthropic" />
+ <image href="/brand-icons/gemini.svg" x="1408" y="188" width="36" height="36" filter="url(#openui-architecture-logo-light)" aria-label="Google Gemini" />
+ <image href="/brand-icons/meta.svg" x="1466" y="188" width="36" height="36" filter="url(#openui-architecture-logo-light)" aria-label="Meta" />
+ </g>
+
+ <text x="835" y="130" text-anchor="middle" fill="#a7adad" font-size="20">Components</text>
+ <text x="835" y="156" text-anchor="middle" fill="#a7adad" font-size="20">and context</text>
+ <text x="1205" y="130" text-anchor="middle" fill="#a7adad" font-size="20">Route</text>
+ <text x="1205" y="156" text-anchor="middle" fill="#a7adad" font-size="20">and failover</text>
+
+ <g filter="url(#openui-architecture-shadow)">
+ <rect x="1200" y="300" width="360" height="250" rx="28" fill="url(#openui-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">Corrected 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(#openui-architecture-shadow)">
+ <rect x="540" y="540" width="300" height="70" rx="18" fill="url(#openui-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>
+ <path d="M 890 590 H 1570" stroke="#fb7185" stroke-opacity="0.38" stroke-width="1.5" stroke-dasharray="5 7" fill="none" vector-effect="non-scaling-stroke" />
+ <rect x="1010" y="555" width="220" height="70" rx="18" fill="#fb7185" fill-opacity="0.1" stroke="#fb7185" stroke-opacity="0.45" vector-effect="non-scaling-stroke" />
+ <text x="1120" y="599" text-anchor="middle" fill="#fda4af" font-size="24" font-weight="500">Observability</text>
+ </g>
+ </g>
+</svg>
diff --git a/docs/research/vercel-documentation-patterns.md b/docs/research/vercel-documentation-patterns.md
new file mode 100644
index 000000000..ef0099fa0
--- /dev/null
+++ b/docs/research/vercel-documentation-patterns.md
@@ -0,0 +1,146 @@
+# Vercel documentation patterns relevant to OpenUI
+
+Research date: 2026-09-01
+
+## Scope
+
+This note examines first-party Vercel documentation patterns that are useful for
+an open-source project with paid hosted products, then maps them to the current
+OpenUI documentation and package structure.
+
+## Transferable patterns from Vercel
+
+### Organize first by product, then by user task
+
+Vercel's docs home routes readers by intent, while the full documentation tree
+is grouped into product domains. Product subtrees generally progress from a
+landing page to getting started, concepts, task guides, reference, limits, and
+pricing. Longer tutorials live in the Knowledge Base rather than in the core
+product reference.
+
+Sources: [Vercel docs](https://vercel.com/docs), [documentation
+sitemap](https://vercel.com/docs/sitemap.md), [Vercel Knowledge
+Base](https://vercel.com/kb).
+
+### Give each page one job
+
+Vercel's public writing guidance distinguishes landing pages, tutorials,
+how-to guides, conceptual explanations, reference pages, and troubleshooting.
+The tone changes with the page type: tutorials teach an end-to-end path,
+how-to pages optimize for task completion, and references optimize for exact
+lookup.
+
+Source: [Vercel writing
+guidelines](https://github.com/vercel-labs/writing-guidelines/blob/main/README.md).
+
+### Use concise, operational language
+
+The writing guidelines favor active voice, present tense, direct `you`,
+imperative steps, sentence-case headings, and a summary at the start of each
+page and major section. They discourage filler and subjective promises such as
+"easy" or "simple." Terms and acronyms are defined on first use.
+
+Source: [Vercel writing
+guidelines](https://github.com/vercel-labs/writing-guidelines/blob/main/README.md).
+
+### Make examples runnable and visually consistent
+
+Vercel examples consistently identify the language and filename, put the first
+runnable example before exhaustive detail, use package-manager or
+framework/language tabs when the variants are genuinely equivalent, and keep
+snippets short. Terminal commands are visually distinct from source files.
+
+Sources: [Vercel Functions
+quickstart](https://vercel.com/docs/functions/quickstart), [Vercel CLI deploy
+reference](https://vercel.com/docs/cli/deploy), [Vercel writing
+guidelines](https://github.com/vercel-labs/writing-guidelines/blob/main/README.md).
+
+### Generate exhaustive reference; hand-write the learning path
+
+Vercel combines an OpenAPI-generated endpoint reference with hand-written
+Overview, Getting Started, and Errors pages. Endpoint pages expose the method
+and path, authentication, typed parameters, request and response schemas,
+examples, status-specific errors, and related endpoints. REST and SDK
+references use parallel resource taxonomies instead of mixing every client
+surface into a single page.
+
+Sources: [REST API getting
+started](https://vercel.com/docs/rest-api/getting-started), [example endpoint
+reference](https://vercel.com/docs/rest-api/projects/create-a-new-project),
+[REST API errors](https://vercel.com/docs/rest-api/errors), [SDK
+reference](https://vercel.com/docs/rest-api/sdk), [OpenAPI documentation
+announcement](https://vercel.com/changelog/automatic-rest-api-documentation-with-openapi).
+
+### State open-source and paid boundaries directly
+
+Vercel's eve documentation identifies the framework as open source, states
+what the Vercel-hosted documentation covers, and links to the independent
+framework and self-hosting paths. Pricing documentation maps charges and limits
+to the hosted infrastructure involved.
+
+Sources: [eve on Vercel](https://vercel.com/docs/eve), [eve pricing and
+limits](https://vercel.com/docs/eve/pricing).
+
+### Publish documentation for people and agents
+
+Vercel exposes structured page metadata, Markdown versions, `llms.txt`, and a
+semantic sitemap. This makes product boundaries, prerequisites, related pages,
+and page types machine-readable as well as visible in the HTML experience.
+
+Source: [Markdown and agent
+discovery](https://vercel.com/docs/agent-resources/markdown-access).
+
+## Current OpenUI inventory
+
+The repository currently presents five top-level documentation areas:
+OpenUI Lang, Build Agents, Gateway, Observability, and API Reference. The global
+and nested navigation behavior is defined in
+[`docs/lib/docs-navigation.ts`](../lib/docs-navigation.ts), and authored page
+order lives in the section `meta.json` files under
+[`docs/content/docs`](../content/docs).
+
+The implementation has more distinct reader-facing roles than the current
+three-layer introduction makes explicit:
+
+- OpenUI Lang and its framework runtimes define, generate, parse, and render the
+ interface program.
+- Agent UI and integration packages connect that renderer to conversation and
+ agent runtimes.
+- Gateway owns the hosted model-generation and correction path.
+- Observability combines an open-source local event bus with a hosted telemetry
+ sink and product dashboards.
+
+The package descriptions in the workspace manifests support this split. In
+particular, the repository contains framework runtimes for React, Vue, and
+Svelte; headless and prebuilt React agent UI layers; assistant-ui and LangChain
+integrations; email and browser-bundle targets; CLI and developer tooling; and
+separate local and hosted observability packages.
+
+The current package API section has dedicated pages for eight of the fourteen
+public workspace packages. The missing package references are `lang-core`,
+`vue-lang`, `svelte-lang`, `browser-bundle`, `observability`, and
+`observability-cloud`.
+
+## Implications for the OpenUI information architecture
+
+1. Keep one documentation portal, but make the commercial boundary explicit by
+ grouping Gateway and hosted Observability under an **OpenUI Cloud** branch.
+2. Keep a complete, first-class **Open source** path. A reader must be able to
+ define components, generate a prompt, call a model directly, render the
+ response, and instrument a custom sink without entering the Cloud section.
+3. Replace the mixed **Build Agents** bucket with clearer **SDKs** and
+ **Integrations** groupings, or use those as two subgroups beneath one branch.
+4. Add a package chooser and dependency diagram before package-level pages.
+ Readers should understand `lang-core` versus a renderer, headless chat versus
+ `AgentInterface`, and local observability versus the hosted sink.
+5. Merge the overlapping OpenUI Lang introduction and overview. Move exhaustive
+ syntax, versioned specifications, exports, and endpoint schemas into
+ Reference, leaving the main product tree task-oriented.
+6. Maintain hand-written overview, quickstart, concept, guide, pricing, and
+ troubleshooting pages. Generate TypeScript reference from source/TSDoc and
+ Gateway HTTP reference from OpenAPI.
+7. Add explicit availability metadata to every page: **Open source**,
+ **OpenUI Cloud**, **Beta**, **Deprecated**, or a combination.
+8. Preserve the existing `llms.txt` support and extend page frontmatter with
+ page type, product, availability, prerequisites, last-updated date, and
+ related pages.
diff --git a/docs/source.config.ts b/docs/source.config.ts
index e7795bbf2..5c833e767 100644
--- a/docs/source.config.ts
+++ b/docs/source.config.ts
@@ -3,12 +3,16 @@ import { defineCollections, defineConfig, defineDocs } from "fumadocs-mdx/config
import lastModified from "fumadocs-mdx/plugins/last-modified";
import { z } from "zod";
+const docsPageSchema = pageSchema.extend({
+ customHeader: z.boolean().optional().default(false),
+});
+
// You can customise Zod schemas for frontmatter and `meta.json` here
// see https://fumadocs.dev/docs/mdx/collections
export const docs = defineDocs({
dir: "content/docs",
docs: {
- schema: pageSchema,
+ schema: docsPageSchema,
postprocess: {
includeProcessedMarkdown: true,
},