assistant-ui Tools

Always consult assistant-ui.com/llms.txt for latest API.

Tools let LLMs trigger actions with custom UI rendering.

References

• ./references/make-tool.md -- makeAssistantTool/useAssistantTool

• ./references/tool-ui.md -- makeAssistantToolUI rendering

• ./references/human-in-loop.md -- Confirmation patterns

Tool Types

Where does the tool execute?

├─ Backend (LLM calls API) → AI SDK tool()

│  └─ Want custom UI? → makeAssistantToolUI

└─ Frontend (browser-only) → makeAssistantTool

   └─ Want custom UI? → makeAssistantToolUI

Backend Tool with UI

// Backend (app/api/chat/route.ts)

import { tool, stepCountIs } from "ai";

import { z } from "zod";

const tools = {

  get_weather: tool({

    description: "Get weather for a city",

    inputSchema: z.object({ city: z.string() }),

    execute: async ({ city }) => ({ temp: 22, city }),

  }),

};

const result = streamText({

  model: openai("gpt-4o"),

  messages,

  tools,

  stopWhen: stepCountIs(5),

});

// Frontend

import { makeAssistantToolUI } from "@assistant-ui/react";

const WeatherToolUI = makeAssistantToolUI({

  toolName: "get_weather",

  render: ({ args, result, status }) => {

    if (status === "running") return <div>Loading weather...</div>;

    return <div>{result?.city}: {result?.temp}°C</div>;

  },

});

// Register in app

<AssistantRuntimeProvider runtime={runtime}>

  <WeatherToolUI />

  <Thread />

</AssistantRuntimeProvider>

Frontend-Only Tool

import { makeAssistantTool } from "@assistant-ui/react";

import { z } from "zod";

const CopyTool = makeAssistantTool({

  toolName: "copy_to_clipboard",

  parameters: z.object({ text: z.string() }),

  execute: async ({ text }) => {

    await navigator.clipboard.writeText(text);

    return { success: true };

  },

});

<AssistantRuntimeProvider runtime={runtime}>

  <CopyTool />

  <Thread />

</AssistantRuntimeProvider>

API Reference

// makeAssistantToolUI props

interface ToolUIProps {

  toolCallId: string;

  toolName: string;

  args: Record<string, unknown>;

  argsText: string;

  result?: unknown;

  status: "running" | "complete" | "incomplete" | "requires-action";

  submitResult: (result: unknown) => void;  // For interactive tools

}

Human-in-the-Loop

const DeleteToolUI = makeAssistantToolUI({

  toolName: "delete_file",

  render: ({ args, status, submitResult }) => {

    if (status === "requires-action") {

      return (

        <div>

          <p>Delete {args.path}?</p>

          <button onClick={() => submitResult({ confirmed: true })}>Confirm</button>

          <button onClick={() => submitResult({ confirmed: false })}>Cancel</button>

        </div>

      );

    }

    return <div>File deleted</div>;

  },

});

Common Gotchas

Tool UI not rendering

• toolName must match exactly (case-sensitive)

• Register UI inside AssistantRuntimeProvider

Tool not being called

• Check tool description is clear

• Use stopWhen: stepCountIs(n) to allow multi-step

Result not showing

• Tool must return a value

• Check status === "complete" before accessing result