从零解剖一个 AI Agent Tool怎么实现的

一、先讲一个故事：模型为什么需要 Tool？

使用者痛点：大语言模型拥有强大的推理能力。却缺乏读取文件、调用 API 等实际操作的能力，导致它只能给出空洞的答案。

想象一下你雇了一位世界顶级的代码审查专家。怎么说呢，他智商爆表，精通所有编程语言。能在毫秒间分析算法复杂度——但他双目失明，双手被绑在身后。

你递给他一个项目说：“帮我看看 tool-file-read.mjs 这个文件有没有 bug。”

专家会非常礼貌地告诉你：“我很乐意帮忙，但我看不到文件。”

这就是大语言模型的处境。它拥有惊人的推理能力，却被关在一个黑盒子里——没有眼睛看文件程序。没有手去输入命令，没有嘴巴去调用 API。

Tool就是给模型装上眼睛和双手。

二、全局架构：一张图看懂整个流程

使用者痛点：传统的 LLM 调用方式需要手动拼接提示词、解析返回结果，过程繁琐且易出错。下面的架构把这些细节抽象为循环，让开发者专注于业务逻辑。

使用者提问 │ ▼
┌─────────────────────────────────────────────────┐
│ messages 数组 │
│ │
└─────────────────────────────────────────────────┘
│ ▼
┌─────────────────────────────────────────────────┐
│ modelWithTools.invoke │
│ 模型分析：我需要读取文件 → 返回 tool_calls │
└─────────────────────────────────────────────────┘
│ ▼ response.tool_calls 有内容吗？│
│ 有 没有 → 输出最终答案，结束
▼
┌─────────────────────────────────────────────────┐
│ 遍历每个 tool_call，找到对应 Tool，执行 invoke│
│ 收集所有 toolResults │
└─────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────┐
│ 将 toolResults 包装成 ToolMessage。push 进 messages│
└─────────────────────────────────────────────────┘
▼
调用 modelWithTools.invoke ←── 循环

这个循环就是 Agent 的主要——模型思考 → 调用工具 → 获取结果 → 再思考直到它认为不需要再调用工具了。

三、第一步先：创建一个“有手”的模型

const model = new ChatOpenAI({
modelName: process.env.MODEL_NAME。apiKey: process.env.OPENAI_API_KEY,configuration: {
baseURL: process.env.OPENAI_BASE_URL
},temperature: 0,});

到这一步，model 只是一个普通的 LLM 实例。它能聊天但不能做任何事. 它的 .invoke 返回的 response 只有文字，没有 tool_calls.

关键改变：

const modelWithTools = model.bindTools;老实说，

.bindTools 向模型声明了一份“能力清单”。话说回来，LangChain 会把每个工具的名称、描述、参数 schema 一并发送给模型。使其知道可以调用哪些外部功能。

User Pain Point：Lack of a unified way to expose external capabilities makes integration error‑prone. .bindTools solves this by standardizing interface.

四、接下来：定义一个 Tool —— 麻雀虽小，五脏俱全

This section is heart of implementation.

const readFileTool = tool(
// 第一个参数：处理函数
async => {
const content = await fs.readFile;console.log 成功读取 ${content.length} 字节`);return content;},// 第二个参数：元数据配置
{
name这方面。'read_file',description: `用此工具来读取文件内容。当使用者需要读取文件、查看代码、分析文件内容时调用此工具。输入文件方法`,schema: z.object({
再看path。z.string.describe
})
}
);

处理函数 —— Tool 的“肉体”

async => {
const content = await fs.readFile;return content;}

The function performs actual I/O operation. It is asynchronous because file reading is non‑blocking.

Name —— Tool 的“身份证”

说到name，'read_file'。

• 发送给模型：A name tells LLM which tool it can invoke.
• .tool_call.name: Identifies which tool was requested.
• The runtime matches this name with corresponding object.

Description —— Tool 的“使用说明书”

description: `用此工具来读取文件内容。当使用者需要读取文件、查看代码、分析文件内容时调用此工具。...`,

This natural‑language description is how model decides *when* and *wher* to call tool. A well‑crafted description dramatically reduces hallucination and misuse.

Sche​ma —— Tool 的“合同条款”

schema的观点是。z.object({
path这方面，z.string.describe
})

五、然后：Agent 循环 —— 模型和工具的交谊舞

再看初始化，搭建“对话舞台”

const messages =;"

User Pain Point: 手动维护对话历史容易出错；如果忘记把上一次的 tool result 加回 messages，后续推理会缺失关键上下文。**消息结构**



类型
用途




SystemMessage
设置角色与规则


HumanMessage
使用者真实需求


ToolMessage
工具执行后的返回值




至于第一次调用，模型决定 “我需要工具” 
js
let response = await modelWithTools.invoke;
messages.push;


模型收到 System + Human 后识别出「读文件」需求。

因为已经绑定了 `read_file`，它返回 **tool_calls** 而不是直接答复。怎么说呢，

将这条带有 `tool_calls` 的回复也 push 到历史中。以保证完整性，

json
{
"tool_calls":
}

再看执行循环，把模型的「意图」变成「行动」
js
while {
// 并行执行所有 tool 调用
const toolResults = await Promise.all(
response.tool_calls.map => {
const tool = tools.find;if {
return `错误，找不到工具 ${toolCall.name}`;}
try {
const result = await tool.invoke;return result;} catch {
return `错误: ${e.message}`;}
})
)，
// 把每个结果包装成 ToolMessage 并加入对话
response.tool_calls.forEach => {
messages.push(new ToolMessage({
content: toolResults。tool_call_id: tc.id,}));})，//
让模型基于新信息思考
response = await modelWithTools.invoke;

}


第一层判断 — 循环油门/刹车


有 tool_calls → 继续 

无 tool_calls → 停止


第二层并行 — 效率翻倍

一次请求可能返回多个 read_file 调用，例如批量检查多个源码文件。

第三层路由 — 策略模式实现

把 LLM 返回的字符串名字映射到真实执行函数。

第四层包装 — 粘合剂

json
{
至于"role"，"tool","content": "... 文件内容 ..."。"tool_call_id": "call_abc123"
}


tool_call_id 确保 哪个结果对应哪个请求尤其在并行场景下很关键。

说到循环终止。输出最终答案

当 LLM
思考后不再产生 tool_calls 时它直接返回文本答案，即为我们想要的代码解释或分析结果。


六、完整时序图：一次调用的「生命历程」 

ascii
时间 ─► HumanMessage ─► 模型思考 ─► tool_calls:
│ ▼
│ Tool.invoke
│ ▼
│ ToolMessage
│ ▼
└──────► 模型再思考 ─► 最终答案



七、：设计背后的精妙之处 

关注点分离 


角色 
职责 



模型 
理解意图；决定是否使用哪个工具还有传参方式。

Tool 定义 
声明「我能做什么」还有所需参数。

Tool 执行 
实际完成 I/O 操作。

循环控制器 
负责把意图转化为动作。再把结果喂回模型，实现闭环。






可
性 – 增加新功能只需在 tools 数组里添加定义，无需改动主要循环。

解耦合 – 每层职责单一，让团队可以分别负责 Prompt Engineering、业务 I/O 与调度逻辑。


Tool 本质是 I/O 边界的 

mermaid
graph LR;subgraph 推理世界
A --> B;end

subgraph 现实世界
C --> D;end

B --> C;D --> A，怎么说呢，

Model ↔︎ Tools ↔︎ Reality – Tools bridge closed reasoning loop with open real‑world actions.

错误处理的艺术 

js
if {
return `错误。找不到工具 ${toolCall.name}`;}



Instead of throwing exceptions that crash service,errors are turned into ToolMessages so LLM can react gracefully—e.g.。ask user for clarification or switch strategy.


Similarly:

js
try {
const result = await tool.invoke;return result;} catch {
return `错误: ${e.message}`;}



Errors become part of conversation,enabling self‑correction without manual intervention.



八、实战小结 & 常见痛点速查表 



痛点1：L​LM 无法直接访问本地资源 → 方法通过 bindTools 暴露统一接口。

痛点2：I/O 操作散落在业务代码中导致难以维护 → 方法将每个 I/O 抽象为独立 tool 对象。

痛点3：L​LM 返回结构化数据不可靠 → 方法使用 Zod Schema 强制参数类型与语义。

痛点4：Cascade 错误导致服务崩溃 → 方法将异常包装为文本返回，让 LLM 自己决定接下来动作。

痛点5：Coding 多线程/并发时难以同步结果 → 方法利用 Promise.all 并行执行，并通过 tool_call_id 保证对应关系。





掌握上述架构。你就能从「只能聊天」升级到「会读写会调接口」的大型 AI Agent，实现真正意义上的智能助理或自动化机器人。