Overview
Level 3: Advanced · Module 8: Generative UI · 22 min read
Why this matters
In standard tool-calling architectures, tool results are converted into text strings and fed back into the model for a second pass, only for the model to re-describe the data in prose. For rich visual data (like a 7-day weather forecast, financial balance sheets, or calendar slot pickers), this second LLM pass is pure waste: it adds 3–5 seconds of latency, burns additional tokens, and degrades structured data into lossy text paragraphs. By mapping tool results directly to typed React components on the frontend, you bypass the second LLM turn entirely, rendering pixel-perfect, interactive widgets instantaneously upon tool execution.
Learning objectives
- Build a direct pipeline mapping tool execution payloads to typed React components.
- Eliminate redundant second-turn LLM generation latency for visual data.
- Validate tool outputs with Zod before mounting client components.
- Manage client component state and user interactions (clicks, form submits) within the chat stream.
- Handle partial tool streaming states with loading skeleton cards.
The Direct Tool-to-Component Flow
graph LR
subgraph TraditionalTurn["Traditional Turn (Slow & Lossy)"]
A1["Tool Runs"] --> B1["Raw JSON Data"]
B1 --> C1["Second LLM Pass (3-5s delay)"]
C1 --> D1["Markdown Text Paragraphs"]
end
subgraph DirectGenUI["Direct Generative UI Mapping (Instantaneous & Interactive)"]
A2["Tool Runs"] --> B2["Raw JSON Data"]
B2 --> C2["Zod Schema Validation"]
C2 --> D2["Mount <InteractiveFlightCard data={...} />"]
D2 --> E2["Zero second-turn latency! User clicks to book immediately!"]
endStep 1: Defining the Typed Tool and Component Pair
First, define the Zod schema representing the tool output and the React component props:
// components/gen-ui/weather-card.tsx
import React from "react";
import { z } from "zod";
export const WeatherDataSchema = z.object({
city: z.string(),
temperature: z.number(),
condition: z.enum(["SUNNY", "RAINY", "CLOUDY", "SNOWY"]),
humidity: z.number(),
forecast: z.array(
z.object({
day: z.string(),
high: z.number(),
low: z.number(),
})
).max(5),
});
export type WeatherData = z.infer<typeof WeatherDataSchema>;
export function WeatherCard({ data }: { data: WeatherData }) {
const iconMap = {
SUNNY: "☀️",
RAINY: "🌧️",
CLOUDY: "☁️",
SNOWY: "❄️",
};
return (
<div className="my-3 p-5 rounded-2xl border border-blue-200 dark:border-blue-900 bg-gradient-to-br from-blue-50 to-indigo-50 dark:from-blue-950/40 dark:to-indigo-950/30">
<div className="flex justify-between items-start">
<div>
<h3 className="text-base font-bold text-gray-900 dark:text-white">{data.city}</h3>
<span className="text-xs text-gray-500 capitalize">{data.condition.toLowerCase()}</span>
</div>
<div className="text-right">
<span className="text-3xl font-black font-mono text-gray-900 dark:text-white flex items-center gap-1">
<span>{iconMap[data.condition] || "🌤️"}</span>
<span>{data.temperature}°</span>
</span>
</div>
</div>
{/* 3-Day Forecast Strip */}
<div className="grid grid-cols-3 gap-2 mt-4 pt-3 border-t border-blue-200/60 dark:border-blue-900/40">
{data.forecast.map((f, i) => (
<div key={i} className="text-center p-2 rounded-lg bg-white/70 dark:bg-gray-900/60">
<span className="text-[10px] font-mono text-gray-400 block uppercase">{f.day}</span>
<span className="text-xs font-bold text-gray-800 dark:text-gray-200">
{f.high}° / {f.low}°
</span>
</div>
))}
</div>
</div>
);
}Step 2: The Chat Message Dispatcher
In your chat message renderer, inspect incoming messages. If a message contains a tool_call or typed tool result, route it to the registered component:
// components/MessageItem.tsx
"use client";
import React from "react";
import { WeatherCard, WeatherDataSchema } from "./gen-ui/weather-card";
export interface ChatMessage {
id: string;
role: "user" | "assistant" | "tool";
content: string;
toolCallName?: string;
toolData?: unknown;
}
export function MessageItem({ message }: { message: ChatMessage }) {
// If message role is 'tool' and matches our registered component
if (message.role === "tool" && message.toolCallName === "get_weather") {
const parseResult = WeatherDataSchema.safeParse(message.toolData);
if (parseResult.success) {
return <WeatherCard data={parseResult.data} />;
}
// Defensive fallback: render raw JSON if schema mismatched
return (
<pre className="p-3 bg-gray-100 rounded text-xs font-mono">
{JSON.stringify(message.toolData, null, 2)}
</pre>
);
}
// Standard conversational text message
return (
<div className={`p-4 rounded-xl text-sm ${message.role === "user" ? "bg-blue-600 text-white ml-auto" : "bg-gray-100 dark:bg-gray-800"}`}>
{message.content}
</div>
);
}Emitting User Events from Generative Components
A major power of Generative UI is that components can emit state mutations back into the chat session. When a user clicks "Select Flight" inside a generated card, the component can dispatch an affirmative message back to the server:
export function FlightCardWithAction({ flight, onSelect }: { flight: Flight; onSelect: (flightId: string) => void }) {
const [isBooked, setIsBooked] = useState(false);
const handleClick = () => {
setIsBooked(true);
// Dispatches user confirmation turn back into chat state machine!
onSelect(flight.id);
};
return (
<div className="p-4 rounded-xl border">
<h4>{flight.airline} - ${flight.price}</h4>
<button
onClick={handleClick}
disabled={isBooked}
className="mt-2 px-4 py-2 bg-blue-600 text-white rounded font-bold"
>
{isBooked ? "✓ Selected" : "Select Flight"}
</button>
</div>
);
}Interview Angle: How to Answer in System Design
- Question: "Why map tool outputs directly to React components rather than having the model summarize the data in a second turn?"
- Target Answer:
"Direct tool-to-component mapping yields two decisive advantages:
- Latency & Cost: A second LLM forward pass introduces 3 to 6 seconds of streaming delay and burns hundreds of output tokens simply re-describing JSON keys as English prose. Mapping directly to a component renders in 0 milliseconds with zero token cost.
- Precision & Interactivity: Text descriptions lose interactive fidelity. By rendering a React component, users can filter columns, toggle dark mode, click action buttons ('Book Now'), and submit authenticated actions directly from the chat feed."
Quick Check
- What are the two primary benefits of mapping tool outputs directly to React components?
- What should your message renderer do if tool output fails the component's Zod schema?
- How can a generated component communicate user interactions back into the conversation thread?