截至上篇,我们实现了类似于 2023 年 ChatGPT 那样的 AI 对话系统。 本文介绍 Agent 最重要的功能——工具调用能力。
在传统的 AI 对话系统种,AI 大模型只能根据预训练的数据,生成文本答案回答用户的问题;而 Agent 则功能更强,能拆解复杂任务、上网搜索、访问文件系统等等。 这些所有与外界系统的交互,都是通过工具调用来触发的。
工具调用的流程是这样:
可以看出,上面的 1、4 步骤都给大模型发送了消息,也就是说 Agent 有可能在用户的一次输入后与大模型完成多轮交互,这也是 “Agent 对话循环” 的含义。
工具调用的原生支持、参数格式等,大模型厂商已经提前规定好了;本文不赘述那些规定格式,因为我们使用 SDK,这些格式 SDK 会帮我们处理。
首先,想让大模型认识工具,需要用一段文字来介绍工具的作用、返回值; 如果工具支持传参,那么每个参数也需要一段文字来介绍,主要介绍参数的格式、作用。
这个过程,就是向 AI 注册工具。
举例:注册一个 “提供时区,获取当前时间” 的工具:
import 'server-only'
import { tool } from 'ai'
import dayjs from 'dayjs'
import utc from 'dayjs/plugin/utc'
import { z } from 'zod'
import 'dayjs/locale/zh-cn'
dayjs.extend(utc)
dayjs.locale('zh-cn')
const get_current_time_by_time_zone = tool({
// 工具的描述
description: '获取指定时区的当前时间。',
// 如果工具支持参数,此处定义参数的格式
inputSchema: z.object({
timeZone: z.int().min(-12).max(14)
.optional().default(8)
.describe('UTC 时区偏移小时数,仅支持数字,例如 8、-8、0;不提供时默认为 8。'),
}),
// 工具自身的运行代码
execute: async ({ timeZone }) => {
return { formatted: dayjs().utcOffset(timeZone).format('YYYY年M月D日 dddd HH:mm:ss') }
},
})工具的名称必须使用 snake_case,也就是下划线分隔形式;如果使用驼峰式命名,SDK 会自动转化。 此处建议在代码中保持正确的命名方式,避免出现不一致的情况。
通过代码示例可以看出,其中:
description 是最重要的字段之一,它是工具的完整介绍;inputSchema;
SDK 预期用户使用 zod 来定义参数的校验和描述,这里需要为每个字段定义校验规则、报错信息和描述,其中最重要的就是 .describe() 定义的描述文字;execute 就是工具实际执行代码了,AI 输入参数后,就会运行这个函数并使用它的返回值。注册好工具后,我们要把工具传递给大模型。
更新后端代码:
import 'server-only'
import { convertToModelMessages, streamText, type UIMessage } from 'ai'
import { mainModel } from '@/lib/agent/models'
export async function POST(request: Request) {
const { messages } = (await request.json()) as { messages: UIMessage[] }
const modelMessage = await convertToModelMessages(messages)
const result = streamText({
model: mainModel,
messages: modelMessage,
tools: { get_current_time_by_time_zone },
})
return result.toUIMessageStreamResponse()
}这里,使用 tools 字段把工具列表注册给大模型。
工具调用规范中明确了工具名只能使用 snake_case 格式,也就是下划线分隔单词;AI SDK 内部会自动转换工具名,但仍建议显式声明工具名为 snake_case。
接下来,更新前端组件。
Vercel AI SDK 支持多种消息,普通文本是一种类型,工具调用则有一种专门的类型来区分出来;因此,我们需要通过代码分支判断决定渲染何种组件。
而且,消息中可能包含多个部分,因为 Vercel AI SDK 返回的结果中,一条消息中可能包含多次工具调用,这是允许的行为;这部分内容也要用循环的方式依次渲染。
更新后的前端代码如下:
渲染组件如下:
你好,我是一个支持全世界不同时区的报时机器人!
我已提供了默认的问题 “美国现在的时间是?”,可以尝试一下点击发送。
你可能发现问题了:AI 先说出 “我帮你查查” 之后,发起了工具调用,但最后不会继续输出内容了,只有工具调用的过程,却没有最终回答!
这是因为:Vercel AI SDK 默认是以 “一问一答” 的模式运行,问指的是用户的输入;答指的是把问题发送给 AI 大模型供应商。 也就是说:每次用户输入,默认只能给大模型提交一次消息。
我们的流程是: 用户询问 AI:“美国现在的时间是?” → AI 回答:“我帮你查查”,并发起工具调用,经过工具执行拿到工具调用的结果。
这并不能完成需求,接下来还要: 把之前的对话和工具调用结果继续发给 AI → AI 回答:“根据工具结果,告诉你美国的时间……”。
这期间,需要给 AI 大模型提供商发送两次消息。
接下来,介绍一种并非最完善的前端解决方式。
这种方式是,只要前端检测到最末尾的消息是工具调用,则表明缺少一个让 AI 最终回答的步骤,此时,应该自动续发消息,让 AI 继续。
Vercel AI SDK 的客户端部分,提供了 sendAutomaticallyWhen 这个参数,它让 SDK 在满足特定条件时自动发送;同时还提供了 lastAssistantMessageIsCompleteWithToolCalls 这个参数,它表示 “最后一条 AI 返回的消息是工具调用”。
这两者组合使用,便可避免 “工具调用出现在消息最末尾” 这种情况。
更新前端代码:
import { lastAssistantMessageIsCompleteWithToolCalls } from 'ai'
const { error, messages, sendMessage, status, stop } = useChat<UIMessage>({
messages: chatHistory,
transport,
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
})添加了这一行之后,只要前端检测到末尾消息是 AI 的工具调用,便会自动续发。
更新后的组件如下:
你好,我是一个支持全世界不同时区的报时机器人!
点击按钮发送消息,可以看出,工具调用后 AI 会继续回答问题,我们似乎解决了问题。
这种解决方式,只是单纯的 “前端续发” 方案,它更多适用于后端异常中断时的恢复措施; 我们希望解决办法是,尽可能从根源来解决。
其实,Vercel AI SDK 已经提供了配置方式。这里先直接给出后端代码:
import { convertToModelMessages, stepCountIs, streamText, tool, type UIMessage } from 'ai'
export async function POST(request: Request) {
const { messages } = (await request.json()) as { messages: UIMessage[] }
const modelMessage = await convertToModelMessages(messages)
const result = streamText({
model: mainModel,
messages: modelMessage,
tools: { get_current_time_by_time_zone },
stopWhen: stepCountIs(5),
})
return result.toUIMessageStreamResponse()
}注意高亮行,这里我们使用 stopWhen: stepCountIs(5) 向 SDK 传递了要求:现在允许 “一问五答”。 这样,即使触发了工具调用,消耗掉了一个步骤,还剩余好几个步骤可以让 AI 总结文字返回给用户。
这才是根本性的解决方式。
更新后端代码并接入,新组件如下:
你好,我是一个支持全世界不同时区的报时机器人!
新的组件同样可以正常在工具调用后输出最终回答。
也可以写成 stopWhen: stepCountIs(2),但这样会遇到一些问题:有时,AI 会在发起一轮工具调用后,返回文字:“考虑到美国有夏令时,我再次以夏令时的时区偏移查询一遍”,然后开始第二轮工具调用,此时 stepCountIs(2) 就不够用了,会导致这轮工具调用后 AI 无法总结回答。
实际开发中,Agent 可能还会执行更多的步骤,因此 stopWhen: stepCountIs(5) 的值会调的比较大,例如 50;前端方面,也会开启 sendAutomaticallyWhen,通过前后端同时采取措施,避免工具调用作为最后一条消息的情况。
上文中,使用的 “获取时间” 工具是服务端执行一个函数,把 AI 的输入转化为函数运行的结果并放回对话历史中,让 AI 根据它来继续生成文字。 这种方式,我们称之为 “服务端工具调用”。
接下来尝试开发 “客户端工具”,在前端渲染一些 UI 组件,让用户与之产生交互。
在用户使用 AI 工具时,有时对需求的描述可能不够清晰,因此,我们希望 AI 可以在适当的时机弹出表单,让用户进一步选择明确自己的需求;这个表单将尽可能减少交互复杂度,以选择为主,但也提供输入框允许用户自行输入。
我们给这个工具取名为 ask_user_question。
首先,在后端 SDK 处注册这个工具:
import 'server-only'
import { convertToModelMessages, stepCountIs, streamText, tool, type UIMessage } from 'ai'
import { z } from 'zod'
import { mainModel } from '@/lib/agent/models'
const askUserQuestion = tool({
description:
'当用户的需求不够明确,无法可靠地继续处理时,向用户确认需求。优先提供 2 到 4 个简短、互斥、容易选择的选项;如仍需要更多细节,可允许用户补充文本。',
inputSchema: z.object({
question: z.string().describe('需要向用户确认的问题。问题应简短具体,一次只确认一个关键点。'),
options: z
.array(
z.object({
label: z.string().describe('选项名称 Key,尽量简短。'),
description: z.string().optional().describe('选中此项代表的含义或影响。'),
})
)
.min(2)
.max(4)
.describe('给用户选择的候选项,优先覆盖最可能的需求方向。'),
allowCustomText: z
.boolean()
.optional()
.default(true)
.describe('是否允许用户手动输入补充说明;默认允许。'),
customTextPlaceholder: z
.string()
.optional()
.default('也可以补充你的具体想法...')
.describe('补充文本输入框的占位文案。'),
}),
})
export async function POST(request: Request) {
const { messages } = (await request.json()) as { messages: UIMessage[] }
const modelMessage = await convertToModelMessages(messages)
const result = streamText({
model: mainModel,
messages: modelMessage,
tools: { askUserQuestion },
stopWhen: stepCountIs(10),
})
return result.toUIMessageStreamResponse()
}因为这是一个给前端用户使用的组件,它不需要执行代码,所以它没有 execute。
然后,在前端为这个工具创建 UI 界面; 这是一个由按钮和输入框组成的表单,允许用户选择某一项,或者对选项都不满意时直接在输入框输入文本并提交。
代码如下:
这样这个请求用户详细描述问题的表单组件就完成了,我们把它接入 AI 对话流程中。
更新工具调用,针对消息的类型进行判断,如果发现是这个客户端工具调用,则渲染这个组件:
Vercel AI SDK 的核心 hook useChat() 返回了 addToolOutput 这个函数,它是专为客户端工具调用场景设计,在与用户交互时回传工具调用的结果。
对于服务端工具,大模型 “请求工具调用” 后,SDK 会先校验参数是否正确,然后把参数传入 execute,获取运行结果,将结果重新发给大模型,这个过程中不涉及用户交互;
对于客户端工具,大模型 “请求工具调用” 后,SDK 会先校验参数是否正确,然后把包含最末尾是 “请求工具调用” 的消息传给前端,我们需要针对这种工具调用开发对应的组件,将大模型回传的参数渲染为组件,等待用户的交互,用户交互后,使用 addToolOutput() 把工具调用的结果放入消息序列并重新发给大模型。
更新代码后,渲染出的组件如下:
你好,我是你的 AI 助理。
可以直接点击发送按钮,使用我预设的问题,体会客户端工具调用的效果。
留言