Day 20 - Weekly Review 4: Tool-Based Agent Demo

今日目标

能做出调用 2-3 个工具完成 Nginx CPU 分析的 Agent Demo。

学习安排

时间	模块	做什么
0-10 分钟	整理产出	盘点 Day 16-19 的四份产物（工具定义、MCP 架构、权限矩阵、流程设计），确认每份都能用自己的话解释。
10-25 分钟	查漏补缺	回看第 4、5 章重点，把说不清的概念补进今天的交付物。
25-45 分钟	实践任务	把工具定义组装成 Demo，跑通「Nginx CPU 分析」完整闭环。
45-55 分钟	追问与反思	回答追问练习，标记 Demo 里最容易出错的一步。
55-60 分钟	复盘与作业	整理阶段交付物清单，定下明天要复习的一点。

核心概念

术语	中文解释	应用场景
demo	演示：跑通最小闭环的可运行示例，证明概念而非完成产品	输入一句中文指令，Agent 调用工具输出结论
tool routing	工具路由：根据任务把请求分发给正确工具的决策过程	「查 CPU」走 query_metrics，「看报错」走 query_logs
empty result	空结果：工具返回无数据，需判断是正常（确实无数据）还是异常（查询条件错）	10:55-11:00 日志为空，先核对时间格式
verified vs unverified	已验证与待验证：结论的证据分级，有工具数据支撑 vs 只有推测	指标证实 CPU 升高；归因 WAF 需进一步验证
productionization	产品化：把 Demo 变成生产可用系统的过程（鉴权、限流、评估、审计）	给 Demo 接上权限矩阵与审计日志
acceptance criteria	验收标准：判断任务是否完成的明确条件	「输出含 3 个异常时间点与证据标签」
trace log	轨迹日志：记录 Agent 每步决策与工具调用的日志，用于排障与复盘	回看 Demo 为什么先查了指标再查日志
fallback	降级路径：主路径失败时备选的处理方案	query_metrics 失败时改用日志关键词统计

阅读重点

对应章节：回看第 4 章（工具与 MCP）、第 5 章（Coding Agent）的关键小节。
关注点：
工具定义五要素（用途、参数、返回、失败、权限）是否在 Demo 里全部体现。
工具路由与调用顺序：先查指标定位异常时间段，再查日志找原因。
权限分级：Demo 里哪些调用无需确认，哪些必须确认。
失败处理：空结果、超时、参数错误在 Demo 里如何表现。
补充材料：
回看 Day 16-19 的补充材料（tool use 文档、MCP 官方文档、工具安全实践）。
用 OpenAI Agents SDK 或类似框架跑一遍官方工具调用示例，对照自己的 Demo。

理解检查

这个 Demo 的工具调用顺序是什么？为什么先查指标再查日志？
哪一步最容易出错？你的 Demo 里最可能出现的失败是什么？
如何判断工具返回为空是正常还是异常？
哪些结论不能让 Agent 直接下定论？应该怎么标注？

实践任务

背景：把 Day 16 设计的 3 个工具（可先用模拟实现）组装成一个最小工具 Agent，跑通「一句话任务 -> 工具调用 -> Markdown 结论」的闭环。今天跑通闭环最重要，不用追求真实数据源。

步骤：

准备模拟数据：10:00-11:00 的指标样本与日志样本，包含一段异常区间。
实现 3 个工具函数（可返回假数据，但返回结构按 Day 16 的定义）。
写工具路由：根据任务关键词决定调用哪些工具、什么顺序。
跑通闭环并打印轨迹（每步调用与结果）。
输出 Markdown 结论，标注「已验证」与「待验证」。

产出：demo 脚本 + 一份 Markdown 结论 + 轨迹记录。

task = "帮我分析 10:00-11:00 Nginx CPU 升高可能原因"
metrics = query_metrics("nginx_cpu", "10:00", "11:00")
logs = query_logs("10:00", "11:00", keyword="ERROR")
summary = summarize(metrics, logs)  # 汇总异常时间点，标注已验证/待验证
print(summary)  # Markdown 结论

输出模板

Demo 骨架:
1. 输入任务: [一句话任务]
2. 工具路由: [任务 -> 调用哪些工具、什么顺序]
3. 工具调用: [每个工具的入参与返回摘要]
4. 汇总分析: [异常时间点、关键发现]
5. 输出结论: Markdown，含「已验证」与「待验证」标签
6. 轨迹记录: [每步决策与失败处理]

Markdown 结论模板:
# Nginx CPU 分析结论
分析时段: [10:00-11:00]
异常时间点: [xxx]（已验证: 指标数据）
可能原因: [xxx]
- 已验证: [证据来源]
- 待验证: [需要进一步查询 xxx]

示范输出

输入: 帮我分析 10:00-11:00 Nginx CPU 升高可能原因
工具路由: query_metrics(nginx_cpu) -> query_logs(keyword=ERROR)
调用结果:
- query_metrics: 10:20-10:35 CPU 从 20% 升到 85%，10:25 达到峰值
- query_logs: 10:21-10:30 出现大量 upstream timeout，约 300 条
汇总: 异常集中在 10:20-10:35，与上游超时时间段重合

# Nginx CPU 分析结论
分析时段: 2026-08-14 10:00-11:00
异常时间点: 10:20-10:35（已验证: 指标曲线）
可能原因: 上游接口超时导致大量重试，worker 被打满
- 已验证: CPU 指标与 ERROR 日志时间吻合
- 待验证: 具体是哪个 upstream 节点超时，需查 upstream 日志

轨迹记录:
- 10:00-11:00 参数合法
- query_metrics 成功返回 60 个点
- query_logs 成功返回 300 条 ERROR，无空结果
- 结论中 2 条已验证、1 条待验证

追问练习

如何把这个 Demo 扩展成生产工具？从 Day 16-19 的产物里选 5 件必须做的事。
query_logs 返回为空时，你如何区分「真的没日志」和「时间格式传错了」？
Demo 里「待验证」的比例多少算合理？全是已验证说明什么？
用 Day 19 的流程骨架套这个 Demo，哪一步没有被覆盖？

常见误区

用假数据骗过自己：Demo 跑通不等于逻辑对，要保留轨迹检查每一步。
结论全标「已验证」：没有工具证据支撑的结论必须标「待验证」。
工具路由写死：换一个任务就转不动，路由要和工具描述对应。
只做 happy path：不测空结果与工具失败，交付物缺失败处理。

进阶扩展

从 Demo 到生产：鉴权、限流、评估集、审计日志、人工确认。
用 trace 驱动改进：回看轨迹发现「工具白调」「参数错传」这类浪费。
复用阶段产物：权限矩阵接进执行层，工具定义直接进 schema。

今日作业

跑通 Demo，保存脚本与运行轨迹。
输出一份 Markdown 分析结论。
整理 Day 16-19 的四份产物为阶段交付物清单（工具 schema 设计、权限与风险清单、MCP 架构、Coding Agent 流程）。
写出 Demo 的 3 个已知局限，作为下一阶段改进输入。

自检清单

我能让 Agent 调用 2-3 个工具完成一次完整分析。
我能区分「已验证」与「待验证」结论。
我能判断工具返回空结果是否异常。
我能说出 Demo 到生产的差距。
我能整理出 Day 16-19 的交付物清单。