如何扩展 chatbot-template:添加自定义 Tool 与 Part 组件完整步骤
如何扩展 chatbot-template:添加自定义 Tool 与 Part 组件完整步骤
chatbot-template 是一个基于 Next.js + Vercel AI SDK + shadcn/ui 构建的极简 AI 聊天机器人模板,运行在 Vercel AI Gateway 上。本文带你走通扩展聊天机器人的完整流程:从定义自定义 Tool、注册到工具集,到创建配套的 Part 组件并接入消息渲染,一个示例讲清全部步骤。
先认识模板:为什么扩展只需改两个地方
模板内置了三个现成的 Tool 可以当"参考样板":
| Tool | 定义文件 | 说明 |
|---|---|---|
github_repo |
tools/github_repo.ts | 服务端执行,查询 GitHub 仓库数据 |
web_search |
tools/web_search.ts | 各模型提供商的原生联网搜索 |
ask_user |
tools/ask_user.ts | 交互式问卷,由用户在界面中作答 |
要给它加新能力(比如查天气、查汇率、连内部 API),只需要动两处:
- Tool(工具):模型"会做什么"——在服务端定义能力,模型调用后返回结果。
- Part(部件):消息"长什么样"——把工具的输入/输出渲染成界面上的一块内容。
一条助手消息是由若干有类型的 Part 组成的列表。app/api/chat/route.ts 用 streamText 流式返回响应,components/chat-message.tsx 则对每个 part.type 做 switch 分发,把每种 Tool Part 交给 components/parts/ 目录下对应的组件渲染。
理解关键机制:Tool 状态流转与类型推导
Tool Part 在流式输出过程中会经历如下状态,这是写 Part 组件时的核心依据:
input-streaming → input-available → output-available(或 output-error)
以 components/parts/github-repo-part.tsx 为例:前两个状态显示"正在查询…"的加载动画,output-available 渲染 stars/forks 统计,output-error 显示错误信息。
更省心的是类型推导:消息类型由工具定义通过 AI SDK 的 InferUITools 自动推断,所以在 Part 组件里 part.input 和 part.output 都是完整类型化的——改错一个字段名,构建会直接报错,而不是运行时悄悄出现 undefined。
第 1 步:在 tools/ 下创建 Tool 定义文件
新建 tools/get_weather.ts。注意:文件名就是模型识别到的工具名,推荐用下划线命名(如 get_weather、github_repo)。文件内导出一个 tool() 调用,包含三部分:
import { tool } from "ai"
import { z } from "zod"
export const getWeather = tool({
description: "Get the current weather for a city.",
inputSchema: z.object({
city: z.string().describe("The city name"),
}),
outputSchema: z.object({
temperature: z.number(),
condition: z.string(),
}),
execute: ({ city }) => {
// 调用你的天气 API,这里只是示意
return { temperature: 25, condition: "Sunny" }
},
})
description:写给模型看的"说明书",决定模型何时调用它,建议写清楚触发场景。inputSchema/outputSchema:用 zod 描述输入输出结构。execute:服务端执行逻辑。💡 如果是"由用户在界面中作答"的交互型工具(如ask_user),可以省略execute,后面进阶部分会讲。
第 2 步:在 tools/index.ts 注册工具
打开 tools/index.ts,把新工具加进 baseTools 并导入即可:
import { getWeather } from "./get_weather"
const baseTools = {
github_repo: githubRepo,
ask_user: askUser,
get_weather: getWeather, // ← 新增
}
baseTools 会被 getTools() 取出并传入聊天路由的 streamText,模型从此就能调用它了。同时,ChatUIMessage 类型基于 InferUITools<typeof baseTools> 自动推导,新工具的 part.input / part.output 类型也随之就绪。
第 3 步:创建配套的 Part 组件
在 components/parts/ 新建 get-weather-part.tsx,按 part.state 分支渲染不同阶段:
import { type ChatMessagePart } from "@/tools"
import { Spinner } from "@/components/ui/spinner"
type GetWeatherToolPart = Extract<
ChatMessagePart,
{ type: "tool-get_weather" }
>
export function GetWeatherPart({ part }: { part: GetWeatherToolPart }) {
switch (part.state) {
case "input-streaming":
case "input-available":
return (
<div className="flex items-center gap-2 text-sm">
<Spinner /> Looking up weather…
</div>
)
case "output-available":
return <div>🌤 {part.output.temperature}°C, {part.output.condition}</div>
case "output-error":
return <div className="text-destructive">{part.errorText}</div>
default:
return null
}
}
类型 GetWeatherToolPart 从 ChatMessagePart 中用 Extract 精确挑出来(写法与 tools/index.ts 中 GithubRepoToolPart、AskUserToolPart 完全一致),保证只接收自己那种 Part。
第 4 步:在 chat-message.tsx 中接入渲染
最后一步,打开 components/chat-message.tsx,在 switch 中新增一个 case:
case "tool-get_weather":
return <GetWeatherPart key={part.toolCallId} part={part} />
到这里,pnpm dev 跑起来后,只要对话中模型判断需要查天气,界面就会先显示加载动画,再显示天气结果——完整的 Tool + Part 扩展就完成了。✅
进阶:交互型 Tool(ask_user 模式)
如果工具的结果不来自服务端,而来自用户本人(例如问卷、审批、表单确认),可以省略 execute,参考 tools/ask_user.ts。此时流程变为:
- 模型调用
ask_user并传入问题列表; - components/chat.tsx 检测到最后一条消息存在待回答的
tool-ask_userPart,就在滚动区底部钉住一个 components/question-card.tsx 问卷卡片; - 用户作答后,客户端调用
addToolOutput把答案作为工具输出回传,sendAutomaticallyWhen配置会自动续流,模型继续生成回复。
这个"服务端执行"与"客户端作答"两种模式,覆盖了绝大多数自定义 Tool 场景。
新手常见问题 FAQ
Q1:Tool 的字段类型在 Part 里是 undefined,为什么?
确认该工具已经加进 tools/index.ts 的 baseTools——类型是通过 InferUITools 从 baseTools 推导的,未注册的工具没有对应类型。
Q2:想给 Part 组件加按钮、抽屉等 UI,怎么装? 模板已内置 shadcn CLI,直接运行:
npx shadcn@latest add button
组件会落到 components/ui/,Spinner、Drawer、Item 等现成组件可直接复用。
Q3:想换模型或加模型,在哪改? 模型列表在 lib/models.ts,第一个条目是默认模型;聊天路由会用它校验请求,防止调用未授权的模型。
Q4:web_search 为什么不在 baseTools 里?
它由模型 ID 决定——tools/web_search.ts 根据前缀(openai/ 或 anthropic/)动态返回对应提供商的搜索工具,getTools() 会按需合并进工具集。这是"条件性工具"的参考写法。
小结
| 步骤 | 文件位置 | 做什么 |
|---|---|---|
| 1 | tools/<name>.ts |
定义 tool():description + schema + execute |
| 2 | tools/index.ts | 注册进 baseTools |
| 3 | components/parts/<name>-part.tsx |
按 part.state 渲染各阶段 UI |
| 4 | components/chat-message.tsx | 新增 case "tool-<name>" |
记住这条主线:文件名即工具名,注册后类型自动推导,状态驱动渲染。有了 github_repo 这个样板,加上任意能力都不过是四步小事——这就是 chatbot-template 作为扩展底座的魅力。