Toolkits

A Toolkit is a named map of model-facing tool definitions. The Tools resource installs a toolkit into an assistant subtree, registering each tool with the model context and each render component with the tool-call renderer scope.

Use these APIs when you want a tool's availability to follow your runtime or provider tree. The older component-scoped registration APIs are deprecated; see Migrating Tools to Toolkits.

API Reference

tool

Defines a model tool with its argument schema, execution behavior, and optional model-output conversion.

This helper keeps reusable tool definitions type-checked and convenient to export for a Toolkit registered with Tools. When parameters is a Standard Schema (for example Zod v4), its input type is inferred for execute, streamCall, and model-output callbacks. Plain JSON Schema objects do not carry TypeScript input types, so provide generic arguments or annotate callbacks when you need precise args for JSON Schema.

import { z } from "zod";

const getWeather = tool({
  type: "frontend",
  description: "Get the weather for a city.",
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => `Sunny in ${city}`,
});

ToolDefinition

Tool definition accepted by the React tool registry.

Extends the core tool contract with tool-call display options. Human tools rely on render to collect input from the user. Frontend tools execute in the browser and require either render or renderText for their progress and result. Backend tools execute server-side and may omit a renderer.

Toolkit

Named collection of tools exposed to the assistant model.

Keys are the tool names the model receives and uses in tool calls.

const toolkit = defineToolkit({
  get_weather: {
    type: "frontend",
    description: "Get the weather for a city.",
    parameters: weatherSchema,
    execute: async ({ city }: { city: string }) => fetchWeather(city),
    render: WeatherToolUI,
  },
});

type Toolkit = Record<string, ToolDefinition<any, any>>;

Tools

defineMcpToolkit

Defines MCP server tools as a spreadable toolkit fragment. Pass a raw McpServerConfig for always-on servers, or { server, disabled, tools } when a server should stay configured but not expose all tools for the current request.

defineToolkit

Toolkit authoring helper. Accepts the permissive ToolkitDefinition (a generative backend tool may carry its server execute) and types the result as the canonical Toolkit.

In a "use generative" file, the compiler strips the wrapper per build so it can split schemas, renderers, and executors across the client/server boundary. Outside generative compilation, it returns the toolkit unchanged and can be used for plain frontend/backend/human toolkit objects.

externalTool

Marks a generative toolkit entry as an externally executed backend tool.

Use this when another system (for example a backend route or LangGraph node) already defines and executes the tool, but assistant-ui should render its tool calls. The use-generative compiler omits execute: externalTool() entries from the server build and keeps a type: "backend" renderer on the client build.

function externalTool(): never;

humanTool

Marks a tool as human-in-the-loop: the agent pauses and the UI (render) supplies the result instead of code. Use it as the tool's execute:

confirm: { execute: humanTool(), render: (props) => <Confirm {...props} /> }

Unlike defineToolkit, it has no runtime implementation: a "use generative" compiler (e.g. @assistant-ui/next or @assistant-ui/vite) detects execute: humanTool(), drops it, and stamps the tool type: "human". Reaching it at runtime means the module wasn't compiled (used outside a "use generative" file), so it throws.

function humanTool(): never;

providerTool

Marks a tool as provider-executed. The use-generative compiler converts execute: providerTool(...) into a type: "provider" tool entry.

stubTool

Marks a generative toolkit entry as a frontend tool whose executor will be supplied by useAuiToolOverrides(...).

stubTool() has no runtime implementation. It must be used inside a "use generative" toolkit file so the compiler can strip it.

function stubTool(): never;

hitl

const hitl: typeof humanTool;

hitlTool

const hitlTool: typeof humanTool;