Agent 分析工具设计的五个坑：100 行分页样本被当全量汇总，工具响应设计才是关键

AbleBranch6 · reddit · 2026-11-04

作者指出：在数仓上做 agentic 分析（经 MCP 或 function calling）时，模型写的 SQL 往往没问题，出事的是工具返回了什么。文中借 Cube 的 agentic analytics harness 生产实践总结了五个可复用模式，并给出自测方法。

1. 结果截断必须显式说明

查询可能返回 5 万行，工具只回前 100 行时，模型常把分页当全量：排名、求和、报告一个「总数」其实是单页总数。Cube 的做法是返回首 100 行 + 总行数 + 可取更多页的 queryid + 明确的 partial 提示。作者给出了最小 JSON 响应结构示例，以及一个快速自测：让 agent 算「前 10 客户占总营收比例」，若明显高于自己手算的 SQL 结果，就是分母用了分页总数。

2. 错误要告诉模型如何恢复

模糊错误每次都浪费一轮往返和上下文：列名 position 未加引号的解析错误应提示加引号重试；超时应提示用更长超时重试同一 SQL；执行前 linter 拒绝已知非法构造（如 measure 嵌套进 SUM）并解释原因。

3. 成功不止一种状态

执行成功但结果保存失败不算成功；零行不代表分析完成；部分结果要说明缺了什么、如何补齐。不显式说明这些状态，模型就会猜，且倾向于乐观猜测。

4. 按需搜索 schema 而非预载

把完整 schema/语义模型塞进 system prompt 浪费上下文，还可能暴露调用方无权查询的字段，且部署变更后立即过期。按需搜索工具每次读取时同步刷新、按调用方权限过滤、返回少量候选度量/维度；代价是加一点延迟——作者认为值得，因为过期搜索会静默失败。

5. 上下文层不止一种形态

语义元数据（描述、指标构建方式）、自由格式的业务笔记（财年日历、财务排除的交易类型）等各有归属和加载规则，应分层管理。

原文链接 →

「编程与Agent」频道最新

更多「编程与Agent」频道 AI 资讯 →