ai-sdk/tools

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Tool execution can return JSON objects instead of text

Instead of returning text from a tool's execute function, you can return a JSON object that represents structured data. This JSON object can then be used to conditionally render a React component with the object as props.

ToolModelMessage type definition

ToolModelMessage has role 'tool' and content property of type ToolContent, which is an array of ToolResultPart. The Zod schema can be accessed via toolModelMessageSchema export.

ToolCallPart structure

ToolCallPart has type 'tool-call', toolCallId property (string used to match the tool call with tool result), toolName property (string name of the tool being called), and args property (JSON-serializable object matching the tool's input schema).

ToolResultPart structure

ToolResultPart has type 'tool-result', toolCallId property (string ID associated with the tool call), toolName property (string name of the tool), output property of type LanguageModelV4ToolResultOutput, and optional providerOptions property for provider-specific metadata passed through to the provider.

ToolResultOutput type variants

ToolResultOutput supports multiple types: 'text' with string value, 'json' with JSONValue, 'execution-denied' with optional reason string, 'error-text' with string value, 'error-json' with JSONValue, and 'content' with array of content items. All variants support optional providerOptions.

ToolResultOutput content array item types

ToolResultOutput content array items can be: type 'text' with text string property; deprecated type 'media' with data and mediaType; type 'file-data' with base64-encoded data string, IANA mediaType, optional filename; type 'file-url' with url string and optional mediaType; deprecated type 'file-id' with fileId string or Record<string,string>; type 'file-reference' with ProviderReference; deprecated types 'image-data', 'image-url', 'image-file-id', 'image-file-reference'; and type 'custom'. All support optional providerOptions.

Tool definition with tool() function

Tools are defined using the tool() function from the ai package. Each tool receives an object with description (string), inputSchema (a Zod schema), and optionally an execute function. The execute function is async and receives the parsed input. Client-side tools can omit the execute function if they require manual output handling.

InferUITools and UIMessage types for tools

The ai package exports InferUITools type that can infer a union of tool names from a ToolSet. UIMessage is a generic type that accepts type parameters for custom types, UIDataTypes, and ChatTools (the inferred tool union). This enables type-safe message handling with tool calls.

Client-side tool with user interaction pattern

Client-side tools that require user interaction (like confirmation dialogs) can be defined without an execute function. They render UI with buttons that call addToolOutput when clicked. The part.state property indicates whether output has been provided ('output-available') or is still pending.

Give your agent this brain