这是「近五年 AI 技术演进」系列深挖的第四篇。第一篇《从 ChatGPT 到 Agent Harness》铺开全景，第二篇拆了 RAG，第三篇讲了 Function Calling——模型第一次学会"填工单"。这一篇轮到工单指向的对象：Tool（工具）。一句话定位：模型可调用的任何外部能力。Function Calling 给了模型"表达调用意图"的能力，Tool 就是被调用的那些真实能力。模型本身只有一个"大脑"，Tool 是它伸出去的手脚——手脚长什么样、听不听使唤、会不会闯祸，决定了这个 Agent 是能干活的员工，还是只会画饼的领导。全文约 6000 字，建议收藏后按章节阅读。
一、定义：大脑与手脚
先给一个足够精确的定义：Tool 就是模型能调用的外部能力——一个函数、一个 HTTP API、一次数据库查询、一个搜索引擎、一段能写文件的脚本。它有三个特征：
第一，它不依赖模型存在。你的天气 API 在模型问世之前就能跑，把模型换掉它照样工作。Tool 是应用侧的资产，这一点和第三篇讲的"模型只输出意图、应用负责执行"一脉相承——模型是决策者，Tool 是执行者。
第二，它通过 Function Calling 协议被"点名"。模型在工具清单里看到工具的名字和描述，需要时输出一段结构化调用意图，应用拿到意图后去执行对应的 Tool。整个协作的接口契约，就是第三篇拆过的那套 8 步时序。
第三，它决定了模型的实际能力边界。这是最容易被低估的一点。模型参数里固化了多少知识、推理能力多强，决定的是"大脑"的上限；但用户感知到的 Agent 能力——能不能查到实时信息、能不能真把邮件发出去——完全由 Tool 决定。大脑再聪明，没有手脚就寸步难行。
一个类比贯穿全文：模型是坐在办公室里看监控屏幕的调度员，Tool 是车间里的设备。调度员看得到订单（用户请求）、背得出操作手册（训练知识），但他真正影响物理世界的唯一方式，就是操作那些设备。所以给 Agent 做系统，一半的功夫要花在"造设备"上——这就是本文的主角。
二、五类工具：给"手脚"画一张图谱
工具的形态五花八门，但按"对世界做什么"来划分，基本逃不出五类。每一类都配两个真实例子：
信息获取类——替模型看世界。模型的训练数据有截止日期，想知道"今天"的事必须靠它。典型例子：联网搜索（接到"最新款手机参数"的问题，调搜索引擎拿回十页结果）和网页抓取（用户丢来一个链接让"总结这篇公众号文章"，先抓 HTML 再喂给模型）。天气查询也属于这类。
数据查询类——替模型问系统。企业场景里最常用的一类，模型自己不知道你的库存和订单，必须问。典型例子：数据库查询（"查一下 SKU A103 的实时库存"，执行一条只读 SQL）和向量库检索（在十万条客服工单里语义搜出最相关的三条）。调用内部 REST API 查业务数据也归这类。
计算处理类——替模型算数。模型心算大数靠概率，乘错很正常，精确计算要外包。典型例子：代码执行沙箱（"这组销售数据算一下环比增长率"，跑一段 pandas）和数据分析工具（对表格做聚合、透视、统计检验）。连计算器都算——别小看它，让模型调计算器算 34817 × 293，准确率远高于让它自己心算。
行动执行类——替模型改变世界。前三类是"读"，这一类是"写"，风险也最高。典型例子：发邮件（"把周报发给全组"，真实调用邮件网关）和下单（订机票、提交采购单，操作的是真金白银）。写数据库、调第三方系统的写接口都在此列。
环境操作类——替模型操作工作台。Agent 运行所在的"工作环境"本身也是工具的靶子。典型例子：文件读写（把报告保存成 Markdown 文件、读取用户上传的 Excel）和浏览器操作（自动化测试场景里打开页面、点按钮、填表单）。控制本机设备、操作 IDE 也属于这类。
五类放在一起看：
| 类别 | 本质动作 | 典型例子 | 风险等级 | 设计关键 |
|---|---|---|---|---|
| 信息获取类 | 读外部世界 | 联网搜索、网页抓取 | 低 | 结果要截断、去噪，控制 token 成本 |
| 数据查询类 | 读内部系统 | 数据库查询、向量检索 | 低-中 | 强制只读、限制返回行数 |
| 计算处理类 | 纯计算 | 代码执行、计算器 | 中 | 隔离执行环境、限定资源 |
| 行动执行类 | 写外部世界 | 发邮件、下单 | 高 | 确认机制、幂等设计、审计日志 |
| 环境操作类 | 写工作环境 | 文件读写、浏览器操作 | 中-高 | 路径白名单、域名校验 |
这张图值得多看两眼：五类工具环绕着模型的"大脑"，读类工具（左半边）负责把世界的信息喂进来，写类工具（右半边）负责把决策落到世界上。一个能干活的 Agent，往往是五类工具各配几个，再靠模型在中间调度。比如一句"帮我统计上周的退货订单，写进周报发给运营组"——数据查询类查订单、计算处理类算统计、环境操作类写文件、行动执行类发邮件，四个动作串成一条链。
三、工具设计原则：本文最值钱的一节
工具人人会写，但好工具和差工具的差距，直接体现在 Agent 的任务成功率上。同一个模型，接上一套精心设计的工具，成功率能从六成拉到九成；接上一套烂工具，再强的模型也救不回来。下面五条原则，每一条都是真金白银换来的。
原则一：粒度——切工具像切函数
粒度是工具设计里最纠结的决定：切多细合适？
切太细的问题：模型要为一件小事调很多次。比如把"订机票"拆成search_flights、get_flight_detail、check_price、create_order、add_passenger五个工具，模型完成一次订票要连调五轮，每一轮都有出错概率，五轮乘下来成功率断崖式下跌——这在第三篇讲过，多轮循环的每一圈都是风险敞口。
切太粗的问题：不灵活，参数爆炸。反过来把所有查询揉成一个do_everything(action, params)，一个工具带十几个参数，description 写成小作文，模型在参数组合里挑错的概率急剧上升，而且任何新需求都得改这一个工具。
平衡的经验法则：按"业务意图的一个完整动作"来切，而不是按底层 API 来切。"订机票"对用户是一个意图，但如果下单前必须让用户确认价格，就拆成"搜机票"和"下单"两个——因为中间夹着人的决策点。判断标准是：这个工具单独拿出去，能不能对应一句完整的人话？"查库存"能，"连接数据库再查库存"不能。另外记住一条底线：宁可略粗，不可过细——粗一点模型顶多少点灵活性，细过头模型会在茫茫工具清单里迷路。
原则二：命名与描述——工具的唯一"产品说明书"
模型选择工具，靠的就是名字和描述做语义匹配。这条规则第三篇详细讲过，这里从 Tool 的视角补三条实践：
名字动词开头、蛇形命名、见名知义。get_weather、query_inventory、send_email，模型对"动词 + 名词"的模式最熟悉。反面教材是tool_1、handle、process_data——模型读了等于没读，只能靠猜。
描述写三段：干什么、什么时候用、什么时候别用。这是命中率的核心。比如库存查询工具的描述："按 SKU 或商品名查询实时库存与可售数量。当用户询问库存、能否下单、缺货情况时使用；查询订单的物流状态不要用本工具，用 track_logistics。"最后那句"别用"特别值钱——工具越多，相近工具之间的互相点名越能压低误调用率。
描述里把坑也写上。参数格式（"日期必须 YYYY-MM-DD"）、单位（"金额单位为分"）、限制（"仅支持查询最近 90 天"），全部写进描述。描述是模型出发前能读到的唯一文档，你没写的，它就靠猜，猜错就是你买单。
原则三：返回值——给模型"人读的结果"，不是"机器的转储"
工具执行完，结果会原样进入模型的上下文。这里最容易犯的错：把数据库的原始返回、API 的完整 JSON、一整个 HTML 页面一股脑扔回去。后果有两个：token 成本爆炸（一次工具调用吃掉几千 token，多轮循环直接把上下文撑爆），以及信噪比暴跌（模型在五千行 JSON 里找那三个有用字段，找错概率大增）。
正确的做法是在应用侧做一层"结果整形"：只保留模型需要的字段、把时间戳转成人话（"3 天前"）、超长的列表截断并注明"共 247 条，已显示前 10 条"、数字做单位换算。返回值的目标是：模型扫一眼就知道有什么、该拿它干什么。
原则四：幂等性——写操作的保命符
读操作重复执行无所谓，查两次库存还是那个库存。但写操作不一样："下单"被调两次就是两个订单，"发邮件"被调两次就是两封邮件——而模型因为超时重试、循环判断失误、甚至幻觉，是会把同一个调用发两遍的。
所以每写一个行动执行类工具，先问自己：重复调用会发生什么？提高幂等性的常规手段有三个：
幂等键。让工具接受一个客户端生成的唯一 ID（比如模型为本次任务生成的order_intent_id），服务端见到重复 ID 直接返回第一次的结果而不是重复执行。支付系统都是这么做的，Agent 调用没有理由不借鉴。
确认机制。高危写操作不要让模型直接执行，第一轮调用只返回"待执行确认单"（把要干的事完整列出来），等用户明确点头后，应用才真正执行。这相当于给"手"加了一道刹车：模型可以提议，人来做最终决定。
先查后写。下单前先查"这个用户 10 分钟内是否已有相同内容的订单"，存在就拒绝重复创建。防御性冗余，成本极低，挡掉的却是生产事故。
原则五：错误处理——把报错写成模型能读懂的"下一步指引"
工具一定会报错：网络超时、参数非法、权限不足、数据不存在。差的处理是把异常栈原样扔回去——模型看到一屏 Python traceback，通常会输出一句"抱歉，操作失败"，任务就此中断。
好的处理是把错误也当作一种结构化的返回值来设计，让错误信息本身携带"下一步该怎么办"：
{ "success": false, "error_code": "SKU_NOT_FOUND", "message": "SKU 'A1O3' 不存在（疑似把数字 0 写成了字母 O）", "suggestion": "请先用 search_product 按名称查询正确的 SKU 编码后重试" }模型读到suggestion字段，会真的去调search_product重新查，然后带着正确的参数回来——错误变成了循环里的一次自愈，而不是任务的终点。模型是 Agent 循环里最好的异常处理器，前提是你把异常翻译成它能理解的语言。
四、一个可以直接运行的自定义工具
把五条原则揉进一段能跑的代码。下面是一个"库存查询"自定义工具的完整接入示例——schema 定义、带错误整形和结果整形的实现、接入模型的完整循环，依赖只有一个 OpenAI SDK（pip install openai），国内各家兼容 OpenAI 协议的模型服务也能直接对接：
from openai import OpenAI import json client = OpenAI(api_key="你的KEY") # 也可填国内兼容 OpenAI 协议的服务地址 # ===== ① 工具定义：名字动词开头，描述含"何时用/何时别用"（原则二） ===== tools = [{ "type": "function", "function": { "name": "query_inventory", "description": ( "按 SKU 编码或商品名称查询仓库实时库存与可售数量。" "当用户询问库存多少、能否下单、是否缺货时使用；" "查询订单物流状态不要使用本工具。日期参数格式必须为 YYYY-MM-DD。" ), "parameters": { "type": "object", "properties": { "keyword": {"type": "string", "description": "SKU 编码（如 A103）或商品名称关键词"}, }, "required": ["keyword"], }, }, }] # ===== ② 模拟数据库：真实项目里换成你的存储层 ===== DB = { "A103": {"name": "无线机械键盘", "stock": 42, "reserved": 5}, "B208": {"name": "蓝牙鼠标", "stock": 0, "reserved": 0}, } # ===== ③ 工具实现：错误整形（原则五）+ 结果整形（原则三） ===== def query_inventory(keyword: str) -> str: # 精确命中 SKU if keyword in DB: item = DB[keyword] return json.dumps({ "success": True, "sku": keyword, "name": item["name"], "可售数量": item["stock"] - item["reserved"], # 预扣的库存别暴露给模型 }, ensure_ascii=False) # 模糊匹配商品名 hits = [dict(sku=k, name=v["name"]) for k, v in DB.items() if keyword in v["name"]] if hits: return json.dumps({"success": True, "matches": hits, "note": "请确认 SKU 后再次精确查询"}, ensure_ascii=False) # 查不到：不抛异常，返回结构化错误 + 下一步指引 return json.dumps({ "success": False, "error_code": "NOT_FOUND", "message": f"未找到与 '{keyword}' 匹配的商品", "suggestion": "请向用户确认商品名称或 SKU 后重试", }, ensure_ascii=False) dispatch = {"query_inventory": query_inventory} # ===== ④ 接入模型的完整循环 ===== messages = [{"role": "user", "content": "帮我看看无线键盘还有货吗？"}] while True: resp = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools) msg = resp.choices[0].message if not msg.tool_calls: print(msg.content) # "无线机械键盘（A103）目前可售 37 件，现货充足。" break messages.append(msg) for call in msg.tool_calls: args = json.loads(call.function.arguments) result = dispatch[call.function.name](**args) # 真正执行发生在你的应用里 messages.append({"role": "tool", "tool_call_id": call.id, "content": result})对照第三节的五条原则看：名字query_inventory动词开头；描述里写清了"何时用、何时别用"；返回值只留模型需要的字段，预扣库存这种内部细节不外泄；查不到时不抛异常栈，而是返回带suggestion的结构化错误，让模型自己纠错。40 行的核心逻辑，就是一个生产级工具的全部骨架。
五、为什么工具描述的质量直接决定 Agent 成功率
把第三、四节合起来，回答一个更根本的问题：同样是 GPT-4o，为什么有的 Agent 稳如老狗，有的抽风到怀疑人生？大部分时候，差距不在模型，不在 Prompt，而在工具清单本身。
原因在于模型选工具的机制：它拿用户请求和每条工具的名字 + 描述 + 参数定义做语义匹配，在毫秒之间完成一次"路由"。这条路由链上的每一个含糊点，都是一次抛硬币：
- 名字叫
func_2，模型只能靠描述猜； - 描述只写"查询数据"，模型分不清该查库存还是查订单；
- 两个工具描述高度重叠又没有互相点名，模型随机挑一个，挑错的那个返回错误结果，循环再多转几圈；
- 参数定义模糊，模型凑出格式错误的参数，工具报错，模型重试，再错——死循环烧 token。
这些失败叠加起来，就是"模型能力不差、Agent 就是不好用"的真相。工具清单是模型的操作系统 API 文档，文档的质量就是系统的质量。反过来这也是个好消息：Agent 效果不好时，优化的杠杆往往不在换模型（贵），而在重写工具描述和整理工具粒度（几乎免费）——先花一天把 20 个工具的描述按第三节的五条原则重写一遍，通常比换一档更强的模型见效更快。
六、权限与安全：手脚必须戴上镣铐
再强调第三篇立下那条分界线的安全含义：模型只输出意图，真正执行的是你的应用——所以工具闯的祸，责任全在应用侧，模型不会替你坐牢。给工具上权限，要从三个层面布防：
能力层面：最小权限。每个工具只给它完成任务所必需的权限。库存查询工具用只读数据库账号，就算模型生成了一条DELETE FROM orders，数据库层面也直接拒绝——不要依赖模型"自觉"，要在工具实现里硬编码边界。第三节的代码里"预扣库存不暴露给模型"就是同一思想：模型看不到的，它就破坏不了。
操作层面：分级护栏。把工具按风险分级：纯读的（搜索、查询）直接放行；低危写的（写草稿文件）自动执行但留审计日志；高危写的（发邮件、下单、删除数据）必须走确认机制或幂等键。级别越高，人介入越深。
执行层面：隔离环境。环境操作类工具（执行代码、读写文件、操作浏览器）尤其危险——模型生成的代码有任意性，直接跑在生产机上等于把服务器 root 权限交给一个概率系统。正确做法是把这类执行关进一个一次性的隔离环境：文件系统隔离、网络受限、资源限额、跑完即焚。这个隔离环境有一个专门的名字——Sandbox（沙箱），它是本系列后面要单独开一篇讲的重头戏，这里先埋个伏笔：工具是 Agent 伸出去的手，Sandbox 是给这只手划定的活动范围。
七、反模式：五种常见的糟糕工具设计
集中踩一脚油门，把见过的反面教材放一排，每条附改法：
反模式一：万能工具。一个do_anything(action: str, params: dict)包打天下。模型面对无限的 action 空间只能瞎猜，参数结构没有任何 schema 约束。改法：按业务意图拆成多个强类型工具，每个工具的参数用 JSON Schema 写死。
反模式二：谜语人命名。proc_ord_v2_final、handleData——只有写它的人知道是什么。模型选它等于抽奖。改法：动词开头 + 业务名词（process_order、query_inventory），名字即文档。
反模式三：裸奔的返回值。把 5000 行原始 JSON 直接扔回上下文，token 烧掉，信噪比归零。改法：应用侧做结果整形——挑字段、转人话、截断并注明总量，返回"人读"而非"机转储"。
反模式四：静默失败。工具内部try: ... except: pass，出错返回{"status": "ok"}，模型拿着假成功继续往下走，错误层层传递直到不可挽回。改法：错误必须如实、结构化地回传，并附上下一步建议——让模型参与纠错而不是被蒙在鼓里。
反模式五：无护栏的写操作。delete_user(id)直接上线，模型哪天参数抽风、哪天被提示词注入，一行调用删库跑路。改法：高危写操作上确认机制 + 幂等键 + 最小权限账号，把"撤销"和"审计"当成默认配置。
八、工具体系膨胀后的困境：为什么必须有 MCP
单机时代，工具就是你自己写的几个函数，一个dispatch字典搞定分发，第四节那 40 行代码就是全部。但当 Agent 体系长大，问题来了：
一家公司里，10 个 Agent 团队各自造轮子，接了 10 套不同的工具——数据库查询这同一个能力，被包装成了 10 种不同的接口格式、10 套鉴权方式、10 份描述文档。要给任何一个新 Agent 接工具，就得写一层新的适配代码。M × N 个 Agent 和工具的组合，就是 M × N 个适配器——10 × 10 = 100 个适配器，每个都在重复解决同一件事："把一个能力，按某种私有格式翻译给某个模型。"
这不就是 Function Calling 出现前的正则解析时代吗？当年是"每个应用为每种输出格式写一套解析器"，现在是"每个应用为每套工具写一层适配器"。历史再次押韵，解法也再次相同：把私有协议变成公共标准。
这就是 2024 年底 Anthropic 推出 MCP（Model Context Protocol）的动机：与其让 M 个模型和 N 个工具两两握手，不如让所有工具按同一套协议把能力暴露出来（MCP Server），所有应用按同一套协议接入工具清单（MCP Client）。工具写一次，任何支持 MCP 的 Agent 都能直接用——适配器从 M × N 降回 M + N。工具的"接口标准化"，是 Tool 层走向基础设施的最后一公里，也是下一篇的主角。
九、写在最后
回到开头那个类比：模型是调度员，Tool 是车间里的设备。
这个系列讲到这里，三层结构已经浮出水面：Prompt是你和模型说话的方式，RAG是模型的知识外挂，Function Calling是模型表达意图的协议——而Tool，是这一切最终落地的物理接口。用户不为模型的推理过程付费，用户为"事情真的办成了"付费，而办成事的每一步，都是某个 Tool 在执行。
所以做 Agent 的功夫，三分在调模型，七分在造工具：粒度切分、命名描述、返回值整形、幂等护栏、错误翻译——这五条原则不依赖任何模型，今天就可以用在你手上的项目里。而当工具越造越多、越连越广，M × N 的适配困境会把所有人推向同一个出口：标准化协议 MCP，以及再往后，把工具执行关进 Sandbox 的安全体系。这条线，我们下一篇接着走。
 AI应用开发实战：从核心功能到私有化部署全解析)
