293 lines
8.4 KiB
Markdown
293 lines
8.4 KiB
Markdown
# Tool
|
|
|
|
URL: /components/tool
|
|
|
|
---
|
|
|
|
title: Tool
|
|
description: A collapsible component for displaying tool invocation details in AI chatbot interfaces.
|
|
path: elements/components/tool
|
|
|
|
---
|
|
|
|
The `Tool` component displays a collapsible interface for showing/hiding tool details. It is designed to take the `ToolUIPart` type from the AI SDK and display it in a collapsible interface.
|
|
|
|
<Preview path="tool" />
|
|
|
|
## Installation
|
|
|
|
<ElementsInstaller path="tool" />
|
|
|
|
## Usage
|
|
|
|
```tsx
|
|
import { Tool, ToolContent, ToolHeader, ToolOutput, ToolInput } from "@/components/ai-elements/tool";
|
|
```
|
|
|
|
```tsx
|
|
<Tool>
|
|
<ToolHeader type="tool-call" state={"output-available" as const} />
|
|
<ToolContent>
|
|
<ToolInput input="Input to tool call" />
|
|
<ToolOutput errorText="Error" output="Output from tool call" />
|
|
</ToolContent>
|
|
</Tool>
|
|
```
|
|
|
|
## Usage in AI SDK
|
|
|
|
Build a simple stateful weather app that renders the last message in a tool using [`useChat`](/docs/reference/ai-sdk-ui/use-chat).
|
|
|
|
Add the following component to your frontend:
|
|
|
|
```tsx title="app/page.tsx"
|
|
"use client";
|
|
|
|
import { useChat } from "@ai-sdk/react";
|
|
import { DefaultChatTransport, type ToolUIPart } from "ai";
|
|
import { Button } from "@/components/ui/button";
|
|
import { Response } from "@/components/ai-elements/response";
|
|
import { Tool, ToolContent, ToolHeader, ToolInput, ToolOutput } from "@/components/ai-elements/tool";
|
|
|
|
type WeatherToolInput = {
|
|
location: string;
|
|
units: "celsius" | "fahrenheit";
|
|
};
|
|
|
|
type WeatherToolOutput = {
|
|
location: string;
|
|
temperature: string;
|
|
conditions: string;
|
|
humidity: string;
|
|
windSpeed: string;
|
|
lastUpdated: string;
|
|
};
|
|
|
|
type WeatherToolUIPart = ToolUIPart<{
|
|
fetch_weather_data: {
|
|
input: WeatherToolInput;
|
|
output: WeatherToolOutput;
|
|
};
|
|
}>;
|
|
|
|
const Example = () => {
|
|
const { messages, sendMessage, status } = useChat({
|
|
transport: new DefaultChatTransport({
|
|
api: "/api/weather",
|
|
}),
|
|
});
|
|
|
|
const handleWeatherClick = () => {
|
|
sendMessage({ text: "Get weather data for San Francisco in fahrenheit" });
|
|
};
|
|
|
|
const latestMessage = messages[messages.length - 1];
|
|
const weatherTool = latestMessage?.parts?.find((part) => part.type === "tool-fetch_weather_data") as WeatherToolUIPart | undefined;
|
|
|
|
return (
|
|
<div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]">
|
|
<div className="flex flex-col h-full">
|
|
<div className="space-y-4">
|
|
<Button onClick={handleWeatherClick} disabled={status !== "ready"}>
|
|
Get Weather for San Francisco
|
|
</Button>
|
|
|
|
{weatherTool && (
|
|
<Tool defaultOpen={true}>
|
|
<ToolHeader type="tool-fetch_weather_data" state={weatherTool.state} />
|
|
<ToolContent>
|
|
<ToolInput input={weatherTool.input} />
|
|
<ToolOutput
|
|
output={<Response>{formatWeatherResult(weatherTool.output)}</Response>}
|
|
errorText={weatherTool.errorText}
|
|
/>
|
|
</ToolContent>
|
|
</Tool>
|
|
)}
|
|
</div>
|
|
</div>
|
|
</div>
|
|
);
|
|
};
|
|
|
|
function formatWeatherResult(result: WeatherToolOutput): string {
|
|
return `**Weather for ${result.location}**
|
|
|
|
**Temperature:** ${result.temperature}
|
|
**Conditions:** ${result.conditions}
|
|
**Humidity:** ${result.humidity}
|
|
**Wind Speed:** ${result.windSpeed}
|
|
|
|
*Last updated: ${result.lastUpdated}*`;
|
|
}
|
|
|
|
export default Example;
|
|
```
|
|
|
|
Add the following route to your backend:
|
|
|
|
```ts title="app/api/weather/route.tsx"
|
|
import { streamText, UIMessage, convertToModelMessages } from "ai";
|
|
import { z } from "zod";
|
|
|
|
// Allow streaming responses up to 30 seconds
|
|
export const maxDuration = 30;
|
|
|
|
export async function POST(req: Request) {
|
|
const { messages }: { messages: UIMessage[] } = await req.json();
|
|
|
|
const result = streamText({
|
|
model: "openai/gpt-4o",
|
|
messages: convertToModelMessages(messages),
|
|
tools: {
|
|
fetch_weather_data: {
|
|
description: "Fetch weather information for a specific location",
|
|
parameters: z.object({
|
|
location: z.string().describe("The city or location to get weather for"),
|
|
units: z.enum(["celsius", "fahrenheit"]).default("celsius").describe("Temperature units"),
|
|
}),
|
|
inputSchema: z.object({
|
|
location: z.string(),
|
|
units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
|
|
}),
|
|
execute: async ({ location, units }) => {
|
|
await new Promise((resolve) => setTimeout(resolve, 1500));
|
|
|
|
const temp = units === "celsius" ? Math.floor(Math.random() * 35) + 5 : Math.floor(Math.random() * 63) + 41;
|
|
|
|
return {
|
|
location,
|
|
temperature: `${temp}°${units === "celsius" ? "C" : "F"}`,
|
|
conditions: "Sunny",
|
|
humidity: `12%`,
|
|
windSpeed: `35 ${units === "celsius" ? "km/h" : "mph"}`,
|
|
lastUpdated: new Date().toLocaleString(),
|
|
};
|
|
},
|
|
},
|
|
},
|
|
});
|
|
|
|
return result.toUIMessageStreamResponse();
|
|
}
|
|
```
|
|
|
|
## Features
|
|
|
|
- Collapsible interface for showing/hiding tool details
|
|
- Visual status indicators with icons and badges
|
|
- Support for multiple tool execution states (pending, running, completed, error)
|
|
- Formatted parameter display with JSON syntax highlighting
|
|
- Result and error handling with appropriate styling
|
|
- Composable structure for flexible layouts
|
|
- Accessible keyboard navigation and screen reader support
|
|
- Consistent styling that matches your design system
|
|
- Auto-opens completed tools by default for better UX
|
|
|
|
## Examples
|
|
|
|
### Input Streaming (Pending)
|
|
|
|
Shows a tool in its initial state while parameters are being processed.
|
|
|
|
<Preview path="tool-input-streaming" />
|
|
|
|
### Input Available (Running)
|
|
|
|
Shows a tool that's actively executing with its parameters.
|
|
|
|
<Preview path="tool-input-available" />
|
|
|
|
### Output Available (Completed)
|
|
|
|
Shows a completed tool with successful results. Opens by default to show the results. In this instance, the output is a JSON object, so we can use the `CodeBlock` component to display it.
|
|
|
|
<Preview path="tool-output-available" />
|
|
|
|
### Output Error
|
|
|
|
Shows a tool that encountered an error during execution. Opens by default to display the error.
|
|
|
|
<Preview path="tool-output-error" />
|
|
|
|
## Props
|
|
|
|
### `<Tool />`
|
|
|
|
<TypeTable
|
|
type={{
|
|
'...props': {
|
|
description: 'Any other props are spread to the root Collapsible component.',
|
|
type: 'React.ComponentProps<typeof Collapsible>',
|
|
},
|
|
}}
|
|
/>
|
|
|
|
### `<ToolHeader />`
|
|
|
|
<TypeTable
|
|
type={{
|
|
type: {
|
|
description: 'The type/name of the tool.',
|
|
type: 'ToolUIPart["type"]',
|
|
},
|
|
state: {
|
|
description: 'The current state of the tool (input-streaming, input-available, output-available, or output-error).',
|
|
type: 'ToolUIPart["state"]',
|
|
},
|
|
className: {
|
|
description: 'Additional CSS classes to apply to the header.',
|
|
type: 'string',
|
|
},
|
|
'...props': {
|
|
description: 'Any other props are spread to the CollapsibleTrigger.',
|
|
type: 'React.ComponentProps<typeof CollapsibleTrigger>',
|
|
},
|
|
}}
|
|
/>
|
|
|
|
### `<ToolContent />`
|
|
|
|
<TypeTable
|
|
type={{
|
|
'...props': {
|
|
description: 'Any other props are spread to the CollapsibleContent.',
|
|
type: 'React.ComponentProps<typeof CollapsibleContent>',
|
|
},
|
|
}}
|
|
/>
|
|
|
|
### `<ToolInput />`
|
|
|
|
<TypeTable
|
|
type={{
|
|
input: {
|
|
description: 'The input parameters passed to the tool, displayed as formatted JSON.',
|
|
type: 'ToolUIPart["input"]',
|
|
},
|
|
'...props': {
|
|
description: 'Any other props are spread to the underlying div.',
|
|
type: 'React.ComponentProps<"div">',
|
|
},
|
|
}}
|
|
/>
|
|
|
|
### `<ToolOutput />`
|
|
|
|
<TypeTable
|
|
type={{
|
|
output: {
|
|
description: 'The output/result of the tool execution.',
|
|
type: 'React.ReactNode',
|
|
},
|
|
errorText: {
|
|
description: 'An error message if the tool execution failed.',
|
|
type: 'ToolUIPart["errorText"]',
|
|
},
|
|
'...props': {
|
|
description: 'Any other props are spread to the underlying div.',
|
|
type: 'React.ComponentProps<"div">',
|
|
},
|
|
}}
|
|
/>
|