题目 1:Data Analysis Agent 与普通 Text-to-SQL 最大的区别是什么?请用“为什么昨天收入下降?”说明。
Text-to-SQL 通常把一个自然语言问题转换成一次 SQL,然后根据结果回答,更适合“昨天收入多少”这种单次查询。Data Analysis Agent 面对“为什么收入下降”时,会先查总体指标,再根据 Observation 判断异常来自 request、impression、eCPM 或其他指标,随后动态选择媒体、广告位等维度继续查询。它解决的是连续分析过程,而不是一次 SQL 翻译。
题目 2:为什么 Data Agent 需要 AnalysisState,而不能只依赖聊天历史?
聊天历史记录的是发生过什么,却不一定清晰表达当前已经确认的事实、已经否定的假设、查询过的维度和仍未回答的问题。AnalysisState 可以显式保存 confirmed_findings、current_hypothesis、queried_dimensions、remaining_questions 和 query_count。这样即使 Context 变长或发生 Compaction,Agent 仍能知道分析进展,避免重复查询和错误结束。
题目 3:编程实现——定义一个最小 AnalysisState,至少包含 goal、confirmed_findings、queried_dimensions 和 query_count。
from dataclasses import (
dataclass,
field,
)
@dataclass
class AnalysisState:
goal: str
confirmed_findings: list[str] = field(
default_factory=list
)
queried_dimensions: list[str] = field(
default_factory=list
)
query_count: int = 0
if __name__ == "__main__":
state = AnalysisState(
goal="分析收入下降原因"
)
state.confirmed_findings.append(
"eCPM 明显下降"
)
state.queried_dimensions.append(
"media"
)
state.query_count += 1
print(state)
#真实系统还会加入 run_id、status、current_hypothesis、remaining_questions 和重要 Query Evidence。
题目 4:为什么结构化 Query Tool 通常比让模型直接生成任意 SQL 更适合生产 Data Agent?
结构化 Query Tool 可以限制允许的表、指标、维度、时间范围、Limit 和只读权限,模型只需要表达“我要查什么”,后端负责生成和执行安全 SQL。这样更容易做 Schema Validation、Middleware、Trace、超时和权限控制。任意 SQL 虽然灵活,但风险更高,也更容易出现错误表、危险写操作和不可控扫描,因此生产系统更适合受控查询接口。
题目 5:如果整体数据显示 request -1%、eCPM -30%、income -24%,下一步更合理查什么?为什么?
request 基本稳定,而 eCPM 明显下降,说明当前主要假设应从流量问题转向变现价格或效率问题。下一步更合理的是按 media 维度查看 income、impression 和 eCPM,找出哪个媒体对整体 eCPM 下滑贡献最大,而不是优先继续按请求来源深挖。这个选择正是 Observation 驱动下一步 Query 的体现。
题目 6:为什么 Data Agent 必须有 Stop Condition?什么情况下应该结束分析?
如果没有 Stop Condition,Agent 很容易在已经找到主要原因后继续查询小时、地域、设备、版本等维度,造成过度 Tool Calling、数据库资源浪费和 Context 噪声。一个实用结束条件是:整体异常已确认、主要异常指标已定位、至少一个主要贡献维度已找到、最终结论有 Query Result 支撑、没有关键未回答问题。满足后应优先总结而不是继续无边界下钻。
题目 7:如何把本章 Data Agent 做成一个真正可持续迭代的系统,而不是一次 Demo?
需要把 AgentEngine 与 Flask Route 解耦,通过 Run、Session、SQLite 和 Trace 持久化分析过程;Query Tool 要有 Policy、权限、超时和结果截断;Data Analysis Skill 要定义分析顺序与 Stop Criteria;RunGuard 限制 Query 次数和总耗时;Evaluation 建立固定异常案例 Benchmark;每次失败再通过 Trace 做 Failure Postmortem,并把新失败样本加入 Regression Benchmark。这样系统才能持续迭代而不是只跑通一次。
进一步阅读
- Text-to-SQL:理解自然语言到结构化查询的基础能力,以及它与多轮 Agent 分析的边界。
- Metric Decomposition:收入、流量、转化与价格类指标如何做层层拆解。
- Query Planning:让模型输出结构化 Query Plan,而不是直接拥有任意数据库写权限。
- Analysis State:开放分析任务中如何保存假设、证据、已查维度和剩余问题。
- Evidence-based Analysis:最终结论如何绑定真实 Query Result。
- Data Agent Benchmark:如何构造收入异常、流量异常、价格异常、数据缺失等标准案例。
- Database Safety:只读权限、时间范围、Limit、超时和表字段白名单。
- AgentOps:Trace、Metrics、Evaluation 与 Failure Postmortem 如何作用于 Data Agent。
术语表
- Data Analysis Agent:围绕一个开放数据问题,通过多轮查询、Observation、假设更新和维度下钻持续收集证据,直到形成分析结论的 Agent。
- Text-to-SQL:把自然语言转换为 SQL 的能力,通常解决一次查询,不天然包含多轮 Observation-driven Analysis。
- AnalysisState:保存当前分析目标、已确认事实、当前假设、已查维度、剩余问题和查询次数的结构化状态。
- Query Plan:模型输出的结构化查询意图,例如时间范围、指标、维度和过滤条件,由后端转换成安全 SQL。
- Metric Decomposition:把收入等最终指标拆成 request、impression、click、eCPM 等中间指标,用于判断异常发生在哪一层。
- Dimension Drilldown:在确认异常指标后,继续按 media、position 等维度下钻,定位主要贡献来源的过程。
- Evidence Chain:由多次 Query Result 串起来的分析证据链,使最终结论可以追溯到真实数据。
- Analysis Completion Gate:Data Agent 输出最终结论前的完成检查,包括异常指标、主要维度、证据和剩余问题是否满足结束条件。
本章总结
这一节,我们完成了整门课程第二个,也是最后一个端到端项目,从 0 打造 Data Analysis Agent。
用户只需要问一句,“为什么昨天收入突然下降?”
Agent 不再只做:
问题
↓
SQL
↓
答案
而是进入:
问题
↓
SQL
↓
观察结果
↓
决定下一步查什么
↓
SQL
↓
继续观察
↓
继续分析
这就是整章最重要的第一条结论,Data Agent 与 Text-to-SQL 最大的区别,不是 SQL 生成能力更强,而是拥有多轮运行时决策。
Text-to-SQL 解决:
一次查询。
Data Agent 解决:
一个开放分析目标。
第二条原则是,每次 Query Result 都必须改变 Analysis State。
例如:
request 基本稳定
eCPM 明显下降
这两条一旦确认。
下一步就不应该继续无差别查流量。
而应该:
优先下钻价格与变现维度。
如果 Observation 变成:
request -40%
eCPM 稳定
分析路径就应该完全改变:
优先查流量来源。
这就是 Agent 的动态性。
第三条原则是,Data Agent 需要自己的 Working Memory。
我们定义:
goal
current_hypothesis
confirmed_findings
queried_dimensions
remaining_questions
query_count
这样 Agent 才不会:
忘记已经查过什么
重复查询
丢失关键结论
提前结束
第四条原则是,模型负责决定“下一步查什么”,Harness 负责安全执行。
不要直接给模型:
任意 SQL 权限。
更推荐:
LLM
↓
Query Plan
↓
Query Policy
↓
Safe SQL
↓
Database
模型表达:
指标
维度
时间范围
过滤条件
后端负责:
表白名单
字段白名单
只读
时间范围
Limit
超时
这和整个课程从 Tool Calling 开始建立的思想完全一致。
第五条原则是,Data Agent 不应该无边界下钻。
真正成熟的分析,不是:
查得越多越专业。
而是:
每一次查询都回答一个明确问题。
当:
整体异常已确认
主要异常指标已定位
主要贡献维度已定位
结论有证据支撑
就应该:
COMPLETED。
否则很容易出现:
SQL 50 次
Token 越来越高
Context 越来越乱
最后结论反而更差
第六条原则是,最终分析必须来自 Evidence Chain。
例如:
收入 -25.4%
↓
request +0.3%
eCPM -25.5%
↓
media_a 收入差额 -6800 / eCPM -33.8%
↓
position_102 收入差额 -6600 / eCPM -54.5%
最终结论才是:
现有数据不支持“流量大幅下降”这个解释,
主要下降贡献集中在 media_a 下的 position_102;
具体业务根因仍需结合变更记录确认。
这不是模型猜出来的。
而是:
Query Result
一步步支持出来的。
第七条原则是,Data Agent 仍然需要 Flask、Run、Trace、Metrics 和 Evaluation。
成熟架构:
Client
↓
Flask
↓
AgentService
↓
DataAgentEngine
↓
ContextBuilder
↓
AnalysisMemory
↓
LLM Provider
↓
Query Tool Registry
↓
Query Policy
↓
Database
↓
Trace
↓
Evaluation
这样同一个 Agent 才能真正进入:
Web
内部数据平台
飞书机器人
运营分析助手
广告数据分析系统
等真实场景。
到这里,整门课程的最终架构已经完整闭环:
Client
↓
Flask
↓
Session / Run
↓
Agent Engine
↓
Context / Memory / Planner
↓
Main Loop
↓
LLM Provider
↓
Tool Calling
↓
Middleware
↓
Tool Registry
↓
File / Shell / Python / Query
↓
Tracing
↓
Metrics
↓
Evaluation
我们从最开始一个最简单的:
while True:
...
一路走到了:
Coding Agent
+
Data Analysis Agent
真正值得带走的并不是某一段框架代码。
而是这套判断方式:
确定性的流程
→ Workflow / DAG
开放式下一步决策
→ Agent
真实世界动作
→ Tool
工具执行边界
→ Middleware / Sandbox
长期运行稳定性
→ State / Memory / RunGuard
复杂任务组织
→ Planner / SubAgent / Skills
项目约束
→ AGENTS.md
可维护性
→ Tracing / Metrics / Evaluation
如果这些东西真正理解了。
以后不管你用:
OpenAI
Claude
本地模型
自己封装 Provider
现成 Agent 框架
底层的判断逻辑都不会变。
这才是我们从 0 手搓 Agent Harness 真正想建立的能力。

















请登录后查看评论内容