Agent Interface SDK

[ankit-thesys]

What & why

This PR lands the Agent Interface SDK — a ground-up redesign of OpenUI's chat surface. It replaces the legacy flat-prop chat shells (Shell, CopilotShell, BottomTray, OpenUIChat stories) with a single composable <AgentInterface> component built on an adapter-based headless core (storage: ChatStorage + llm: ChatLLM), reworks artifact/panel state into purpose-built stores, ships a real tool-call activity model with accessible rendering, renames the Artifact* panel API to DetailedView*, adds two reference example apps (OpenUI Cloud + OpenAI Responses), and replaces the old chat/* docs with a full Agent Interface documentation section.

It is a large, intentionally breaking change: +19,752 / −13,719 across 381 files. The deletions are almost entirely the retired shells and their stories/docs.

Heads-up for reviewers: this is a breaking release for @openuidev/react-headless and @openuidev/react-ui. The consolidated Breaking changes & migration section near the bottom is the contract consumers must act on; docs/agent/guides/migrating documents the same mapping for end users.

---

Highlights

• Adapter core. ChatProvider no longer takes apiUrl/threadApiUrl/streamProtocol/messageFormat + 6 callbacks. It now takes llm: ChatLLM (required) and storage?: ChatStorage (defaults to in-memory). Two batteries-included factories cover the common case: fetchLLM({ url, streamAdapter }) and restStorage({ baseUrl }).
• One component, composable slots. <AgentInterface> provides an opinionated two-panel desktop layout (collapsible sidebar + thread + resizable detailed-view panel) and a mobile slide-over, all overridable through a static slot namespace (AgentInterface.Sidebar, .Composer, .Workspace, .Route, .Welcome, …).
• Real tool-call status. A ToolActivity discriminated union (streaming → executing → complete | error) driven by genuine AG-UI stream events (TOOL_CALL_CHUNK/_END/_RESULT), replacing the old "guess from whether content arrived" heuristic. Backed by an accessible ToolCall primitive set and a staggered-reveal timeline.
• Artifact → DetailedView rename. The Artifact panel factory/hooks/components are replaced by identically-shaped DetailedView equivalents (config key panel → actual). Artifact registration (the browser rail) is now a separate concern via defineArtifactRenderer + defineArtifactCategories.
• Accurate artifact classification. ParsedArtifact.meta gains an optional type; the renderer registers each artifact under its real kind when the parser sets it, so a renderer that serves multiple kinds labels each correctly in the browser.
• Streaming correctness fixes. A shared SSE line iterator fixes cross-chunk line-splitting that silently dropped large payloads; the OpenAI-conversation format no longer duplicates "Behind the scenes" groups on reload.
• Two new example apps + every existing example migrated to AgentInterface.
• Docs: new agent/* section (18 pages) + navbar tab; the old chat/* section is removed.

---

1 · Headless core — adapter-based ChatProvider (@openuidev/react-headless)

The monolithic ChatProviderProps is replaced by a two-adapter API.

• ChatProviderProps is now { llm: ChatLLM; storage?: ChatStorage; artifactRenderers?; artifactCategories?; children }. Removed: apiUrl, threadApiUrl, streamProtocol, messageFormat, fetchThreadList, createThread, deleteThread, updateThread, loadThread, processMessage.
• createChatStore now takes { storage, llm }. All thread CRUD delegates to storage.thread.*; sending delegates to llm.send({ threadId, messages, signal }); the stream protocol is read from llm.streamProtocol. The old ephemeral-thread fallback is gone — a createThread always happens on first send (no-storage = in-memory threads with real UUIDs).
• New adapters/ layer:
  • fetchLLM({ url, streamAdapter, messageFormat?, headers?, fetch? }): ChatLLM — POSTs an AG-UI RunAgentInput-shaped body and streams the response through the chosen adapter.
  • restStorage({ baseUrl, messageFormat?, headers?, fetch? }): ChatStorage — implements the thread channel against the same REST conventions the old threadApiUrl used (/get, /create, /get/:id, /update/:id, /delete/:id). Artifact storage is supplied separately as storage.artifact.
  • createDefaultInMemoryStorage() — internal default (not exported).
• New exported types: ChatLLM, ChatStorage, ThreadStorage, ArtifactStorage, Artifact, ArtifactSummary, ArtifactCategory, ArtifactListParams, FetchLLMOptions, RestStorageOptions.
• @ag-ui/core bumped ^0.0.45 → ^0.0.53.

2 · State model — DetailedView, ThreadContext & renderer registries

The old single ArtifactContext/createArtifactStore (tracked only activeArtifactId) is deleted and split into focused stores + stateless registries, wired as nested contexts in ChatProvider (Chat → DetailedView → ThreadContext → ArtifactRenderers → ArtifactStorage → ArtifactCategories):

• DetailedView store — one active detailed-view id at a time, shared across apps/artifacts/custom consumers (useDetailedView(viewId), useActiveDetailedView(), useDetailedViewPortalTarget()).
• ThreadContext store — per-thread artifact registry keyed by (id, version); ArtifactEntry { id, version, heading, type, updatedAt? }, versions kept sorted ascending. Read via useArtifactList(filter?).
• ArtifactRenderersContext — a prebuilt { byToolName, byType } Map registry with first-wins dedup on duplicate toolName/type (dev-mode warning). lookupArtifactRenderer / lookupArtifactRendererByType. Captured once at mount — changing the artifactRenderers prop after mount is ignored with a dev warning, so consumers must memoize or use a module constant.
• defineArtifactRenderer<Props>(config) — { type, toolName: string | string[], parser({ args, response }, { isStreaming }) → ParsedArtifact<Props> | null, preview, actual, icon?, label? }. ParsedArtifact.meta is { id, version, heading, type? } | null — meta: null renders but skips registration (the common streaming case), and the optional type lets a parser stamp the artifact's real kind.
• defineArtifactCategories(groups) — accepts [{ name, renderers, icon? }] and returns { artifactRenderers, artifactCategories } ready to spread onto <AgentInterface>; each category's filter.type is derived from its renderers.

Removed (breaking): ArtifactContext, useArtifactStore, ArtifactState/Actions/Store, useActiveArtifact, useArtifact, useArtifactPortalTarget, openArtifact/closeArtifact/resetArtifacts.

3 · Streaming & message formats

• Shared sseLineIterator (stream/adapters/_shared/sseLines.ts) buffers the partial line straddling a network-chunk boundary and flushes the tail at end-of-stream — fixing a bug that silently dropped large SSE payloads. ag-ui, openai-completions, and openai-readable-stream adopt it; openai-responses and langgraph get the equivalent buffer/flush inline (and move if (done) break after block processing so the final block isn't dropped).
• processStreamedMessage gains first-class tool-call handling: TOOL_CALL_CHUNK (AG-UI combined form — lazily starts a call, fills a late-arriving name, accumulates args; previously dropped), TOOL_CALL_END (marks the call executing), TOOL_CALL_RESULT (creates/upserts a real ToolMessage, mapping isError/error). RUN_ERROR clears in-flight executing flags without synthesizing empty tool messages (no blank renderer flash). TEXT_MESSAGE_START no longer deletes+recreates the assistant message — avoiding ordering corruption when tool messages already landed. deleteMessage is removed; markToolExecuting/clearToolExecuting are added (optional).
• ThreadState.executingToolCallIds: Set<string> drives the "executing" status; cleared on run start, thread switch, cancel, and the run's finally (so adapters that emit TOOL_CALL_END with no TOOL_CALL_RESULT don't stick).
• OpenAI-conversation format fromItems now buffers all tool messages of a multi-call assistant turn and flushes them together — eliminating duplicate "Behind the scenes" groups on thread reload.
• openai-responses handles function_call_output items (response.output_item.added), emitting TOOL_CALL_RESULT with call_id/output.

4 · Tool-call activity & rendering (@openuidev/react-ui)

• ToolActivity<T> + pairToolActivity (react-headless/store/toolActivity.ts): a 4-state union pairing calls↔results by toolCallId (not positional), reading executingToolCallIds, attributing orphan tool messages, with partialJSONParse for tolerant mid-stream args. Exposed via useToolActivities(message, allMessages).
• ToolCall compound primitives (Root/Trigger/Content/StatusIcon/StatusText/ToolName/Parameters/Result): every part takes an optional render escape hatch. StatusText emits role="status" aria-live="polite"; Trigger emits aria-expanded/aria-controls; Content emits role="region". Plus DefaultToolCard (chevron collapsible, opens on error) and TimelineToolCard (dot+connector row).
• ToolCallTimeline replaces the legacy BehindTheScenes + ToolCallComponent + ToolResult composition: staggered reveal for live messages (historical start fully revealed), a settled toggle label showing failure count (Behind the scenes · 2 failed), and a visually-hidden live region. "Thinking" derives from useThread(s => s.isRunning) + last status — no magic _request/_response keys.
• Dispatchers (_shared/tool-renderer/): ToolCallEntry/TimelineEntry look up useArtifactRenderer(toolName) and render the matched renderer xor the default card — never both. ToolActivityRenderer runs renderer.parser and:
  • registers the artifact under meta.type ?? renderer.type so a shared renderer classifies each kind correctly in the browser rail;
  • renders ToolCallErrorFallback inline if the parser throws (one bad renderer can't blank the thread);
  • suppresses the preview when the tool call errored even if the parser produced props — matching reload behavior, since the persisted artifact was never created.
  • ToolMessageRenderer is kept as a @deprecated backward-compatible wrapper.
• Built-in webSearchRenderer (renderers/webSearchRenderer.tsx) for web_search/webSearch — reads { query, reasoning, sources } via partialJSONParse (meta: null, inline-only), with SourceIcon favicon + 16×16 fallback. Not auto-registered; consumers pass it in artifactRenderers.
• Accessibility: run-gated animations (shimmer/spin only while streaming|executing && isRunning && isLast), a comprehensive prefers-reduced-motion block, aria-expanded/aria-controls on toggles, role="region" panels, and focus-visible rings.

5 · <AgentInterface> component suite (@openuidev/react-ui)

A complete, opinionated layout wrapping ChatProvider + ThemeProvider + Nav/Starters/Labels/Store providers.

• Props (additive over ChatProviderProps): componentLibrary, components ({ AssistantMessage?, UserMessage? }), theme, disableThemeProvider, logoUrl, agentName, labels, starters, starterVariant, path/defaultPath/onNavigate (controlled/uncontrolled nav), scrollVariant ('always' | 'user-message-anchor'), scrollOnLoad (default true). Children are slot-extracted; duplicate slots warn and use the first.
• Static slot namespace: Sidebar, SidebarHeader/Content/Separator/Item, ArtifactNav, Workspace, Route, MobileHeader, ThreadHeader, Welcome, Composer, NewChatButton, ThreadList, Messages, MessageLoading, ScrollArea.
• Navigation & routing: useNav() controlled/uncontrolled split (onNavigate present → controlled). AgentInterface.Route declares exact-path custom pages that replace the thread region. The artifacts/ path prefix is reserved and matched before user Routes.
• Sidebar / ThreadList: animated collapse/expand (desktop) and slide-over (mobile, auto-detected via element width); ThreadList groups by Today/Yesterday/7d/30d/Year/Older with a per-thread Delete action.
• Workspace (right rail): lists the active thread's artifacts, one section per artifactCategories entry; tabs/filtering were dropped — all sections show, and artifacts matching no category land in a trailing fallback section (never dropped). Hidden when empty, when a DetailedView is active, or off the thread view.
• Artifact browser: ArtifactBrowserPage (debounced search + cursor pagination via ArtifactStorage.list, with an explicit not-found state for unknown categories) and ArtifactViewPage (renders renderer.actual from stored content with args: undefined, isStreaming: false). ArtifactNav renders one item per category (or a single "Artifacts" item), nothing when artifact storage is absent.
• Detailed-view subsystem (new src/detailed-view/ top-level export): DetailedView<P>(config) factory (title, preview, actual, panelProps), DetailedViewPanel (portals into the nearest target, error-boundary wrapped, configurable header), DetailedViewOverlay (mobile slide-in/out), DetailedViewPortalTarget. ResizableSeparator implements the WAI-ARIA window-splitter pattern (drag + ArrowKeys/Shift/Home/End); useDetailedViewResize clamps the chat panel to [420px, 80%] and auto-collapses the sidebar when a detailed view opens.

6 · Legacy shell retirement (BREAKING)

• Deleted packages/react-ui/src/components/Shell/, CopilotShell/, BottomTray/, and the OpenUIChat stories — including their .scss, stories, and orphaned assets (the bulk of the −13,719 lines). The Shell/CopilotShell namespace star-exports are removed from index.ts.
• Artifact* → DetailedView* rename in the public surface:
  • Artifact factory → DetailedView (config key panel → actual); ArtifactConfig/Controls → DetailedViewConfig/Controls.
  • ArtifactPanel/Overlay/PortalTarget (+ prop types) → DetailedView* equivalents.
  • useActiveArtifact/useArtifact → useActiveDetailedView/useDetailedView.
  • index.ts now does export * from '@openuidev/react-headless' and export * from './components/AgentInterface'. ⚠️ The re-exported headless Artifact domain-model type now shadows the old Artifact factory name — code doing Artifact({...}) gets a type error (caught at build), not a silent runtime bug.
• Wire format: utils/contentParser.ts (XML <content>/<context> envelope) replaced by utils/sentinelParser.ts (the ]]>openui: inline-sentinel format) with an internal parseLegacyXml fallback so previously persisted messages still render.
• useScrollToBottom gains scrollOnLoad (default true, surfaced on AgentInterfaceProps) to suppress initial-load auto-scroll without affecting mid-stream following. restore user-message styling fix included.

7 · Example apps & build config

• examples/openui-cloud (new) — OpenUI Cloud two-plane integration: generation plane (/api/chat llm proxy, THESYS_* key) + read/edit plane (useOpenuiCloudStorage over /v1 with fct_ frontend-token mint/refresh). Consumes the vendored @openuidev/thesys, wires defineArtifactCategories for slides/report. Excluded from the pnpm workspace (!examples/openui-cloud in pnpm-workspace.yaml) because it depends on a gitignored file: tarball and a cross-repo link: that don't exist in CI — keeping monorepo pnpm install --frozen-lockfile green.
• examples/openui-responses-chat (new) — OpenAI Conversations+Responses reference: restStorage + openAIResponsesAdapter, a MAX_TOOL_TURNS agentic loop with file-based thread persistence, and a create_code_artifact renderer.
• examples/openui-artifact-demo migrated from processMessage/openAIAdapter to fetchLLM; the ArtifactCodeBlock openui-lang component is dropped in favor of a create_code_block tool + codeBlockRenderer.
• All other examples (hands-on-table-chat, shadcn-chat, material-ui-chat, langgraph-chat, mastra-chat, openui-chat, harnesses, react-email) and the fastapi-backend frontend migrated off the legacy shells to AgentInterface. The openui-cli scaffold template is intentionally kept on FullScreen for now (reverted).
• lang-core stream parser fix: createStreamParser scans completed statements over the preprocessed (cleaned) buffer and recovers when a code fence/prose prefix shifts offsets — fixing statement-boundary corruption when markdown precedes the openui-lang program.

8 · Docs

• New docs/content/docs/agent/ section (18 MDX pages: Getting Started / Core Concepts / Customize / Reference / Guides) + a new "Agent Interface" navbar tab. Reference pages cover all AgentInterface props, adapters/formats, defineArtifactRenderer, the hook set, components/slots, and self-hosting; guides/migrating documents the full legacy→AgentInterface mapping.
• Removed the entire old docs/content/docs/chat/* section and retargeted READMEs/skill off the deleted shells.
• Added multimedia (videos/images) and a self-contained static build guide served from the docs site.

---

Breaking changes & migration

Legacy (removed)	New
ChatProvider/AgentInterface apiUrl, threadApiUrl, streamProtocol, messageFormat	llm={fetchLLM({ url, streamAdapter })}, storage={restStorage({ baseUrl })}
fetchThreadList/createThread/deleteThread/updateThread/loadThread/processMessage props	storage.thread.* (e.g. restStorage) + llm.send
Artifact({...}) factory, ArtifactConfig/Controls	DetailedView({...}) (config panel → actual), DetailedViewConfig/Controls
ArtifactPanel/ArtifactOverlay/ArtifactPortalTarget (+ props)	DetailedViewPanel/Overlay/PortalTarget (+ props)
useArtifact, useActiveArtifact, useArtifactPortalTarget	useDetailedView, useActiveDetailedView, useDetailedViewPortalTarget
ArtifactContext, useArtifactStore, openArtifact/closeArtifact	useDetailedViewStore, setActiveDetailedView/reset
import * as Shell / import * as CopilotShell	removed — compose <AgentInterface> slots
processStreamedMessage(..., deleteMessage)	markToolExecuting/clearToolExecuting (optional)

Notes consumers should know: artifactRenderers must be memoized/module-constant (registry frozen at mount); restStorage covers only the thread channel (provide storage.artifact separately); toolName matching is exact-match only in this PR (no RegExp/* dispatch yet); the top-level Artifact name now resolves to the headless domain type, not the old factory.

Test plan

• react-headless unit suites: restStorage, processStreamedMessage (+ tool-status), toolActivity, sseLines, artifactRendererRegistry (first-wins + dev warns), createThreadContextStore, createDetailedViewStore, thread-switch resets.
• Adapter migration: confirm old apiUrl/threadApiUrl props are TS errors; fetchLLM + restStorage drive a thread end-to-end.
• Tool calls: TOOL_CALL_CHUNK-only stream renders; TOOL_CALL_END → executing; run ends without result → no perpetual shimmer; errored call suppresses the preview; Behind the scenes · N failed count; web_search renders preview + side panel.
• AgentInterface: no artifact storage → ArtifactNav/Workspace/browser render nothing; unknown category → not-found + "View all artifacts"; uncategorized artifacts appear in the fallback section; DetailedView opens → sidebar collapses, splitter clamps [420px, 80%], keyboard resize works; <768px → slide-over sidebar.
• Shell removal: import * as Shell / import { Artifact } (as factory) fail to compile; legacy XML-envelope messages still render via parseLegacyXml; new ]]>openui: sentinel parses.
• a11y: prefers-reduced-motion stops all reveal/shimmer/spin animations; status changes announce via the live region.
• Examples: openui-cloud (with vendored tarball + keys) loads threads and opens slides/report panels; openui-responses-chat multi-turn tools + code artifact; migrated examples build and run; monorepo pnpm install --frozen-lockfile stays green with openui-cloud excluded.
• lang-core: an openui-lang stream prefixed by markdown prose/fences parses without losing completed statements.
• Docs: /docs/agent/* renders with the new navbar tab; old /docs/chat/* is gone; migration guide links resolve.

Known follow-ups / caveats

• docs/agent/getting-started/openui-cloud.mdx is a "Coming soon" stub; several concept/customize pages carry inline TODO/ASSUMED and "add video/image" placeholders (notably tools.mdx).
• The allowBuilds stanza added to pnpm-workspace.yaml has placeholder string values and is inert until populated with real booleans.
• openui-cloud is not installed by a root pnpm install (workspace-excluded); its vendor/ tarball must be produced from genui-sdk first.
• The retired Shell/CopilotShell/BottomTray directories are fully deleted (no dead code left on disk).