/做了一个线上故障排查 AI 工具，才真正想清楚 Agent 的边界在哪里/

这篇文章想复盘一个我以前做过的线上故障排查 AI 工具。

这个工具来自一个很高频的后端研发场景：线上接口报错后，工程师需要根据 trace_id、错误码或者异常栈，快速找到问题发生在哪里、可能原因是什么、代码应该怎么改。

在做这个工具的时候，我给每个功能模块都起了一个 *_agent.py 的名字。

但最近重新整理这版代码时，我意识到一件事：这些模块里，没有一个符合今天 Agent 工程的定义。它们是工具、是 workflow step，但不是 Agent。

这不只是一个命名问题。它让我重新想清楚了一个更根本的工程问题：tool、workflow 和 Agent，在工程上到底怎么区分？

这篇文章先不急着给定义，而是按真实顺序讲：这个工具是为了解决什么问题、当时怎么实现、它做对了什么，最后再回头用 V1 的真实案例，把这三个概念的工程边界说清楚。

1

线上故障排查到底麻烦在哪

后端工程师都知道，线上故障排查很多时候不是“不知道理论”，而是信息太散。

一个问题来了，入口可能很简单：

• 一个 trace_id
• 一个接口路径和错误码
• 一段异常栈
• 一条用户反馈
• 一个报警信息

但真正开始排查后，工程师要在很多地方来回切换。

比如，拿到一个 trace_id 后，通常要去日志平台查请求日志。日志里会有大量字段：请求参数、响应结果、错误码、异常信息、调用链、服务名、时间戳。工程师需要从这些字段里挑出真正有用的信息。

如果拿到的是异常栈，也不是简单看第一行就能结束。真实项目里的异常栈经常混着业务代码、Spring AOP、事务拦截、RPC 框架、线程池和各种基础设施调用。你需要判断哪个栈帧才是业务代码，哪个方法、哪一行最可能是问题现场。

找到可疑代码后，还要回到本地代码库，根据类名、文件名和行号定位源码，查看异常行附近的上下文。很多问题不能只看一行代码，还要看前后变量怎么来、参数是否可能为空、状态流转是否完整。

这些工作有两个特点：

• 很重复。
• 很依赖上下文。

所以我当时想做的不是“让 AI 替代工程师”，而是先让 AI 帮工程师完成第一轮排查，把最机械、最耗时的步骤串起来。

我希望这个工具至少能做这些事：

1拿到 trace_id / 错误码 / 异常栈2-> 自动查询日志3-> 提取关键异常和请求上下文4-> 分析异常栈5-> 定位源码文件和行号6-> 汇总证据7-> 给出初步根因和修复建议

这就是 V1 的起点。

2

V1 做成了什么样

当时团队只给员工开通了 Claude Code 订阅，并没有提供可供程序调用的 LLM API。基于这个约束，V1 的分工很直接：日志查询、异常栈解析、代码定位由 Python 程序完成；根因分析和修复建议交给 Claude Code。

虽然工程师只能在终端里与 Claude Code 手动交互，但 V1 没有做成一个只能在终端里运行的脚本。

原因很简单：线上故障排查本身就是一个需要反复查看信息的过程。如果只在命令行里输出一大段文本，使用起来并不方便。工程师需要一个页面来输入 trace_id、错误码或者异常栈，也需要一个页面把日志、异常分析、代码定位、根因分析和修复建议分块展示出来。

所以 V1 做了一个可视化页面。技术上用的是 Streamlit，它适合快速搭建内部工具页面。

用户打开页面后，可以选择诊断方式：

• trace_id 诊断
• 接口路径 + 错误码诊断
• 异常栈诊断

输入信息后，系统会按照固定流程执行诊断，并把每一步结果展示出来。

整体流程大致是：

1输入 trace_id / 错误码 / 异常栈2-> 查询日志3-> 提取异常、请求参数、服务调用信息4-> 分析异常栈5-> 定位源码文件和行号6-> 调用 Claude Code 做根因分析7-> 调用 Claude Code 生成修复建议8-> 在 Web UI 展示结果并生成报告

换成流程图，大概是这样：

1flowchart TD2    A["用户输入：trace_id / 错误码 / 异常栈"] --> B["可视化诊断页面"]3    B --> C["固定诊断流程"]4    C --> D["日志查询"]5    D --> E["异常栈分析"]6    E --> F["代码定位"]7    F --> G["Claude Code 根因分析"]8    G --> H["Claude Code 修复建议"]9    H --> I["结果展示 / JSON 报告"]

这个 Web UI 的价值是，它让工具从“我本地跑一个脚本”变成了“工程师可以打开页面使用的内部工具”。

页面里可以看到日志查询结果、异常分析、代码定位、根因分析、解决方案和详细信息，也可以下载诊断报告。

下面是 V1 当时的几个页面示例，截图已经做过脱敏处理。

异常栈诊断入口：

代码定位结果：

修复建议结果：

3

V1 的代码结构

V1 的代码结构大致是这样：

1v1-ai-assisted-workflow/2├── src/3│   ├── app.py  # Streamlit UI + workflow 编排4│   └── agents/5│       ├── trace_log_query_agent.py6│       ├── stack_trace_analyze_agent.py7│       ├── code_locator_agent.py8│       ├── root_cause_analysis_agent.py9│       └── solution_suggest_agent.py10├── config.example.json11├── requirements.txt12└── start_app.sh

这里先不急着讨论这些文件名里的 agent 是否准确，先看每个模块做了什么。

3.1

日志查询

trace_log_query_agent.py 负责根据 trace_id 或错误码查询日志。

它做的是确定性检索，不是模型推理：

• 拼接日志查询条件。
• 请求日志平台。
• 提取异常信息。
• 提取请求参数。
• 提取服务调用信息。
• 从错误码日志里反查 trace_id。

3.2

异常栈分析

stack_trace_analyze_agent.py 负责分析异常栈。

它会根据包名、类名、方法名和栈帧位置，判断哪些栈帧更像业务代码，哪些更像框架调用。

它的目标不是解释所有栈帧，而是尽快找到最可能有价值的业务栈帧，比如某个 service 方法和具体行号。

3.3

代码定位

code_locator_agent.py 负责根据异常栈定位源码。

它会根据类名、文件名、行号和本地项目路径，找到对应源码文件，并提取问题行附近的代码上下文。

今天看，Claude Code 本身已经有很强的代码库理解能力，所以这个模块确实有一部分重复造轮子的成分。

但它也有工程价值。

它做的是 code grounding：先用确定性程序把异常栈定位到具体文件、行号和代码片段，再把压缩后的上下文交给 Claude Code。

这比把一堆日志和代码全部丢给模型更可控。

3.4

根因分析和修复建议

真正调用 Claude Code 的地方主要是两个模块：

• root_cause_analysis_agent.py
• solution_suggest_agent.py

根因分析模块会把日志、异常栈和源码上下文组织成提示词，让 Claude Code 分析可能原因。

修复建议模块会把问题文件、问题行、根因描述和代码片段交给 Claude Code，让它生成修改建议。

当时的提示词很朴素，但方向是对的：

不是空问模型，而是把日志、异常栈和源码作为证据交给模型。

4

V1 做对了什么

V1 现在看很粗糙，但它有几个方向是对的。

第一，它解决的是一个真实工程问题。

线上故障排查不是聊天 demo，它涉及日志、异常栈、源码、请求参数、服务调用链和报告输出。V1 至少证明了这条流程可以被自动化一部分。

第二，它没有空问模型。

在调用 Claude Code 前，系统会先收集日志、异常栈和源码上下文。给模型的不是一句"帮我看看哪里出错了"，而是日志、栈、代码都备齐的上下文。

第三，它把确定性任务和 LLM 任务做了初步分工。

日志查询、异常栈解析、代码定位主要由 Python 程序完成；根因分析和修复建议交给 Claude Code。

这给后续版本留下了一个很重要的设计原则：

工具负责收集和约束上下文，模型负责理解和生成。

5

tool、workflow 和 Agent，工程上怎么区分

讲完背景和实现，再回头看当时的命名问题就比较自然了。

V1 里很多文件都叫 *_agent.py。要判断这个命名是否准确，先要说清楚这三个概念在工程上的区别。

Tool（工具）

确定性执行，输入输出固定，没有自主决策。给定相同的输入，每次返回相同类型的结果。日志查询、代码检索、异常栈解析，都是这类。

Workflow Step（工作流步骤）

由编排层按固定顺序调用的执行单元。可以包含 LLM 调用，但执行路径是开发时写死的，不会根据中间结果自主调整下一步做什么。

Agent

有自主决策能力。能根据当前上下文选择调用哪个工具、决定下一步做什么、判断什么时候可以停止。执行路径是运行时动态决定的，不是提前写死的。

判断一个模块是不是 Agent，可以问三个问题：

1. 它的执行路径是开发时写死的，还是运行时自主决定的？
2. 它能根据中间结果调整下一步做什么吗？
3. 它知道什么时候该停止吗？

用这三个问题重新审视 V1 的每个模块：

V1 里没有一个模块能对这三个问题给出肯定答案。所以它是一个 AI-assisted workflow，而不是 Agent Harness。

这不是说 V1 做错了。对一个验证阶段的工具来说，固定 workflow 是务实的选择。但它暴露出几个工程化不足的地方，值得逐一复盘。

5.1

Workflow 是写死的

trace_id 怎么诊断、错误码怎么诊断、异常栈怎么诊断，都是代码里固定好的函数调用。

这适合快速验证，但还不是一个可配置、可追踪、可评测的 Agent Harness。

5.2

工具没有统一 schema 和边界

V1 中每个模块都有自己的输入输出格式，主要靠 Python dict 串联。

它没有统一的 tool schema，也没有工具注册中心、工具白名单和权限边界。

在线上故障排查场景里，这个问题很关键。因为工具可能访问日志、数据库、配置、监控系统和代码库。工具越强，越需要边界。

5.3

LLM 调用缺少治理

V1 是通过 subprocess 调用 Claude Code CLI。

这在当时是可行方案，但工程化能力不足：

• 没有统一 LLM client。
• 没有 timeout。
• 没有 retry。
• 没有 fallback。
• 没有 token、cost、latency 记录。
• 没有结构化输出约束。
• 没有 prompt 版本记录。

系统能跑，不代表它已经可治理。

5.4

Prompt 还比较朴素

V1 的提示词只是把日志、异常栈和代码片段交给 Claude Code，让它总结根因和修改建议。

它没有进一步要求模型：

• 区分事实、推测和置信度。
• 引用日志、异常栈和源码证据。
• 在证据不足时不要强行下结论。
• 把修复建议拆成临时止血、长期修复和验证步骤。
• 输出固定结构，方便后续解析和评估。

5.5

Trace 和 eval 不是一等公民

V1 可以生成最终诊断报告，但这不等于 Agent trace。

更成熟的系统应该记录：

• 每一步什么时候开始、什么时候结束。
• 每一步输入了什么、输出了什么。
• 调用了哪些工具。
• 调用了哪次 LLM。
• 使用了哪个 prompt 版本。
• 失败在哪里，是否重试，是否 fallback。
• 最终结果是否命中预期。

没有 trace，就很难复盘。没有 eval，就很难判断一次修改到底让系统变好了还是变差了。

Agent 系统里，不是什么都应该交给模型。

尤其是线上故障排查这种生产场景。

日志查询、异常栈解析、代码定位、上下文裁剪、权限控制、执行记录，这些事情更适合由工具和 harness 控制。

LLM 更适合做基于证据的理解、归纳、解释和建议生成。

如果让模型完全自由发挥，它可能看起来很智能，但系统很难稳定、可控、可审计。

所以我现在更倾向于把这类系统设计成 workflow-first：

1问题分类2-> 上下文解析3-> workflow 路由4-> 受控工具调用5-> LLM 基于证据分析6-> trace 记录7-> eval 回归

这不是为了限制模型，而是为了让模型在正确的边界内发挥作用。

6

V1 如何引出后续优化

V1 的价值是跑通了真实场景的最小闭环。

但它暴露出来的问题，也自然引出了后续优化方向。

V2 的重点是尝试框架化。

当工具越来越多、场景越来越多时，硬编码 workflow 很难继续扩展。所以 V2 尝试使用开源 Agent 框架，把日志查询、代码分析、数据库诊断等能力做成更明确的 tools，并构建一个更像 workbench 的使用体验。

V3 的重点则是回到 lightweight harness。

因为生产故障排查不是完全自由聊天场景，它更需要：

• 问题分类。
• 上下文预解析。
• workflow 路由。
• step 级工具白名单。
• prompt builder。
• trace 持久化。
• eval 回归。

这三版并不是“一开始就做对了”，而是从真实问题出发，不断修正 Agent 工程认知。

7

结尾

这个项目已整理成脱敏公开仓库，感兴趣可以看：https://github.com/second-curve-engineer/sre-troubleshooting-agent-evolution

我刻意没有把 V1 包装成成熟 Agent。对一个工程项目来说，说清楚它不是什么，和说清楚它是什么一样重要。

V1 不是成熟 Agent，但它是一个真实问题驱动的 AI 工程原型。

它让我更清楚地区分了几件事：

• tool 不等于 Agent。
• workflow step 不等于 Agent。
• LLM 调用不等于 Agent。
• 能跑通不等于可观测、可评测、可治理。

对线上故障排查这类场景来说，Agent 工程化的关键不是让模型自由发挥，而是让模型在可控 workflow、明确工具边界和可追踪证据链里发挥作用。

这也是我后续继续打磨这个项目的方向。