AI 电子伴侣

创建时间: 2026-03-29最后更新: 2026-08-04作者: yangbo

1. 用户一句话里，常常不止一个动作

前面几篇里，Agent 已经能做几件事：

接收消息
读取检索结果
结合上下文生成回复

但只靠聊天模型，它还是只能停在「回答」这一层。

比如用户说：

tool-scene.txt

1帮我查一下明天上海下不下雨，如果下雨就提醒我带伞。

这句话里其实有两个动作：

先查天气
如果下雨，再创建提醒

普通聊天模型能理解这句话，但它碰不到天气接口，也碰不到提醒系统。
Tool 就是补这层能力的。

Tool 在这里做的事很具体：

把一个外部能力暴露给模型
告诉模型这个能力叫什么
告诉模型这个能力要什么参数
当模型想调用它时，先返回一份结构化的调用请求

真正执行函数的，还是你的程序。

2. 先看一遍工具调用到底发生了什么

这一层最好先看清楚，再去用 Agent。

一次工具调用通常是这个顺序：

你先定义工具
把工具列表交给模型
用户发来消息
模型判断要不要调工具
如果要调，就返回 tool_calls
你的程序执行工具
再把工具结果交还给模型
模型生成最后的回复

后面用 createAgent(...) 时，Agent 只是把这套循环接管过去，不用你自己维护。

3. 先把工具定义出来

先从两个最小工具开始：查天气、建提醒。

companion-tools.ts

01import { tool } from 'langchain'
02import { z } from 'zod'
03
04// 这个工具只负责查天气。
05// 模型看到 description 和 schema 后，才知道什么时候该调它、该怎么传参。
06export const getWeather = tool(
07  async ({ city }) => {
08    const fakeWeatherMap: Record<string, string> = {
09      上海: '明天小雨，17-22 度',
10      北京: '明天晴，12-25 度',
11      深圳: '明天多云，26-30 度',
12    }
13
14    return fakeWeatherMap[city] ?? `${city}：暂无天气数据`
15  },
16  {
17    name: 'get_weather',
18    description: '查询某个城市未来的天气情况',
19    schema: z.object({
20      city: z.string().describe('要查询天气的城市名'),
21    }),
22  },
23)
24
25// 这个工具只负责创建提醒。
26// 返回对象没有问题，后面模型照样能继续读取字段内容。
27export const createReminder = tool(
28  async ({ content, time }) => {
29    return {
30      ok: true,
31      message: `提醒已创建：${time} - ${content}`,
32    }
33  },
34  {
35    name: 'create_reminder',
36    description: '帮用户创建一个提醒事项',
37    schema: z.object({
38      content: z.string().describe('提醒的具体内容'),
39      time: z.string().describe('提醒时间，例如 明天早上 8 点'),
40    }),
41  },
42)

这段代码里，真正决定模型能不能用对工具的，不是函数体有多复杂，而是后面这三项：

name
description
schema

尤其是 schema 里的 .describe()，不要省。
它不是写给人看的注释，而是给模型看的参数说明。

4. 先手动跑一遍，再看 Agent 接管

先看手动版，Tool Calling 的原理会更清楚。

这里故意用了 HumanMessage 这类消息对象。原因很简单：手动循环里会依次往同一个数组里塞进用户消息、模型消息和工具消息，用消息对象会更直观。

tool-loop.ts

01import { ChatOpenAI } from '@langchain/openai'
02import { HumanMessage } from '@langchain/core/messages'
03import { getWeather, createReminder } from './companion-tools'
04
05const tools = [getWeather, createReminder]
06const toolMap = new Map(tools.map(tool => [tool.name, tool]))
07
08const model = new ChatOpenAI({
09  model: 'gpt-4.1-mini',
10})
11
12// 这里只是把工具定义交给模型。
13// 到这一步为止，工具还没有被真正执行。
14const modelWithTools = model.bindTools(tools)
15
16const messages = [
17  new HumanMessage('帮我看看明天上海天气，如果下雨就提醒我带伞。'),
18]
19
20// 第一步：模型先决定要不要调工具。
21// 如果它觉得需要，会先返回 tool_calls。
22const aiMessage = await modelWithTools.invoke(messages)
23messages.push(aiMessage)
24
25// 第二步：你的程序根据 tool_calls 真正执行工具。
26for (const toolCall of aiMessage.tool_calls ?? []) {
27  const selectedTool = toolMap.get(toolCall.name)
28
29  if (!selectedTool) {
30    throw new Error(`未知工具：${toolCall.name}`)
31  }
32
33  // selectedTool.invoke(...) 会执行工具，并返回一个 ToolMessage。
34  // 这个 ToolMessage 里会带上 tool_call_id，模型后面靠它来对上这次调用。
35  const toolMessage = await selectedTool.invoke(toolCall)
36  messages.push(toolMessage)
37}
38
39// 第三步：把工具结果再交给模型。
40// 这一次拿到的，才是给用户看的最终回复。
41const finalResponse = await modelWithTools.invoke(messages)
42
43console.log(finalResponse.text)

这段代码里有两个很容易混掉的点：

bindTools() 只是把工具说明交给模型
真正执行工具的是 selectedTool.invoke(...)

也就是说，模型不会直接替你跑函数。
它只是先说一句：“我想调这个工具，请你帮我执行。”

接下来再看 Agent 版本。

agent-with-tools.ts

01import { createAgent } from 'langchain'
02import { getWeather, createReminder } from './companion-tools'
03
04const agent = createAgent({
05  model: 'openai:gpt-4.1-mini',
06  tools: [getWeather, createReminder],
07  systemPrompt: '你是用户的生活助理，能聊天，也能在必要时调用工具。',
08})
09
10const result = await agent.invoke({
11  messages: [
12    {
13      role: 'user',
14      content: '帮我看看明天上海天气，如果下雨就提醒我带伞。',
15    },
16  ],
17})
18
19// Agent 已经把前面的工具循环跑完了。
20// 这里直接读取最后一条消息，就是这一轮最终回复。
21console.log(result.messages.at(-1)?.text)

这两段代码做的是同一件事。

手动版：你自己维护「模型请求工具 -> 执行工具 -> 回传结果」这条循环
Agent 版：这条循环交给 createAgent(...)

文章放两段代码，是为了把边界看清楚。
平时写应用时，直接用 Agent 会省很多事。

5. 多个工具接到一个 Agent 里

放回 AI 伴侣场景里，工具通常不止两个。

再加一个查日程的工具，整条链就完整了：

multi-tools-agent.ts

01import { createAgent, tool } from 'langchain'
02import { z } from 'zod'
03
04const getWeather = tool(
05  async ({ city }) => {
06    const data: Record<string, string> = {
07      上海: '明天小雨，17-22 度',
08      北京: '明天晴，12-25 度',
09    }
10    return data[city] ?? `${city}：暂无数据`
11  },
12  {
13    name: 'get_weather',
14    description: '查询某个城市未来的天气情况',
15    schema: z.object({
16      city: z.string().describe('要查询天气的城市名'),
17    }),
18  },
19)
20
21const createReminder = tool(
22  async ({ content, time }) => {
23    return `提醒已创建：${time} - ${content}`
24  },
25  {
26    name: 'create_reminder',
27    description: '帮用户创建一个提醒事项',
28    schema: z.object({
29      content: z.string().describe('提醒的具体内容'),
30      time: z.string().describe('提醒时间，例如 明天早上 8 点'),
31    }),
32  },
33)
34
35const querySchedule = tool(
36  async ({ date }) => {
37    const schedules: Record<string, string> = {
38      明天: '10:00 产品评审会，14:00 和小李 1v1',
39      后天: '全天无日程',
40    }
41    return schedules[date] ?? `${date}：没有找到日程`
42  },
43  {
44    name: 'query_schedule',
45    description: '查询用户某一天的日程安排',
46    schema: z.object({
47      date: z.string().describe('要查询的日期，例如 今天、明天、后天'),
48    }),
49  },
50)
51
52const agent = createAgent({
53  model: 'openai:gpt-4.1-mini',
54  tools: [getWeather, createReminder, querySchedule],
55  systemPrompt: `
56你是用户的 AI 伴侣。
57当用户请求涉及天气、提醒和日程时，使用对应工具。
58如果用户只是在聊天，就直接回复，不要硬调工具。
59  `.trim(),
60})
61
62const result = await agent.invoke({
63  messages: [
64    {
65      role: 'user',
66      content: '明天上海天气怎么样？如果下雨，明早提醒我带伞。顺便看看我明天有什么安排。',
67    },
68  ],
69})
70
71console.log(result.messages.at(-1)?.text)

这类请求里，Agent 可能会连续做几件事：

先查天气
再判断要不要建提醒
还可能再去查日程

你在调用入口里只写了一次 agent.invoke(...)，中间怎么循环、要不要继续调下一个工具，已经交给 Agent。

6. 写工具时，几个地方最容易出错

描述写得太空

如果 description 只写「查询信息」「执行操作」，模型很难判断它什么时候该用这个工具。
描述里最好直接写清楚：

这个工具解决什么问题
用户说到什么场景时该调用
参数大概是什么含义

参数结构太宽

别把所有输入都塞成一个大字符串。

bad-tool-schema.ts

1schema: z.object({
2  input: z.string(),
3})

这种写法短期看着省事，后面最难排查。
如果你知道工具要 city、time、content 这几个字段，就直接拆出来。

以为绑定后就会自动执行

bindTools() 只负责把工具定义交给模型。
如果你没有用 Agent，就还得自己跑那条工具循环。

一个工具里塞太多事

像下面这种「万能工具」通常不好用：

assistant-action.ts

01const assistantAction = tool(
02  async ({ action, payload }) => {
03    // 根据 action 再去分发天气、提醒、日程等逻辑
04  },
05  {
06    name: 'assistant_action',
07    description: '处理所有外部动作',
08    schema: z.object({
09      action: z.string(),
10      payload: z.string(),
11    }),
12  },
13)

这样做会让模型更难选工具，也更难把参数填稳。
一般来说，一个工具只负责一类明确动作，会更好维护。

7. 记住这几件事

这一篇真正要记住的是这几件事：

Tool 是给模型看的「外部能力说明书」
模型返回 tool_calls，不等于工具已经执行
手动版里，要自己维护那条工具循环
Agent 版里，这条循环交给 createAgent(...)

这一篇和下一篇是接着的：

这一篇先把工具调用过程拆开
下一篇再看单个 Agent 怎么把多个工具接起来