Tool Calling and UI Generation with the AI SDK

Generative UI means the model calls tools, and your React tree turns tool results into real components - cards, tables, forms - not only markdown.

This page wires a server tool into streamText, streams typed tool parts to useChat, and maps those parts to components.

Summary

Define tools with description, inputSchema, and optional execute; stream them through a UI message response; on the client, switch on part.type (tool-${name}) and part.state to render loading, result, and error UI.

Recipe

1. Create a tools module with tool() (or plain tool objects) and Zod inputSchema.
2. Register tools on streamText (or an agent) and bound steps with stopWhen.
3. Return a UI message stream response from the App Router route.
4. Render message.parts in the client; map each tool part type to a component.
5. Handle part states: input streaming/available, output available, output error.
6. For client-only tools, omit execute and use onToolCall + addToolOutput.
7. Optionally auto-continue with sendAutomaticallyWhen when client tool results are complete.

Working Example

ai/tools.ts:

import { tool } from "ai";
import { z } from "zod";
 
export const displayWeather = tool({
  description: "Show the weather for a location in the chat UI",
  inputSchema: z.object({
    location: z.string().describe("City or place name"),
  }),
  execute: async ({ location }) => {
    // Replace with a real weather API
    return { location, weather: "Sunny", temperature: 22 };
  },
});
 
export const tools = { displayWeather };

app/api/chat/route.ts:

import {
  convertToModelMessages,
  isStepCount,
  streamText,
  type UIMessage,
} from "ai";
import { tools } from "@/ai/tools";
 
export const maxDuration = 30;
 
export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();
 
  const result = streamText({
    model: "openai/gpt-4o-mini", // verify at build
    instructions: "Use displayWeather when the user asks about weather.",
    messages: await convertToModelMessages(messages),
    tools,
    stopWhen: isStepCount(5),
  });
 
  return result.toUIMessageStreamResponse();
}

components/weather.tsx + client render sketch:

"use client";
 
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
import { useState } from "react";
 
function Weather(props: {
  location: string;
  weather: string;
  temperature: number;
}) {
  return (
    <div>
      <h3>{props.location}</h3>
      <p>
        {props.weather}, {props.temperature}°C
      </p>
    </div>
  );
}
 
export default function Page() {
  const [input, setInput] = useState("");
  const { messages, sendMessage } = useChat({
    transport: new DefaultChatTransport({ api: "/api/chat" }),
  });
 
  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          {m.parts.map((part, i) => {
            if (part.type === "text") return <span key={i}>{part.text}</span>;
            if (part.type === "tool-displayWeather") {
              if (part.state === "input-available")
                return <div key={i}>Loading weather…</div>;
              if (part.state === "output-available")
                return <Weather key={i} {...part.output} />;
              if (part.state === "output-error")
                return <div key={i}>Error: {part.errorText}</div>;
            }
            return null;
          })}
        </div>
      ))}
      <form
        onSubmit={(e) => {
          e.preventDefault();
          sendMessage({ text: input });
          setInput("");
        }}
      >
        <input value={input} onChange={(e) => setInput(e.target.value)} />
      </form>
    </div>
  );
}

Deep Dive

Why tools are the UI contract

The model should not invent HTML.

It should call a named tool with structured input; your app owns presentation.

That separation keeps theming, accessibility, and validation under engineering control.

Server tools vs client tools

Part states drive UX

Treat tool parts as a small state machine:

• input-streaming / input-available - show skeleton or partial args
• output-available - mount the real component with part.output
• output-error - show recoverable error UI
• approval-requested (when using tool approval) - show approve/deny controls

Avoid assuming every tool finishes in one frame; multi-step agents interleave text and tools.

Description quality

Tool selection is only as good as description + schema field .describe() text.

Scope the tool: "weather for a place" beats "general helper."

One tool per UI surface often beats a mega-tool returning arbitrary JSON.

Type safety

Share Zod schemas or inferred types between tool output and React props.

When part types are generated or narrowed, prefer part.type === 'tool-displayWeather' switches over stringly toolName bags.

Multi-step continuation

After server tools run, stopWhen decides whether the model gets another step to narrate results.

After client tools, configure sendAutomaticallyWhen (for example lastAssistantMessageIsCompleteWithToolCalls) so the user does not click "continue" manually.

Generative UI is not free form

Limit which tools exist; do not let the model emit arbitrary component names.

Each tool is an allowlisted UI capability.

Gotchas

1. Rendering content only. Tool UIs never appear if you ignore parts.
2. Mismatched tool names. Part type tool-X must match the tools object key X.
3. Awaiting inside onToolCall incorrectly. Some guides warn that improper await patterns can deadlock; follow current AI SDK tool-usage docs.
4. No stopWhen. Multi-step tools can loop until platform timeout.
5. Passing secrets to the client. Anything needed for tool execute must stay server-side.
6. Treating outputs as trusted HTML. Still sanitize if you ever interpolate strings into dangerouslySetInnerHTML.
7. Version drift on response helpers. toUIMessageStreamResponse vs createUIMessageStreamResponse - verify at build for your AI SDK major.

Alternatives

FAQs

Related

• Vercel AI SDK Basics - chat scaffold
• The Vercel AI SDK Mental Model: Streaming UI Meets Agent Loops - parts and streams
• AI SDK 6's Tool-Approval States for Human-in-the-Loop Agents - approve before execute
• Chaining, Routing, and Evaluator-Optimizer Agent Patterns - multi-step workflows
• Vercel AI SDK Best Practices - habits
• Tool Use and Function Calling Basics - generic tool concepts

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.