本课目标

  • 掌握 @Tool 注解的声明式工具定义
  • 理解模型如何"决定"调用哪个工具
  • 学会控制工具返回大小、规避危险操作

模型很聪明，但它困在一个文字世界里。它不能查数据库、不能调 API、不能读文件。Tool Calling 就是给模型装上一双手——它能伸手去拿外部世界的信息，拿回来继续思考。本讲的两个重点是：工具怎么定义，以及哪些操作绝对不能暴露给模型。

核心内容

两种定义方式

声明式：@Tool 注解在方法上，Spring AI 自动扫描并注册。描述写在注解的 description 里——模型就是通过这段文字判断"什么时候该用这个工具"。描述质量直接决定调用准确率。

编程式：MethodToolCallback 手动注册。适合动态生成工具列表的场景。

把工具描述想象成招聘 JD。JD 写得太模糊，投简历的人不是在瞎蒙就是在海投。工具的 description 也一样：不是"查询数据"，而是"根据产品 ID 查询该产品的库存数量和最近 30 天销量"。

模型调用工具的过程：两跳协议

一次 Tool Call 其实是两跳：模型决定调哪个工具 → 你的代码执行工具 → 结果还给模型。模型拿到结果后再决定：继续调另一个工具，还是已经可以给最终答案了。

直觉：模型是经理，工具是下属。经理不会亲自查数据库，他告诉下属去查，下属回来汇报，经理整合成决策。

Keep it small, keep it safe

工具返回控制在几百 Token 以内。如果一次数据库查询返回一万条记录，全塞进上下文——贵且模型会被淹没。在工具层做截断、聚合、摘要。

永远不要暴露：删除操作、写操作、涉及权限变更的操作。模型可能被注入攻击误导去调用不该调的工具。只读工具给模型，写操作留给你的业务代码。

动手练习

给第 01 讲的项目加一个"查天气"工具（调公开 API），让模型在回答"今天适合跑步吗"时自动调用它。