tools

assistant-ui Tools

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

A tool is a named capability the model can call. In assistant-ui you declare tools in a toolkit, a map whose keys are the tool names the model sees and whose values carry the schema, the executor, and the renderer. The supported authoring path is a "use generative" file compiled by a build plugin, which splits one file into a server build (schema plus backend executors) and a client build (schema plus renderers plus browser executors).

References

• ./references/toolkits.md -- authoring a toolkit end to end: kinds, renderers, toModelOutput, providerOptions, stubs, splitting and merging files, backendless
• ./references/tool-ui.md -- rendering states, useToolArgsStatus, deferred rendering, streaming args, ToolFallback and ToolGroup
• ./references/human-in-loop.md -- human tools, human() interrupts, and the full approval gate surface
• ./references/mcp-server.md -- server-side MCP servers and defineMcpToolkit
• ./references/mcp-apps.md -- rendering MCP App ui:// widgets with McpAppRenderer
• ./references/webmcp.md -- publishing frontend tools to the browser agent with unstable_useWebMcpProvider
• ./references/multi-agent.md -- sub-agent conversations inside a tool call
• ./references/legacy-component-apis.md -- the deprecated makeAssistantTool family and how to migrate off it

The authoring model

1. Add the build plugin

The directive does nothing without a compiler.

import { withAui } from "@assistant-ui/next";
 
export default withAui({
  /* your Next config */
});

Vite and TanStack Start add aui() from @assistant-ui/vite to plugins instead; Expo and bare React Native wrap the Metro config with withAui from @assistant-ui/metro. All three take an aui options object, documented in toolkits.md.

2. Write the toolkit

"use generative";
 
import { defineToolkit } from "@assistant-ui/react";
import { z } from "zod";
 
export default defineToolkit({
  get_weather: {
    description: "Get current weather for a location.",
    parameters: z.object({
      location: z.string().describe("City name or zip code"),
      unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
    }),
    execute: async ({ location, unit }) => {
      "use client";
      return fetchWeatherAPI(location, unit);
    },
    render: ({ args, result }) =>
      result ? (
        <div>
          {result.temperature} {args.unit}
        </div>
      ) : (
        <div>Fetching weather for {args.location}</div>
      ),
  },
});

3. Mount it on the client

"use client";
 
import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import toolkit from "./toolkit";
 
export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();
  const config = AuiConfig({ tools: Tools({ toolkit }) });
  return (
    <AssistantRuntimeProvider runtime={runtime} config={config}>
      {children}
    </AssistantRuntimeProvider>
  );
}

To scope a toolkit to part of the tree instead, wrap that subtree in <AuiProvider extends={aui} config={config}> with const aui = useAui(). useChatRuntime() targets /api/chat by default.

4. Expose it to the model

The same import resolves to the server build inside a route handler.

import { AISDKToolkit } from "@assistant-ui/ai-sdk";
import { streamText, convertToModelMessages } from "ai";
import { openai } from "@ai-sdk/openai";
import toolkit from "../../toolkit";
 
const aiToolkit = new AISDKToolkit({ toolkit });
 
export async function POST(req: Request) {
  const { messages, system, tools } = await req.json();
 
  const result = streamText({
    model: openai("gpt-5.6-luna"),
    system,
    messages: await convertToModelMessages(messages),
    tools: await aiToolkit.tools({ frontend: tools }),
  });
 
  return result.toUIMessageStreamResponse();
}

AISDKToolkit.tools() registers every toolkit tool with the model, wires the backend execute where the server build carries one, merges the frontend tools the client uploaded in the request body, and opens any MCP servers the toolkit spreads in. A server execute wins over an uploaded entry of the same name.

Tool kinds

The kind is inferred from execute and written back as type. You never author type in a "use generative" file.

The compiler enforces at build time that every tool declares an execute, that a frontend tool declares a render or renderText, and that a human tool declares a render. humanTool() and stubTool() have no runtime implementation and throw when reached, which means that file was never compiled; externalTool() is a compile-time marker in the same way.

Rendering a tool call

render receives the live call as ToolCallMessagePartProps.

For a one-line status instead of a component, set renderText with running and complete values, each a string or a function of ({ args, result }). Set display: "standalone" on the entry to keep the UI outside the collapsed tool group. Tools with no renderer fall back to the ToolFallback element.

Approval gates

Some runtimes pause on the server and emit an approval request the client must answer before the tool runs. The AI SDK v7 runtime emits one for every tool listed in the call-level toolApproval option.

import { useState } from "react";
import { defineToolkit, type ToolApprovalResponse } from "@assistant-ui/react";
 
const toolkit = defineToolkit({
  deploy: {
    type: "backend",
    render: ({ args, approval, respondToApproval, result }) => {
      const [error, setError] = useState<string | null>(null);
 
      const answer = async (response: ToolApprovalResponse) => {
        setError(null);
        try {
          await respondToApproval(response);
        } catch (failure) {
          setError(failure instanceof Error ? failure.message : String(failure));
        }
      };
 
      if (approval?.approved === undefined) {
        if (approval?.isAutomatic) return <p>Auto approved by policy</p>;
        return (
          <div>
            <p>Approve deploy to {args.target}?</p>
            <button onClick={() => void answer({ approved: true })}>Approve</button>
            <button onClick={() => void answer({ approved: false, reason: "user denied" })}>
              Deny
            </button>
            {error && <p role="alert">{error}</p>}
          </div>
        );
      }
 
      if (approval?.approved === false) {
        return <p>Denied{approval.reason ? `: ${approval.reason}` : ""}</p>;
      }
      return result === undefined ? <p>Approved, running</p> : <p>Deployed</p>;
    },
  },
});

approval.approved has three states. undefined means the gate is open and is the only state in which respondToApproval is legal. true means the decision was recorded as allow and the server is producing the result. false means it was recorded as deny; the runtime records an error result and exposes approval.reason. approval.isAutomatic is true when a server-side policy granted the decision rather than the user, so render a badge instead of buttons.

respondToApproval returns a promise that resolves once the runtime accepted the response and rejects when it could not be recorded, for example an expired gate or a refused answer. Await it before disabling the controls so a refused response leaves the request retryable. toolApprovalAcceptsText(approval) reports whether the request takes a free-form answer, on its own or alongside its options, so a renderer knows whether to offer a text field. The full option, question, and resolution surface is in human-in-loop.md.

Human tools

A human tool has no executor: the run pauses until the renderer supplies the result.

select_date: {
  description: "Ask the user to select a date.",
  parameters: z.object({ prompt: z.string() }),
  execute: humanTool(),
  render: ({ args, result, addResult }) => {
    if (result) return <p>Selected {result.date}</p>;
    return <DatePicker prompt={args.prompt} onChange={(date) => addResult({ date })} />;
  },
},

Call addResult exactly once. Use a human tool when the user supplies the tool result itself, and an approval gate when the backend owns the action and only needs permission.

Common Gotchas

humanTool() or stubTool() throws at runtime

• The file was not processed by the compiler. Add the build plugin and keep "use generative" as the file's first line.

A tool UI never renders

• The toolkit key must match the model-visible tool name exactly, including any MCP prefix.
• The toolkit must be mounted: const config = AuiConfig({ tools: Tools({ toolkit }) }) passed as config on the provider. Pass a stable toolkit from module scope or useMemo.

The model never learns about a frontend or human tool

• The client build skips uploading those schemas because it assumes your backend imported the same file's server build. With no backend of yours, compile with aui: { backendless: true }.

A frontend tool result never reaches the model

• Configure the runtime with sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls from ai, and lastAssistantMessageIsCompleteWithApprovalResponses for approval gates.

toModelOutput is ignored on round-tripped results

• Pass the tool registry to convertToModelMessages(messages, { tools }) as well as to streamText.

A build warning about tool names

• A duplicate name means two spread fragments define the same key and object spread keeps the later one; rename one entry. A tool that cannot be makeTool() came from an opaque factory call: write it as an inline object, or spread a compiler-visible defineToolkit(...) or defineMcpToolkit(...) fragment.

respondToApproval rejects

• It is legal only while approval.approved is undefined. A text answer to a request that declares neither display: "text" nor allowFreeform throws, as does an unknown optionId.

MCP connections pile up

• Keep the AISDKToolkit at module scope so clients pool across requests, and call aiToolkit.close() from onFinish.

Related Skills

• elements -- the styled ToolFallback and ToolGroup files and the rest of the catalog
• generative-ui -- UI the model composes from a vocabulary you ship
• react-mcp -- MCP servers the end user adds and authenticates in the browser
• runtime -- useChatRuntime and the AI SDK route the toolkit plugs into
• copilots -- interactables, the model-editable app state alternative to a stub tool
• update -- migrating older tool code to toolkits