Generative UI (JSON spec)

MessagePrimitive.GenerativeUI is a first-class primitive for rendering UI described by the agent at runtime as a JSON spec. Instead of hard-coding a component per tool, the agent emits a generative-ui message part containing a tree of components by name. assistant-ui resolves each name against a consumer-provided allowlist and renders the result.

Which generative UI pattern?

assistant-ui uses "generative UI" in three different places. Pick the one that matches your integration:

See also: Tool UI guide, LangGraph generative UI.

When not to use the primitive

• User input and two-way interaction → Tool UI or Interactables
• LangGraph push_ui_message → LangGraph data UI
• Untrusted HTML or third-party widgets → MCP Apps (sandboxed frames)

Quick start

1. Define your component allowlist

const Card = ({ title, children }) => (
  <div className="rounded-xl border bg-card p-4 shadow-sm">
    <div className="text-base font-semibold">{title}</div>
    <div className="mt-2">{children}</div>
  </div>
);

const Button = ({ label }) => (
  <button className="rounded-md bg-primary px-3 py-1.5 text-primary-foreground">
    {label}
  </button>
);

export const componentsAllowlist = { Card, Button };

2. Wire the primitive into your message renderer

See Opt-in wiring for all three integration patterns.

3. Have the agent emit UI

ExternalStore / manual messages attach a native part:

{
  type: "generative-ui",
  spec: {
    root: {
      component: "Card",
      props: { title: "Welcome" },
      children: [
        { component: "Button", props: { label: "Get started" } },
      ],
    },
  },
}

AI SDK (useChatRuntime) — the adapter maps tool results to tool-call parts, not generative-ui parts. Use the AI SDK interim bridge until a native emission helper ships.

Live examples in examples/with-generative-ui: Tool UI demo (/), static primitive (/primitive), GUI chat (/gui-chat).

Opt-in wiring

The stock @assistant-ui/ui Thread switch returns null for unknown part types — including generative-ui. Add one of these patterns in your assistant message renderer (~15 lines).

Pattern 1 — MessagePrimitive.Parts

<MessagePrimitive.Parts
  components={{
    generativeUI: {
      components: componentsAllowlist,
      Fallback: UnknownComponentFallback,
    },
  }}
/>

Pattern 2 — GroupedParts case (shadcn Thread fork)

case "generative-ui":
  return (
    <MessagePrimitive.GenerativeUI
      components={componentsAllowlist}
      Fallback={UnknownComponentFallback}
    />
  );

Also exclude render_gui from tool-group chrome in groupBy if you use the AI SDK bridge (return null for that tool name).

Pattern 3 — AI SDK interim bridge

When using useChatRuntime, map a dedicated tool result to the renderer:

case "tool-call":
  if (part.toolName === "render_gui") {
    const spec = parseRenderGuiResult(part.result);
    if (spec) {
      return (
        <MessagePrimitive.GenerativeUI
          spec={spec}
          components={componentsAllowlist}
          Fallback={UnknownComponentFallback}
        />
      );
    }
  }
  return part.toolUI ?? <ToolFallback {...part} />;

The message store still holds a tool-call on this path — not a generative-ui part. See examples/with-generative-ui/app/gui-chat for a working reference.

Bare strings act as inline text leaves.

Spec shape

type GenerativeUINode =
  | string
  | {
      component: string;             // resolved against the allowlist
      props?: Record<string, unknown>;
      children?: GenerativeUINode[];
      key?: string;                   // optional stable React key
    };

type GenerativeUISpec = {
  root: GenerativeUINode | GenerativeUINode[];
};

The spec is plain JSON — easy for any agent to emit, and easy to validate on the server before delivery.

Streaming

When a message contains native generative-ui parts whose spec updates incrementally (for example via ExternalStore), the primitive renders progressively as nodes and props arrive.

The AI SDK render_gui tool path returns the full spec at tool completion — not incrementally during the tool execute step. For args streaming during generation, use Tool UI instead.

Security

The allowlist is the boundary on which components render: a spec can only instantiate components you put in the registry, with no eval and no dynamic import (names are looked up in the registry and nothing else). An unknown name throws GenerativeUIRenderError or invokes your Fallback.

It does not constrain the props the agent supplies. Spec props are spread directly onto your allowlisted components, so treat every allowlisted component as receiving untrusted input: never forward agent-supplied props into dangerouslySetInnerHTML, validate or reject href / src values (for example block javascript: URLs), and avoid passing spec props anywhere they become executable. The safest allowlisted components accept only primitive, display-oriented props.

Error handling

Unknown component names throw GenerativeUIRenderError with a typed componentName field. Catch it with a React error boundary, or pass a Fallback component to opt into a soft-fail UX:

<MessagePrimitive.GenerativeUI
  components={componentsAllowlist}
  Fallback={({ component }) => (
    <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">
      unknown component: {component}
    </span>
  )}
/>

Composing with other primitives

generative-ui is a regular MessagePart type, so it composes cleanly with MessagePrimitive.Parts, MessagePrimitive.PartByIndex, and MessagePrimitive.GroupedParts. Render it alongside text, tool calls, and reasoning in the same message.

Why a primitive (not just a tool)

Tool-call UI is great when the agent already invoked a known tool. Generative UI flips it: the agent composes UI from a vocabulary you ship. Useful for dashboards, status panels, and structured layouts — not for collecting user input (use Tool UI for that).