@assistant-ui/mcp-docs-server 0.1.1

package/.docs/raw/docs/guides/ToolUI.mdx

@@ -0,0 +1,663 @@
+---
+title: Generative UI
+---
+
+import { ToolUISample } from "../../../components/samples/tool-ui-sample";
+import { Steps, Step } from "fumadocs-ui/components/steps";
+import { Callout } from "fumadocs-ui/components/callout";
+
+Create custom UI components for AI tool calls, providing visual feedback and interactive experiences when tools are executed.
+
+<ToolUISample />
+
+## Overview
+
+Tool UIs in assistant-ui allow you to create custom interfaces that appear when AI tools are called. These generative UI components enhance the user experience by:
+
+- **Visualizing tool execution** with loading states and progress indicators
+- **Displaying results** in rich, formatted layouts
+- **Enabling user interaction** through forms and controls
+- **Providing error feedback** with helpful recovery options
+
+This guide demonstrates building tool UIs with the **Vercel AI SDK**.
+
+## Creating Tool UIs
+
+There are two main approaches to creating tool UIs in assistant-ui:
+
+### 1. Client-Defined Tools (`makeAssistantTool`)
+
+If you're creating tools on the client side, use `makeAssistantTool` to register them with the assistant context. Then create a UI component with `makeAssistantToolUI`:
+
+```tsx
+import { makeAssistantTool, tool } from "@assistant-ui/react";
+import { z } from "zod";
+
+// Define the tool
+const weatherTool = tool({
+  description: "Get current weather for a location",
+  parameters: z.object({
+    location: z.string(),
+    unit: z.enum(["celsius", "fahrenheit"]),
+  }),
+  execute: async ({ location, unit }) => {
+    const weather = await fetchWeatherAPI(location, unit);
+    return weather;
+  }
+});
+
+// Register the tool
+const WeatherTool = makeAssistantTool(weatherTool);
+
+// Create the UI
+const WeatherToolUI = makeAssistantToolUI<
+  { location: string; unit: "celsius" | "fahrenheit" },
+  { temperature: number; description: string }
+>({
+  toolName: "getWeather",
+  render: ({ args, result, status }) => {
+    if (status.type === "running") {
+      return <div>Checking weather in {args.location}...</div>;
+    }
+
+    return (
+      <div className="weather-card">
+        <h3>{args.location}</h3>
+        <p>
+          {result.temperature}°{args.unit === "celsius" ? "C" : "F"}
+        </p>
+        <p>{result.description}</p>
+      </div>
+    );
+  },
+});
+```
+
+<Callout type="tip">
+  Tools defined with `makeAssistantTool` can be passed to your backend using the `frontendTools` utility
+</Callout>
+
+Learn more about creating tools in the [Tools Guide](/docs/guides/Tools).
+
+### 2. UI-Only for Existing Tools (`makeAssistantToolUI`)
+
+If your tool is defined elsewhere (e.g., in your backend API, MCP server, or LangGraph), use `makeAssistantToolUI` to create just the UI component:
+
+```tsx
+import { makeAssistantToolUI } from "@assistant-ui/react";
+
+const WeatherToolUI = makeAssistantToolUI<
+  { location: string; unit: "celsius" | "fahrenheit" },
+  { temperature: number; description: string }
+>({
+  toolName: "getWeather", // Must match the backend tool name
+  render: ({ args, result, status }) => {
+    // UI rendering logic only
+  },
+});
+```
+
+## Quick Start Example
+
+This example shows how to implement the UI-only approach using `makeAssistantToolUI`:
+
+<Steps>
+  <Step>
+
+### Create a Tool UI Component
+
+```tsx
+import { makeAssistantToolUI } from "@assistant-ui/react";
+import { z } from "zod";
+
+type WeatherArgs = {
+  location: string;
+  unit: "celsius" | "fahrenheit";
+};
+
+type WeatherResult = {
+  temperature: number;
+  description: string;
+  humidity: number;
+  windSpeed: number;
+};
+
+const WeatherToolUI = makeAssistantToolUI<WeatherArgs, WeatherResult>({
+  toolName: "getWeather",
+  render: ({ args, status, result }) => {
+    if (status.type === "running") {
+      return (
+        <div className="flex items-center gap-2">
+          <Spinner />
+          <span>Checking weather in {args.location}...</span>
+        </div>
+      );
+    }
+
+    if (status.type === "incomplete" && status.reason === "error") {
+      return (
+        <div className="text-red-500">
+          Failed to get weather for {args.location}
+        </div>
+      );
+    }
+
+    return (
+      <div className="weather-card rounded-lg bg-blue-50 p-4">
+        <h3 className="text-lg font-bold">{args.location}</h3>
+        <div className="mt-2 grid grid-cols-2 gap-4">
+          <div>
+            <p className="text-2xl">
+              {result.temperature}°{args.unit === "celsius" ? "C" : "F"}
+            </p>
+            <p className="text-gray-600">{result.description}</p>
+          </div>
+          <div className="text-sm">
+            <p>Humidity: {result.humidity}%</p>
+            <p>Wind: {result.windSpeed} km/h</p>
+          </div>
+        </div>
+      </div>
+    );
+  },
+});
+```
+
+  </Step>
+  <Step>
+
+### Register the Tool UI
+
+Place the component inside your `AssistantRuntimeProvider`:
+
+```tsx
+function App() {
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+      <WeatherToolUI />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+  </Step>
+  <Step>
+
+### Define the Backend Tool (Vercel AI SDK)
+
+When using the Vercel AI SDK, define the corresponding tool in your API route:
+
+```tsx title="/app/api/chat/route.ts"
+import { streamText, tool } from "ai";
+import { z } from "zod";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages,
+    tools: {
+      getWeather: tool({
+        description: "Get current weather for a location",
+        parameters: z.object({
+          location: z.string(),
+          unit: z.enum(["celsius", "fahrenheit"]),
+        }),
+        execute: async ({ location, unit }) => {
+          const weather = await fetchWeatherAPI(location);
+          return {
+            temperature: weather.temp,
+            description: weather.condition,
+            humidity: weather.humidity,
+            windSpeed: weather.wind,
+          };
+        },
+      }),
+    },
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+  </Step>
+</Steps>
+
+## Tool UI Patterns
+
+### Component Pattern
+
+Create standalone tool UI components:
+
+```tsx
+export const WebSearchToolUI = makeAssistantToolUI<
+  { query: string },
+  { results: SearchResult[] }
+>({
+  toolName: "webSearch",
+  render: ({ args, status, result }) => {
+    return (
+      <div className="search-container">
+        <div className="mb-3 flex items-center gap-2">
+          <SearchIcon />
+          <span>Search results for: "{args.query}"</span>
+        </div>
+
+        {status.type === "running" && <LoadingSpinner />}
+
+        {result && (
+          <div className="space-y-2">
+            {result.results.map((item, index) => (
+              <div key={index} className="rounded border p-3">
+                <a href={item.url} className="font-medium text-blue-600">
+                  {item.title}
+                </a>
+                <p className="text-sm text-gray-600">{item.snippet}</p>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  },
+});
+```
+
+### Hook Pattern
+
+Use hooks for dynamic tool UI registration:
+
+<Callout type="tip">
+When you assign your `makeAssistantToolUI({...})` call to a constant starting with `use…`, you can call it directly as a hook inside your component. This pattern lets you access local props or state when rendering the tool UI.
+</Callout>
+
+```tsx
+import { useAssistantToolUI } from "@assistant-ui/react";
+
+function DynamicToolUI() {
+  const [theme, setTheme] = useState("light");
+
+  useAssistantToolUI({
+    toolName: "analyzeData",
+    render: ({ args, result, status }) => {
+      // Hook allows access to component state
+      return (
+        <DataVisualization
+          data={result}
+          theme={theme}
+          loading={status.type === "running"}
+        />
+      );
+    },
+  });
+
+  return null;
+}
+```
+
+### Inline Pattern
+
+For tools that need access to parent component props:
+
+<Callout type="tip">
+**Why `useInlineRender`?**
+By default, a tool UI's `render` function is static. Use `useInlineRender` when your UI needs access to dynamic component props (for example, to pass in an `id` or other contextual data).
+</Callout>
+
+```tsx
+import { useAssistantToolUI, useInlineRender } from "@assistant-ui/react";
+
+function ProductPage({ productId, productName }) {
+  useAssistantToolUI({
+    toolName: "checkInventory",
+    render: useInlineRender(({ args, result }) => {
+      // Access parent component props
+      return (
+        <div className="inventory-status">
+          <h4>{productName} Inventory</h4>
+          <p>
+            Stock for {productId}: {result.quantity} units
+          </p>
+          <p>Location: {result.warehouse}</p>
+        </div>
+      );
+    }),
+  });
+
+  return <div>Product details...</div>;
+}
+```
+
+## Interactive Tool UIs
+
+### User Input Collection
+
+Create tools that collect user input during execution:
+
+<Callout type="tip">
+**Pro tip:** Call `addResult(...)` exactly once to complete the tool call. After it's invoked, the assistant will resume the conversation with your provided data.
+</Callout>
+
+```tsx
+const DatePickerToolUI = makeAssistantToolUI<
+  { prompt: string },
+  { date: string }
+>({
+  toolName: "selectDate",
+  render: ({ args, result, addResult }) => {
+    if (result) {
+      return (
+        <div className="rounded bg-green-50 p-3">
+          ✅ Selected date: {new Date(result.date).toLocaleDateString()}
+        </div>
+      );
+    }
+
+    return (
+      <div className="rounded border p-4">
+        <p className="mb-3">{args.prompt}</p>
+        <DatePicker
+          onChange={(date) => {
+            addResult({ date: date.toISOString() });
+          }}
+        />
+      </div>
+    );
+  },
+});
+```
+
+### Multi-Step Interactions
+
+Build complex workflows with multiple user interactions:
+
+```tsx
+const ApprovalToolUI = makeAssistantToolUI<
+  { action: string; details: any },
+  { approved: boolean; reason?: string }
+>({
+  toolName: "requestApproval",
+  render: ({ args, result, addResult }) => {
+    const [reason, setReason] = useState("");
+
+    if (result) {
+      return (
+        <div className={result.approved ? "text-green-600" : "text-red-600"}>
+          {result.approved ? "✅ Approved" : `❌ Rejected: ${result.reason}`}
+        </div>
+      );
+    }
+
+    return (
+      <div className="rounded border-2 border-yellow-400 p-4">
+        <h4 className="font-bold">Approval Required</h4>
+        <p className="my-2">{args.action}</p>
+        <pre className="rounded bg-gray-100 p-2 text-sm">
+          {JSON.stringify(args.details, null, 2)}
+        </pre>
+
+        <div className="mt-4 flex gap-2">
+          <button
+            onClick={() => addResult({ approved: true })}
+            className="rounded bg-green-500 px-4 py-2 text-white"
+          >
+            Approve
+          </button>
+          <button
+            onClick={() => addResult({ approved: false, reason })}
+            className="rounded bg-red-500 px-4 py-2 text-white"
+          >
+            Reject
+          </button>
+          <input
+            type="text"
+            placeholder="Rejection reason..."
+            value={reason}
+            onChange={(e) => setReason(e.target.value)}
+            className="flex-1 rounded border px-2"
+          />
+        </div>
+      </div>
+    );
+  },
+});
+```
+
+## Advanced Features
+
+### Tool Status Handling
+
+The `status` prop provides detailed execution state:
+
+```tsx
+render: ({ status, args }) => {
+  switch (status.type) {
+    case "running":
+      return <LoadingState />;
+
+    case "requires-action":
+      return <UserInputRequired reason={status.reason} />;
+
+    case "incomplete":
+      if (status.reason === "cancelled") {
+        return <div>Operation cancelled</div>;
+      }
+      if (status.reason === "error") {
+        return <ErrorDisplay error={status.error} />;
+      }
+      return <div>Failed: {status.reason}</div>;
+
+    case "complete":
+      return <SuccessDisplay />;
+  }
+};
+```
+
+### Field-Level Validation
+
+Use `useToolArgsFieldStatus` to show validation states:
+
+```tsx
+import { useToolArgsFieldStatus } from "@assistant-ui/react";
+
+const FormToolUI = makeAssistantToolUI({
+  toolName: "submitForm",
+  render: ({ args }) => {
+    const emailStatus = useToolArgsFieldStatus("email");
+    const phoneStatus = useToolArgsFieldStatus("phone");
+
+    return (
+      <form className="space-y-4">
+        <div>
+          <input
+            type="email"
+            value={args.email}
+            className={emailStatus.type === "running" ? "loading" : ""}
+            disabled
+          />
+          {emailStatus.type === "incomplete" && (
+            <span className="text-red-500">Invalid email</span>
+          )}
+        </div>
+
+        <div>
+          <input
+            type="tel"
+            value={args.phone}
+            className={phoneStatus.type === "running" ? "loading" : ""}
+            disabled
+          />
+        </div>
+      </form>
+    );
+  },
+});
+```
+
+### Partial Results & Streaming
+
+Display results as they stream in:
+
+```tsx
+const AnalysisToolUI = makeAssistantToolUI<
+  { data: string },
+  { progress: number; insights: string[] }
+>({
+  toolName: "analyzeData",
+  render: ({ result, status }) => {
+    const progress = result?.progress || 0;
+    const insights = result?.insights || [];
+
+    return (
+      <div className="analysis-container">
+        {status.type === "running" && (
+          <div className="mb-4">
+            <div className="mb-1 flex justify-between">
+              <span>Analyzing...</span>
+              <span>{progress}%</span>
+            </div>
+            <div className="w-full rounded bg-gray-200">
+              <div
+                className="h-2 rounded bg-blue-500"
+                style={{ width: `${progress}%` }}
+              />
+            </div>
+          </div>
+        )}
+
+        <div className="space-y-2">
+          {insights.map((insight, i) => (
+            <div key={i} className="rounded bg-gray-50 p-2">
+              {insight}
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  },
+});
+```
+
+### Custom Tool Fallback
+
+Provide a custom UI for tools without specific UIs:
+
+```tsx
+<Thread
+  components={{
+    ToolFallback: ({ toolName, args, result }) => (
+      <div className="tool-fallback rounded bg-gray-100 p-3">
+        <code className="text-sm">
+          {toolName}({JSON.stringify(args)})
+        </code>
+        {result && (
+          <pre className="mt-2 text-xs">{JSON.stringify(result, null, 2)}</pre>
+        )}
+      </div>
+    ),
+  }}
+/>
+```
+
+## Execution Context
+
+Generative UI components have access to execution context through props:
+
+```tsx
+type ToolUIRenderProps<TArgs, TResult> = {
+  // Tool arguments
+  args: TArgs;
+  argsText: string; // JSON stringified args
+
+  // Execution status
+  status: ToolCallContentPartStatus;
+  isError?: boolean;
+
+  // Tool result (may be partial during streaming)
+  result?: TResult;
+
+  // Tool metadata
+  toolName: string;
+  toolCallId: string;
+
+  // Interactive callback
+  addResult: (result: TResult) => void;
+
+  // Optional artifact data
+  artifact?: unknown;
+};
+```
+
+## Best Practices
+
+### 1. Handle All Status States
+
+Always handle loading, error, and success states:
+
+```tsx
+render: ({ status, result, args }) => {
+  if (status.type === "running") return <Skeleton />;
+  if (status.type === "incomplete") return <ErrorState />;
+  if (!result) return null;
+  return <ResultDisplay result={result} />;
+};
+```
+
+### 2. Provide Visual Feedback
+
+Use animations and transitions for better UX:
+
+```tsx
+<div
+  className={cn(
+    "transition-all duration-300",
+    status.type === "running" && "opacity-50",
+    status.type === "complete" && "opacity-100",
+  )}
+>
+  {/* Tool UI content */}
+</div>
+```
+
+### 3. Make UIs Accessible
+
+Ensure keyboard navigation and screen reader support:
+
+```tsx
+<button
+  onClick={() => addResult(value)}
+  aria-label="Confirm selection"
+  className="focus:outline-none focus:ring-2"
+>
+  Confirm
+</button>
+```
+
+### 4. Optimize Performance
+
+Use `useInlineRender` to prevent unnecessary re-renders:
+
+```tsx
+useAssistantToolUI({
+  toolName: "heavyComputation",
+  render: useInlineRender(({ result }) => {
+    // Expensive rendering logic
+    return <ComplexVisualization data={result} />;
+  }),
+});
+```
+
+<Callout>
+  Generative UI components are only displayed in the chat interface. The actual
+  tool execution happens on the backend. This separation allows you to create
+  rich, interactive experiences while keeping sensitive logic secure on the
+  server.
+</Callout>
+
+## Related Guides
+
+- [Tools Guide](/docs/guides/Tools) - Learn how to create and use tools with AI models
+- [Tool Fallback](/docs/ui/ToolFallback) - Default UI for tools without custom components
+- [API Reference](/docs/api-reference/primitives/ContentPart) - Detailed type definitions and component APIs