Overview

Research Preview

Tool UI is in active development, and APIs are still coalescing as we refine discover better patterns for conversation-native UIs.

Tool UI is a React component framework for conversation‑native UIs inside AI chats.
Tools return JSON; Tool UI renders it as inline, narrated, referenceable surfaces.

At a glance

Conversation‑native components that live inside messages, optimized for chat width and scroll.
Schema‑first rendering: every surface is driven by a serializable schema with stable IDs.
Assistant‑anchored: the assistant introduces, interprets, and closes each surface.
Stack‑agnostic: works with any LLM/provider and orchestration layer.

Where it fits

Radix/shadcn (primitives) → Tool UI (conversation‑native components & schema) → AI SDK / LangGraph / etc. (LLM orchestration)

Who it’s for

React devs & design engineers building LLM chat apps.
Teams who want predictable, accessible UI that the assistant can reference (“the second row”).
Anyone who wants typed, schema‑validated tool outputs instead of brittle HTML strings.

Why Tool UI

Predictable rendering: Tools emit schema‑validated JSON; components render consistently across themes/devices.
Built for chat: Mobile‑first, glanceable, minimal chrome; no in‑message navigation flows.
Developer control: Components render; your app owns side effects via callbacks/server actions.
Type safety: Serializable schemas on the server, parsers on the client; works great with AI SDK InferUITools.
Lifecycle aware: Clear phases from invocation through receipt; supersession behavior is explicit.

Mental model

See UI Guidelines for the full philosophy. Quick summary:

5 Fundamentals: One intent · Inline · Schema‑first · Assistant‑anchored · Lifecycle aware
Roles: information, decision, control, state, composite
Lifecycle: invocation → output‑pending → interactive → committing → receipt → errored
Conversation coherence: Every important action ↔ one canonical sentence; side effects yield a durable receipt (status, summary, identifiers, timestamp)

How it works

The assistant calls a tool, the tool returns JSON matching a schema, and the UI renders inline.

Loading diagram...

Minimal example

Server side: Define a tool that returns schema-validated JSON.

What this demonstrates:

serializableMediaCardSchema from @tool-ui/media-card ensures type-safe output
Actions are defined with both UI labels and canonical sentences for conversation coherence
The schema guarantees the frontend receives reconstructable, addressable data

import { streamText, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import { serializableMediaCardSchema } from "@/components/tool-ui/media-card/schema";

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    messages,
    tools: {
      previewLink: tool({
        description: "Show a preview card for a URL",
        inputSchema: z.object({ url: z.string().url() }),
        outputSchema: serializableMediaCardSchema,
        async execute({ url }) {
          return {
            id: "link-preview-1",
            assetId: "link-1",
            kind: "link",
            href: url,
            title: "Example Site",
            description: "A description of the linked content",
            thumb: "https://example.com/image.jpg",
          };
        },
      }),
    },
  });

  return result.toUIMessageStreamResponse();
}

import { streamText, tool } from "ai";import { openai } from "@ai-sdk/openai";import { z } from "zod";import { serializableMediaCardSchema } from "@/components/tool-ui/media-card/schema";export async function POST(req: Request) {  const { messages } = await req.json();  const result = streamText({    model: openai("gpt-4o"),    messages,    tools: {      previewLink: tool({        description: "Show a preview card for a URL",        inputSchema: z.object({ url: z.string().url() }),        outputSchema: serializableMediaCardSchema,        async execute({ url }) {          return {            id: "link-preview-1",            assetId: "link-1",            kind: "link",            href: url,            title: "Example Site",            description: "A description of the linked content",            thumb: "https://example.com/image.jpg",          };        },      }),    },  });  return result.toUIMessageStreamResponse();}

Client side: Register the component and let assistant-ui handle rendering.

What this demonstrates:

makeAssistantToolUI connects the tool name to a React component
The result object is automatically typed and validated against your schema
Simply mounting <PreviewLinkUI /> registers it—no manual plumbing required
assistant-ui manages the runtime, streaming, and tool call lifecycle

"use client";
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import {
  useChatRuntime,
  AssistantChatTransport,
  makeAssistantToolUI,
} from "@assistant-ui/react-ai-sdk";
import { MediaCard } from "@/components/tool-ui/media-card";

const PreviewLinkUI = makeAssistantToolUI({
  toolName: "previewLink",
  render: ({ result }) => <MediaCard {...result} maxWidth="420px" />,
});

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <PreviewLinkUI />
      {/* your <Thread /> component here */}
    </AssistantRuntimeProvider>
  );
}

"use client";import { AssistantRuntimeProvider } from "@assistant-ui/react";import {  useChatRuntime,  AssistantChatTransport,  makeAssistantToolUI,} from "@assistant-ui/react-ai-sdk";import { MediaCard } from "@/components/tool-ui/media-card";const PreviewLinkUI = makeAssistantToolUI({  toolName: "previewLink",  render: ({ result }) => <MediaCard {...result} maxWidth="420px" />,});export default function App() {  const runtime = useChatRuntime({    transport: new AssistantChatTransport({ api: "/api/chat" }),  });  return (    <AssistantRuntimeProvider runtime={runtime}>      <PreviewLinkUI />      {/* your <Thread /> component here */}    </AssistantRuntimeProvider>  );}

Anatomy of a surface

Every Tool UI surface is addressable and reconstructable. Here's the common schema structure:

What this shows:

id makes the tool UI referenceable by the assistant ("the link preview above")
role declares the primary purpose (information, decision, control, state, or composite)
actions with sentence fields enable natural language interaction
receipt provides durable proof of side effects with timestamps and identifiers

{
  id: string;                     // stable identifier for this rendering
  role: "information"|"decision"|"control"|"state"|"composite";
  actions?: Array<{ id: string; label: string; sentence: string }>;
  // optional receipt after side effects:
  receipt?: {
    outcome: "success"|"partial"|"failed"|"cancelled";
    summary: string;
    identifiers?: Record<string, string>;
    at: string;                   // ISO timestamp
  };
}

{  id: string;                     // stable identifier for this rendering  role: "information"|"decision"|"control"|"state"|"composite";  actions?: Array<{ id: string; label: string; sentence: string }>;  // optional receipt after side effects:  receipt?: {    outcome: "success"|"partial"|"failed"|"cancelled";    summary: string;    identifiers?: Record<string, string>;    at: string;                   // ISO timestamp  };}

Next steps

Quick Start: Wire your first Tool UI
UI Guidelines: Patterns, roles, lifecycle, receipts
Components: Explore Data Table, Media Card, Option List, Social Post

Quick Start