Generative UI Rendering

API Reference

buildPresentParameters

Builds the JSON schema for the present tool from a GenerativeUILibrary.

The model produces a node { $type, $key?,...props } where $type selects a component, the optional $key pins a stable identity for list items that may reorder, and the rest are its props. The schema is a flat object: $type is an enum of the component names, every component's props are merged into one optional bag, and children recurses via $defs so the tree can nest.

It is intentionally flat rather than a per-$type discriminated union. Tool / function-call schemas (OpenAI and others) require the top-level parameters to be a plain object and reject a top-level oneOf/anyOf/enum. So props can't be refined per $type at the root; the model is guided instead by $type's description (which lists each component) and each prop's own description. The renderer validates nothing here — an unknown $type or stray prop is handled at render time — so a looser schema only costs the model a hint, not safety.

GenerativeUIRender

Internal renderer. Resolves a GenerativeUISpec against the consumer allowlist. Used by MessagePrimitive.GenerativeUI and by MessagePrimitive.Parts when handling a generative-ui part.

GenerativeUIRenderContext

The render context threaded through renderGenerativeUI.

GenerativeUIRenderError

Thrown when a generative-ui spec references a component name that is not present in the consumer-provided allowlist. The allowlist is the security boundary in the same-realm rendering path — there is no fallback by default. Pass Fallback to opt into a soft-fail UX.

generativeUIToJSX

Serializes a generative-UI node to a JSX-like string for display: the "view source" of a model-produced tree. The wire form { $type: "Weather", id: "x" } becomes <Weather id="x" />, and nested children render between tags: <Card title="Hi"><Text>hello</Text></Card>. A model-provided $key becomes the JSX key attribute.

By default this is a faithful textual rendering, not a parser: text children are emitted verbatim (not HTML/JSX-escaped), so the result is meant to be shown, not re-parsed. Returns "" for nodes that aren't renderable (no $type yet, null, booleans).

Pass { escape: true } to make the output safe to paste back into JSX: any string child containing <, >, &, {, or } is emitted as a JSON-stringified expression ({JSON.stringify(child)}) instead of verbatim, while a string child with none of those characters still renders verbatim.

Pass { pretty: true } to pretty-print nested element trees with two-space indentation, while pure text children stay on one line.

renderGenerativeUI

Renders a generative-ui tree against a GenerativeUILibrary.

The model emits each node as a flat object { $type,...props }. We first normalize that wire form into the canonical NormalizedUINode (with children lifted to a reserved top-level key), then render: each type is looked up in the library and its props are passed to the component's render(props, context), with children rendered recursively so components can nest.