一个 SQL 接口，就是一个 AI 工具
一句话：写一条聚合 SQL 存成数据接口，把它登记成一把自定义工具，绑给一个智能体。然后问它「各个状态的订单分别有多少笔」——它不会凭记忆报数，而是先去调那把工具，拿到实时结果再照着说。屏幕上会明明白白出现一行「正在调查：order_status_summary」，那就是它在调工具的证据。这一章是首页视频的第 05 章。
演示环境里已经有成品
用 admin / admin123 登录：
- 基础设施 → 数据管理 → 接口管理 里的
订单状态汇总（编码demo_order_status_summary）——点行内「测试」→「执行」，当场能看到结果； - AI → AI 助手 → 工具管理 → 自定义工具 页签里的
order_status_summary； - AI → AI 助手 → 智能体管理 里的
订单数据助手（编码doc_order_helper）——去智能助手新建对话选它，问「现在各个状态的订单分别有多少笔？」。
功能在哪
| 页面 | 菜单路径 | 这一章用它干什么 |
|---|---|---|
| 接口管理 ★ | 基础设施 → 数据管理 → 接口管理 | 写 SQL、存成正式接口、在线测试 |
| 工具管理 ★ | AI → AI 助手 → 工具管理 → 自定义工具 | 把接口登记成一把 AI 能调的工具 |
| 智能体管理 ★ | AI → AI 助手 → 智能体管理 | 建智能体、绑这把工具、发布 |
| 智能助手 ★ | AI → AI 助手 → 智能助手 | 提问，看它调工具、看答案 |
前置条件
- 有一张能查的表。这一章用的是在线示例自带的
test_demo_order（演示环境里 3 行未删除数据，订单状态分别是 1 / 2 / 4）。你的实例上没有这张表就换一张，SQL 改改字段名即可，步骤一模一样。 - 已配好 API 密钥 与 模型配置。
- 这一章不需要知识库。
为什么用演示表而不是第 01 章 AI 建的那张
第 01 章那张表是 AI 当轮生成的，字段名每轮都可能不同；用它的话这一章的 SQL 每次都得重写。演示表的结构是固定的，SQL 可以照抄。
常用操作
第 1 步：写 SQL，存成数据接口
进 基础设施 → 数据管理 → 接口管理，点「新增」。弹出的面板标题是「新建接口」。
| 字段 | 填什么 |
|---|---|
| 接口名称 | 订单状态汇总 |
| 接口编码 | demo_order_status_summary |
| 标签 | 多选下拉里勾 AI 工具 |
| 类型 / 动作类型 / 是否分页 | 都不动，保持默认（SQL 查询 / 查询 / 关） |
「配置」那一栏是个 SQL 编辑器，把下面这条整段贴进去：
SELECT
CASE order_status WHEN '1' THEN '待付款' WHEN '2' THEN '待发货'
WHEN '3' THEN '已发货' WHEN '4' THEN '已完成'
WHEN '5' THEN '已取消' ELSE order_status END AS status_name,
COUNT(*) AS order_count,
IFNULL(SUM(pay_amount), 0) AS pay_amount_total,
IFNULL(SUM(goods_amount), 0) AS goods_amount_total
FROM test_demo_order
WHERE deleted = 0
GROUP BY order_status
ORDER BY order_status
点「保 存」（两字按钮中间有个空格）。做对了弹绿色提示，含「成功」。
这条 SQL 里有三处是刻意的，别「顺手优化」
WHERE deleted = 0得自己写。平台的逻辑删除不会自动帮你加，不写就会把删掉的行也统计进去。- 不要自己写租户条件。这张表没有
tenant_id列，租户拦截器对「查不到表信息的表」直接放行；你自己加一个tenant_id = 1会报「未知列」。同理不要 joinsystem_dict_data去取状态名——它有实体类但没有tenant_id列，一旦被拦截器注入条件就会报错。所以状态名用CASE硬写。 - 这条 SQL 故意不带参数。带参数就得在测试面板里填值、在对话里让模型猜值，两处都可能翻车。想带参数等这一章走通了再加。
「存下来」意味着什么
它不是一个临时查询，而是一个正式接口：有版本号、能回滚、每次调用都记流水（在访问日志里查得到）。这也是它后面能被当成工具的原因。
第 2 步：在线测试，确认数字对得上
回列表，在 demo_order_status_summary 那一行点「测试」。面板标题是「在线测试」，点「执行」。
面板会回显实际执行的 SQL（租户条件注入得对不对，一眼能核对）和结果 JSON。本轮实测三行：
| status_name | order_count | pay_amount_total | goods_amount_total |
|---|---|---|---|
| 待付款 | 1 | 8480.00 | 8480.00 |
| 待发货 | 1 | 37254.60 | 41394.00 |
| 已完成 | 1 | 45588.60 | 47988.00 |
「测试」不是干跑
它走的是和正式调用同一套后端逻辑，包括租户条件注入与权限判定。所以这一步测出来的数字，就是待会儿模型能拿到的数字——把这张表记下来，第 5 步要拿它对账。
第 3 步：把接口登记成一把工具
进 AI → AI 助手 → 工具管理，点「自定义工具」页签，再点「新增」。面板标题是「新增工具」。
| 字段 | 填什么 |
|---|---|
| 工具键 | order_status_summary |
| 展示名 | 订单状态汇总 |
| 分组 | 数据接口 |
| 关联数据接口 | demo_order_status_summary |
| 风险等级 | 不动，默认「只读」 |
| 执行方式 | 显式选「只读查询」 |
「工具说明」填这段（这是整章最重要的一段文字，原因见下面的 warning）：
查询演示订单按状态分组的汇总：每种状态各有多少笔、付款金额合计、商品金额合计。凡是要回答「各状态订单数量 / 金额合计 / 哪类占比最高」都先调它，拿到实时数字再作答，不要凭记忆报数。
点「保 存」。
「关联数据接口」是远程搜索，不打字就是空下拉
点开那个下拉看不到任何选项——它要你先打字才去查。输入 demo_order_status_summary，等一两秒，选项才出现。
工具说明会原样进模型提示词，是模型选对工具的唯一依据
模型看不到你的 SQL，也看不到接口名称背后的业务含义。它决定「这个问题该不该调这把工具」时，读的就是这段说明。写「查询订单」这种一句话说明，模型会在该调的时候不调、不该调的时候乱调。
上面那段说明的写法值得照抄：先说它返回什么（每种状态各有多少笔、金额合计），再说什么时候必须调它（凡是要回答某某某都先调它），最后说反面（不要凭记忆报数）。
保存即生效，不用再发布一步
自定义工具和智能体不一样：没有发布环节。工具键（order_status_summary）就是模型能点的那个名字，存下来立刻可以被绑。
第 4 步：建一个绑这把工具的智能体
进 AI → AI 助手 → 智能体管理，点「新增」：
| 字段 | 填什么 |
|---|---|
| 名称 | 订单数据助手 |
| 编码 | doc_order_helper |
| 知识库 | 留空 |
| 工具（只读） | 选 order_status_summary |
人设填这段：
你是「启凌智搭」平台的订单数据问答助手。
职责：回答演示订单的分布问题——各状态多少笔、金额合计多少、哪一类占比最高。
方法：凡是要报具体数字，必须先调用「订单状态汇总」工具拿到实时结果，再照着返回值说；不许凭记忆或估算编数。
格式：先一句话给结论，再列一张「状态 / 笔数 / 付款金额」的小表。金额保留两位小数，单位元。
边界：工具没返回的项就说「这个接口没查这一项」；不执行任何写操作。点「保存并发布」，弹「已保存并发布」。
知识库这一栏必须留空
绑了工具就走「思考 → 调工具 → 再思考」的调查循环，而工具与知识库检索在这一版是互斥的。这一章要演的是工具，知识库绑上只会让检索被跳过、白配。互斥的另一半见第 04 章。
不要复用第 04 章那个「使用手册助手」
它的人设写死了「只依据检索到的手册片段作答」「与本平台无关的问题不答」。拿它问订单数据，它很可能当着你的面拒答。工具型智能体必须单独建、人设单独写。
工具下拉里那个选项可能是灰的
如果 order_status_summary 在列表里显示为不可选，说明这把工具当前不允许被绑（比如风险等级或执行方式与这个智能体的能力不匹配）。回去检查第 3 步的「风险等级 = 只读」「执行方式 = 只读查询」。
第 5 步：问它，并且确认它真的调了工具
进 AI → AI 助手 → 智能助手，点「新建对话」，在智能体选择器里选「订单数据助手」，输入框填：
现在各个状态的订单分别有多少笔？付款金额合计各是多少？点「发送」。
关键的一帧在这里：回答出来之前，界面上会先出现一行进行中的提示——
正在调查：
order_status_summary
这行字就是「模型真的调了工具」的唯一直接证据。它只在调用期间出现，答案一出来就被清掉——看到的时候别急着往下读，先确认它出现过。
然后是最终答案，按人设要求给一句话结论 + 一张小表。
第 6 步：对账
把答案里的数字和第 2 步测试面板的结果逐个对：
| 状态 | 测试面板 | 模型答案应该说 |
|---|---|---|
| 待付款 | 1 笔 / 8480.00 | 1 笔 / 8480.00 |
| 待发货 | 1 笔 / 37254.60 | 1 笔 / 37254.60 |
| 已完成 | 1 笔 / 45588.60 | 1 笔 / 45588.60 |
对上了，说明数字是查出来的，不是编的。这一章就成立了。
想更狠一点：改一条数据再问一次
去在线示例的订单表把某条记录的金额改掉，回来再问同一个问题。答案应该跟着变——这才彻底排除「模型记住了上一轮的答案」。
视角对照
| 视角 | 表现 |
|---|---|
超管 admin | 本章视角。能建接口、建工具、建智能体 |
租户管理员 docadmin | 有对应菜单就能建。注意工具是以发布者身份执行的——发布者能查什么，工具就能查什么 |
普通员工 salesman01 | 没有这些菜单；能不能在助手页选中这个智能体，取决于它有没有授给他的角色 |
套餐受限租户 aoteman | 看套餐里有没有「接口管理」与 AI 相关菜单 |
进阶
- 接口管理 ★：接口的类型、动作类型、分页、版本与回滚、调用流水；
- 工具管理 ★：内置工具与自定义工具的区别、风险等级与执行方式的完整含义；
- 工具体系：工具是怎么注册进模型提示词的、安全网关在哪一层拦（开发视角）；
- ReAct 循环与流式对话：「正在调查：…」这行字的来源；
- 第 04 章：教一个机器人回答「这系统怎么用」：互斥的另一条路。
常见问题
Q：模型没调工具，直接给了个答案？ A：这一轮不算数——答案的来路不明，数字很可能是编的。三个方向排：① 工具说明写得太笼统，模型没意识到该调它（回第 3 步照那段说明的三段式重写）；② 人设里没写「必须先调用工具」；③ 问法太泛，换成明确要数字的问法（「各状态分别多少笔」比「订单情况怎么样」更容易触发）。
Q：工具说明到底要写多细？ A：判断标准是一句话：一个没见过你系统的同事，只读这段说明，能不能判断出「这个问题该不该调它」。能就够了。所以要点明返回什么、什么情况下必须调、以及不该干什么。
Q：能不能让这把工具改数据（写入/更新）？ A：技术上能，但风险等级和执行方式就不再是「只读 / 只读查询」了，平台会按更严的口径对待它，智能体那边也可能不允许绑。真要写，参照第 02 章的做法：把写操作放进流程里，上游加一个人工闸口，让人点头再动手——而不是让对话里的模型自己决定写什么。
Q：SQL 改了，工具会跟着变吗？ A：会。工具绑的是接口编码，接口内容改了、保存了，下次调用就是新 SQL。但接口有版本，改完记得确认线上生效的是哪一版。
Q：在线测试的结果和模型答案对不上？ A：先看在线测试面板回显的实际执行 SQL——租户条件注入之后可能和你写的不一样。再看两次查询之间有没有人改过数据。最后才怀疑模型算错（它一般只是照抄返回值，不会自己算）。
Q：结果 JSON 解出来是个 {code, msg, data} 信封？ A：在线测试面板会把返回值原样贴出来，可能是行数组，也可能是信封或分页对象 {total, list}。核对数字时记得往里剥一层。