案例分析二：Data Analysis Agent 生成查询动作，为什么 Tool Calling 比直接生成 SQL 更好控制？

这个案例最适合用对比图来看。因为一旦把“直接给 SQL”与“先产生受控查询动作”并排摆出来，安全边界和工程治理的差别会一下子清楚很多。

换句话说，Tool Calling 的价值并不只是让模型输出得更规范，而是把模型能做的动作收敛到可控范围内，让后续白名单、时间限制和审计规则都有了落点。

场景背景

业务问，“昨天收入为什么下降？”

一种做法是让模型直接返回 SQL：

SELECT ...

然后系统执行。

另一种做法是让模型产生：

{
  "name": "query_metric",
  "arguments": {
    "metric": "revenue",
    "date": "yesterday",
    "dimension": "media"
  }
}

问题矛盾

直接 SQL 很灵活。

但模型自由度也很大：

• 可能查错表；
• 可能 SELECT *；
• 可能查询过大时间范围；
• 可能写出危险 SQL；
• 可能跨权限。

如果先抽象成业务 Tool：

query_metric

Harness 可以把参数转换成安全 SQL。

输入

Tool Call：

{
  "name": "query_metric",
  "arguments": {
    "metric": "revenue",
    "date_start": "2026-09-03",
    "date_end": "2026-09-03",
    "dimension": "media",
    "limit": 20
  }
}

Harness 处理

第一步：

校验 metric 白名单

第二步：

校验 dimension 白名单

第三步：

校验日期范围

第四步：

限制 limit

第五步：

由程序生成 SQL

第六步：

执行查询

输出

Tool Result：

{
  "ok": true,
  "rows": [
    {
      "media": "A",
      "revenue": 120000
    },
    {
      "media": "B",
      "revenue": 80000
    }
  ]
}

复盘与迁移

Tool Calling 的价值之一，就是给模型一个，受控动作空间。

与其让模型直接拥有任意 SQL，不如先给它：

query_metric
query_by_dimension
get_schema

Harness 再把这些动作映射到真实数据系统。

同样的思想也可以用在：

• 文件系统；
• Shell；
• 邮件；
• Git；
• 云资源；
• 生产发布。

越高风险的外部系统，越不应该让模型直接拥有“原始操作能力”。

常见误区

误解： 模型生成了 {"name":"read_file"}，就说明模型真的执行了 Python 函数。
正解： 模型只是输出一个结构化调用意图。真正的 read_file() 是由 Harness 在 Python 进程中查找并执行的。如果 Harness 不执行，真实世界不会发生任何变化。把 Tool Call 和 Tool Execution 分开理解，是后面权限、安全、审批设计的基础。

误解： Tool Calling 就是把自然语言转成 JSON，除此之外没什么工程价值。
正解： 结构化只是第一步。真正价值在于 Harness 可以围绕 Tool Call 做参数校验、权限检查、审计、重放、限流、审批和错误恢复。自然语言指令很难稳定治理，而结构化动作天然适合程序控制。Agent 真正能走向工程，靠的是这条执行边界。

误解： 模型输出的参数应该默认可信，因为模型已经知道 Tool Schema。
正解： Tool Schema 只能降低出错概率，不能替代 Harness 校验。模型仍可能缺字段、类型错误、值范围异常，甚至产生危险路径。任何来自模型的 Tool Call 都应该被当成“不可信输入”，像处理外部 API 请求一样做校验。这一点尤其适用于 Shell、文件写入、SQL 等高风险工具。

误解： Tool 一旦报错，说明 Tool Calling 失败，这轮就应该终止整个 Agent。
正解： 很多 Tool Error 是有价值 Observation。例如 FileNotFoundError 会告诉 Agent 路径假设错误，SQL 空结果会提示换维度。可恢复错误应该结构化后送回下一轮，让模型修正动作。只有权限拒绝、超预算、系统硬边界等情况才可能直接结束任务。

误解： Tool Registry 只是一个字典，没必要单独做组件。
正解： 最开始确实可以是字典，但后面会逐渐需要 Tool Schema、描述、参数定义、权限、分类、版本、是否有副作用等元数据。Registry 会成为模型“有哪些工具”和 Harness“实际能执行哪些工具”的统一来源。下一节我们会专门把它工程化。

误解： Tool Calling 越自由，Agent 越强。
正解： 自由度越高，也意味着风险越大。生产 Agent 更重要的是给模型“足够完成任务的动作空间”，而不是无限操作能力。例如数据分析场景里，受控 query_metric 往往比直接开放任意 SQL 更安全；Coding Agent 中受限 workspace 工具也比任意 Shell 更稳。工具设计本身就是 Agent 能力设计的一部分。