让 AI 不只写 SQL：smolagents 把查表、看结果和追问接成循环

“找出金额最大的那张收据”与“哪个服务员拿到的小费总额最多”，看起来都是问一句话，实际需要的表结构与计算过程却不同。smolagents 的官方 SQL 样例，把这两个问题连着讲，适合用来理解数据代理究竟比一次性生成 SQL 多做了什么。

它的关键是把执行结果交回模型，让后续行动能基于查到的内容继续推进。CodeAgent 会把动作写成 Python 片段，调用你提供的工具函数，再读取返回结果；不是只吐出一段 SQL，就把整个任务交给用户收尾。

第一张表，问题可以直接核对

官方 Text-to-SQL 教程用内存 SQLite 创建 receipts，包含收据编号、客户名、金额与小费四类字段，插入四行数据。

工具 sql_engine 接收 SQL 字符串执行查询，把每行结果转成文本返回。更值得注意的是工具的 description：明确告诉模型表名和列名、列类型。这些说明会进入模型提示，让它知道自己能查询什么。

第一个任务问“金额最高的收据属于谁”。按教程四行数据，最高金额是 Woodrow Wilson 的 53.43。本文用同样数据做了独立 SQLite 核算，确认这个对应关系；这只是确定性的 SQL 检查，不是重新运行模型或代理得到的成绩。

这样的样例很适合判断工具是否接对：如果输出里客户和金额对不上，先查执行查询、结果字段和表说明，而不是马上得出模型推理能力强弱的结论。

加入第二张表，描述也必须跟着变

接下来，教程增加 waiters，按 receipt_id 记录服务员。新问题是“小费总额最多的是谁”。这时仅知道 receipts 的字段不够，还需要连接关系，以及对同一服务员多张收据求和。

官方在这一步重新生成工具 description，把两张表的结构一起告诉模型。这是整份样例中最值得保留的细节：数据库更新了，模型看到的工具说明也要更新。否则实际工具能执行两表查询，模型却仍按一张表规划。教程在第二阶段还更换了所调用的模型，因此不能把跨表问答表现归因于只更新 description；这里的算数核对也不评价两个模型的效果。

根据教程数据，Michael Watts 对应两张收据，小费 0.24 与 5.43 合计 5.67，高于另外两人。这个计算让读者可以辨认正确目标：找单笔最大小费，与按人汇总不是同一件事。结果看起来合理，也仍要核对它回答的是哪一个问题。

有执行反馈，仍需要数据边界

项目 README解释了“模型生成行动、执行工具、保存观察、继续下一轮”的循环，并提供 CodeAgent 与常规 ToolCallingAgent 等选择。前者适合把若干工具调用和计算写成代码来组合。

教程里的 SQL 工具只是教学实现，没有自动替生产数据库建立只读权限。真实接入应限制可访问的数据与操作，并安排代码执行隔离。README 特别说明，内置 LocalPythonExecutor 不是安全沙箱。

smolagents 采用 Apache-2.0 许可，模型服务和运行资源另行准备。我会先保留这份两表样例做工具设计的起点：表结构说清楚，执行结果拿得回来，再检查模型有没有按真正的问题组合查询。能沿数据复核，数据问答才有继续扩展的基础。