Initial commit
This commit is contained in:
Zhongwei Li
292
docs/components/tool.md
Normal file
292
docs/components/tool.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# 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">',
|
||||
},
|
||||
}}
|
||||
/>
|
||||
Reference in New Issue
Block a user