Session 26:Agent Debugging——如何定位和排查 Agent 的问题
传统后端程序出现问题时,通常可以沿着调用链排查:请求进入哪个接口,执行了哪些方法,在哪一步抛出异常,输入参数和返回值是什么。
一、Agent 为什么难调试
传统后端程序出现问题时,通常可以沿着调用链排查:请求进入哪个接口,执行了哪些方法,在哪一步抛出异常,输入参数和返回值是什么。只要日志足够完整,问题通常可以逐步缩小到某个方法或某段代码。
Agent 的调试要复杂一些。一次任务可能经历多轮 LLM 调用、多个 Tool、状态更新、条件分支和循环。即使输入完全相同,模型也可能生成不同的内容,进而选择不同的工具或执行路径。
以 Research Agent 为例,用户要求研究某个技术主题,Agent 需要搜索资料、分析内容、检查证据是否充分,必要时继续搜索,最后生成报告。如果最终报告存在问题,可能的原因包括:
- 搜索范围不合理,遗漏了重要资料。
- LLM 错误理解了工具的返回结果。
- Tool 参数不正确,导致搜索结果偏离主题。
- 状态更新有误,已经搜索过的资料没有被记录。
- 证据不足,但模型错误地判断为充分。
- 循环退出条件不合理,导致提前结束或反复搜索。
- 最终报告生成阶段丢失了前面收集的重要证据。
这些问题最终都可能表现为同一种现象:报告质量不高。仅仅检查最终输出,很难判断问题究竟出在哪里。
因此,Agent 调试首先需要解决一个基础问题:把一次任务的完整执行过程还原出来,而不只是观察最后的答案。
二、先建立一次 Agent 执行的完整记录
调试 Agent 时,需要知道每一步发生了什么,以及这一步为什么发生。
一次典型的 Agent 执行过程,可以记录以下信息:
| 记录内容 | 主要用途 |
|---|---|
| 用户输入 | 确认任务的原始要求 |
| 实际发送给 LLM 的消息 | 检查 System Prompt、历史消息和运行时上下文 |
| 模型返回结果 | 判断模型是否正确理解任务、选择工具 |
| Tool 调用参数 | 检查工具名称、查询词和其他参数 |
| Tool 执行结果 | 判断外部数据是否正确返回 |
| Agent State 变化 | 检查任务进度、证据和执行状态 |
| 分支判断 | 确认为什么继续搜索、结束任务或进入其他节点 |
| 异常和重试记录 | 判断故障发生在哪里,以及系统如何恢复 |
| 最终输出 | 检查中间过程与最终结果是否一致 |
这些信息可以关联到同一次任务,并为每个步骤分配唯一标识。实际工程中通常会使用 run_id、trace_id、span_id 等字段区分任务、调用链和具体操作。
例如,一次 Research Agent 执行可能包含以下记录:
run_id: research-001
[Step 1] receive_task
input:
topic = "Agent 的持久化机制"
[Step 2] llm_call
purpose:
determine_search_strategy
output:
search_query = "LangGraph checkpoint persistence"
[Step 3] tool_call
tool:
web_search
arguments:
query = "LangGraph checkpoint persistence"
[Step 4] tool_result
status:
success
result_count:
8
[Step 5] analyze_evidence
evidence_count:
5
sufficient:
false
[Step 6] llm_call
purpose:
generate_followup_query
output:
search_query = "LangGraph checkpoint recovery limitations"
通过这份记录,可以看出 Agent 为什么进行了第二轮搜索,以及第二轮搜索使用了什么查询词。如果最终报告遗漏了持久化机制的限制,就可以继续检查后续分析与报告生成阶段。
需要注意的是,日志应记录必要的上下文,但不必无差别保存所有数据。对于敏感信息、超长文档和大量工具返回结果,可以采用脱敏、摘要、引用标识或独立存储的方式,避免日志本身成为新的成本和安全问题。
三、排查 LLM:先看实际发送了什么
LLM 的问题经常被简单归结为模型能力不足,但在排查之前,需要先确认模型实际收到了什么。
开发时看到的 Prompt 模板,不一定等于运行时真正发送的消息。程序可能追加历史对话、工具执行结果、检索内容、动态指令或任务状态。上下文组装出现问题时,即使模板本身没有问题,模型也可能得到错误或不完整的信息。
例如,开发者原本希望模型根据证据判断是否继续搜索,System Prompt 中写着:
你是一个研究助手。
请根据已有证据判断信息是否充分。
如果证据不足,生成下一轮搜索查询。
如果证据充分,结束搜索并生成报告。
但运行时实际发送的消息可能是:
messages = [ { "role": "system", "content": system_prompt, }, { "role": "user", "content": "研究 Agent 的持久化机制", }, { "role": "assistant", "content": "证据已经充分,可以生成报告。", },]
假如第三条消息是程序错误地拼接进去的历史内容,模型就可能受到错误上下文的影响。只检查 system_prompt 很难发现这个问题。
因此,排查 LLM 时,应该保存实际发送的完整消息结构,并结合以下几个方面检查:
- System Prompt 是否正确,是否包含互相矛盾的要求。
- 历史消息是否属于当前任务,有没有混入其他任务的内容。
- Tool 定义是否完整,参数类型、必填字段和工具描述是否准确。
- 检索结果是否相关,有没有把低质量或互相冲突的内容放进上下文。
- 上下文是否被截断,关键证据是否在发送前就丢失了。
- 模型返回结果是否符合预期格式,是否包含正确的工具调用信息。
如果实际消息正确,但模型仍然持续做出错误判断,可以进一步比较不同 Prompt、模型或采样参数的表现。此时需要结合 Testing 和 Evaluation 的结果,判断这是偶发输出问题,还是系统性的能力缺陷。
还有一点值得注意:如果使用支持工具调用的模型,模型返回的内容可能包含结构化的工具调用,而不只是普通文本。调试时应检查实际返回的工具名称、参数和结束标记,不能只看模型在界面上展示的文字。
四、排查 Tool:区分选择错误、执行错误和结果错误
Tool 相关问题至少可以分成三类,处理方式并不相同。
第一类是工具选择错误。 例如,Research Agent 明明需要搜索最新的框架文档,却调用了本地知识库检索工具。这可能是工具描述不清楚、工具数量过多、模型判断错误,或者上层流程没有限制工具选择范围。
第二类是工具执行错误。 例如,模型生成的搜索参数缺少必填字段,外部服务超时,接口返回 429,或者数据库连接失败。这类问题通常需要由程序处理,包括参数校验、重试、超时控制和降级。
第三类是工具返回结果错误或不符合预期。 工具可能执行成功,却返回空结果、过期内容、错误的数据结构,甚至返回了与查询主题无关的资料。HTTP 请求成功不等于业务结果正确。
可以为每次 Tool 调用记录一份结构化日志:
import timeimport uuiddef execute_tool(tool, arguments): call_id = str(uuid.uuid4()) start = time.time() log = { "call_id": call_id, "tool_name": tool.name, "arguments": arguments, } try: result = tool.invoke(arguments) log.update({ "status": "success", "duration_ms": round( (time.time() - start) * 1000 ), "result_type": type(result).__name__, }) return result except Exception as exc: log.update({ "status": "error", "duration_ms": round( (time.time() - start) * 1000 ), "error_type": type(exc).__name__, "error_message": str(exc), }) raise finally: print(log)
这段代码主要演示记录方式。生产环境需要使用正式日志系统,并根据异常类型决定是否重试、降级或交给上层流程处理;直接打印日志也不适合高并发服务。
调试时还应检查参数是否符合预期、返回数据是否满足业务约束,以及重试是否产生了副作用。例如,查询接口通常可以安全重试,但发送邮件、创建订单等操作可能重复执行,必须考虑幂等性。
如果 Tool 本身运行正常,但模型总是生成错误参数,可以继续检查工具的 Schema 和描述。如果模型生成了正确参数,工具却返回异常,则应重点排查工具实现和外部依赖。把这几种情况区分开,才能避免在错误的地方反复修改 Prompt。
五、排查 State 和流程:重点检查状态变化
Agent 的很多问题并不发生在 LLM 调用中,而是发生在状态管理和流程控制中。
以 Research Agent 为例,可以定义一个简化的状态结构:
from typing import TypedDictclass ResearchState(TypedDict): topic: str search_queries: list[str] evidence: list[dict] search_round: int evidence_sufficient: bool report: str
每轮搜索完成后,程序应该将查询词、搜索结果和搜索轮数写回状态。证据检查节点读取这些信息,再决定是否继续搜索。
如果某个节点没有正确更新 evidence,后续节点就可能误以为没有收集到资料;如果 search_round 没有递增,循环退出条件就可能永远无法满足;如果 evidence_sufficient 被错误设置为 True,Agent 就可能在资料不足时提前生成报告。
因此,调试状态问题时,应同时检查节点执行前后的状态变化。
例如:
def debug_node(node_name, state_before, state_after): print({ "node": node_name, "before": state_before, "after": state_after, })
真实项目中,完整 State 可能包含大量文档和消息,不适合直接打印。更合理的方式是记录关键字段的变化,例如搜索轮数、证据数量、当前阶段、分支判断结果和报告状态。
对于 LangGraph,还需要注意并行节点和状态合并的问题。如果多个节点在同一个 super-step 中并行运行,它们可能同时更新 State。此时要检查相关字段的 reducer 配置,以及多个节点更新同一个字段时是否符合预期。
循环问题需要单独排查
Research Agent 的流程中可能存在这样的循环:
搜索资料
↓
分析证据
↓
证据是否充分?
├── 是 → 生成报告
└── 否 → 生成新查询 → 再次搜索
如果循环异常,至少要检查三个方面:
- 退出条件是否正确。 证据检查结果是否被正确写入状态,条件分支是否读取了最新值。
- 循环次数是否受控。 即使模型持续判断证据不足,程序也应该设置最大搜索轮数、时间或预算限制。
- 重复执行是否有意义。 如果连续几轮使用相同查询,或者搜索结果没有变化,就需要考虑去重、查询调整和提前终止策略。
在 LangGraph 中,可以使用条件边决定下一步走向,也可以使用图级别的递归限制防止无限执行。不过,递归限制只能提供一道保护,不能替代合理的业务退出条件。程序仍然需要定义达到最大轮数、预算耗尽或连续无新证据时应该如何结束。
六、使用 LangGraph 和 LangSmith 还原执行轨迹
前面的排查方式适用于各种 Agent 实现。使用 LangGraph 时,图结构和节点边界可以帮助我们把执行过程拆分得更清楚。
例如:
from typing import Literalfrom langgraph.graph import StateGraph, START, ENDdef search(state): # 执行搜索并更新证据 return {}def analyze(state): # 分析当前证据是否充分 return {}def route_after_analysis( state) -> Literal["search", "report"]: if state["evidence_sufficient"]: return "report" return "search"def generate_report(state): # 根据证据生成报告 return {}builder = StateGraph(ResearchState)builder.add_node("search", search)builder.add_node("analyze", analyze)builder.add_node("report", generate_report)builder.add_edge(START, "search")builder.add_edge("search", "analyze")builder.add_conditional_edges( "analyze", route_after_analysis, { "search": "search", "report": "report", },)builder.add_edge("report", END)graph = builder.compile()
这里省略了具体的 LLM 调用和业务逻辑,重点是流程结构。调试时可以沿着 search → analyze → search 的执行轨迹检查每一轮的状态变化,确认循环为什么继续,以及最后为什么进入 report 节点。
如果启用了 LangGraph 的 Checkpointer,还可以查看相应线程的状态快照,分析任务在某个时间点保存了什么状态。需要注意,Checkpoint 保存的是图状态,不一定包含所有外部服务的执行细节。对于外部 API 请求、数据库修改等操作,仍然需要独立的业务日志和执行记录。
LangSmith 则可以帮助观察 LLM 调用、链路、工具执行及相关输入输出。使用 Trace 排查问题时,可以先找到一次失败的运行记录,再逐层展开:
- 找到出错的节点或调用。
- 检查该步骤的输入和输出。
- 对照前一步的结果,判断错误从哪里开始出现。
- 检查后续步骤是否放大了这个错误。
- 将失败案例保存下来,用于后续回归测试。
例如,最终报告引用了错误的资料,可以先检查报告生成节点收到的证据,再向前追踪证据分析节点、搜索结果和实际查询参数。这样通常比直接修改最终报告的 Prompt 更容易找到根因。
LangSmith 的具体可观测能力取决于项目接入方式、运行环境和配置。即使没有使用 LangSmith,也可以通过结构化日志、OpenTelemetry Trace 或自建执行记录实现类似的基本排查流程。
七、如何复现问题:把失败案例变成可重复调试的输入
Agent 的一个麻烦之处是,同样的用户输入再次运行,可能走出不同的执行路径。如果每次排查都重新调用真实搜索服务和 LLM,结果可能发生变化,定位问题就会比较困难。
因此,需要区分两种调试方式。
第一种是重放已有执行过程。 保存当时的模型输入输出、工具参数和工具返回结果,然后在本地重放后续逻辑。这样可以排除外部数据变化的影响,重点检查状态更新、分支判断和报告处理代码。
第二种是重新运行任务。 使用相同的用户输入重新执行 Agent,观察当前模型和工具能否复现问题。这种方式更适合检查模型输出不稳定、Prompt 变化或外部服务状态变化等问题,但不能保证得到与原任务完全相同的结果。
如果要重放一次失败的 Research Agent 任务,可以保存如下记录:
failed_case = { "topic": "Agent 的持久化机制", "search_queries": [ "LangGraph checkpoint persistence", ], "tool_results": [ { "query": "LangGraph checkpoint persistence", "documents": [ { "source": "official_docs", "content": "..." } ], } ], "expected_behavior": ( "证据不足时应继续搜索," "不能直接生成最终报告。" ),}
这只是简化示例。完整记录还可以包含 Prompt 版本、模型名称、关键状态、工具调用顺序、异常信息和相关代码版本。涉及敏感数据时,需要脱敏后再用于调试。
保存失败案例的价值在于:问题修复后,可以用同一份输入重新验证。如果之前的问题是循环提前结束,就检查现在是否能够正确进入下一轮搜索;如果问题是工具参数错误,就验证参数构造逻辑是否已经修复。
这也让 Debugging 和 Testing 连接起来。一次调试发现的问题,最好最终沉淀成一条自动化测试用例,避免后续修改再次引入同样的缺陷。
八、调试时要区分程序错误与模型判断错误
实际排查过程中,容易把所有异常现象都归结为 LLM 的问题。为了提高效率,可以先判断问题属于哪一类。
| 问题表现 | 优先检查的地方 |
|---|---|
| 模型没有调用应该使用的 Tool | Tool 描述、模型输入、工具选择策略 |
| Tool 参数缺失或格式错误 | Tool Schema、参数校验、模型返回 |
| Tool 执行超时或抛异常 | 超时设置、重试机制、外部依赖 |
| Tool 成功但数据不相关 | 查询构造、数据源、结果过滤 |
| Agent 反复执行同一任务 | State 更新、循环退出条件、去重逻辑 |
| 证据不足却提前结束 | 证据检查逻辑、分支条件、运行时上下文 |
| 最终报告遗漏关键证据 | 报告节点输入、上下文裁剪、生成 Prompt |
| 中断恢复后重复执行操作 | Checkpoint、外部副作用、幂等性 |
| 同一输入多次运行结果差异明显 | 模型随机性、外部数据变化、执行轨迹差异 |
表格只能帮助确定排查方向,不能直接证明根因。比如模型没有调用工具,既可能是工具描述不合理,也可能是程序在模型调用前就错误地结束了任务。最终仍然要根据实际执行记录判断。
另外,模型判断错误与程序控制错误需要分开处理。证据是否充分可以由模型提供语义判断,但最大循环次数、预算上限、超时、必填字段和权限检查应该由程序控制。即使模型做出了错误判断,程序也应该能够限制它造成的影响。
九、建立一套日常调试流程
Agent 出现问题时,可以按照以下顺序排查,避免一上来就修改 Prompt 或更换模型。
- 确认失败现象。 明确任务的预期结果和实际结果,尽量用具体案例描述问题。
- 找到对应的 Trace。 确认这是哪一次执行,定位出现异常的节点和调用。
- 从结果向前追踪。 先检查失败节点的输入,再检查上游节点的输出,寻找错误首次出现的位置。
- 判断问题归属。 区分模型判断、Prompt 组装、工具执行、状态更新和流程控制问题。
- 构造可重复案例。 保存必要的输入、模型响应、工具结果和状态,尽可能排除外部变化。
- 修复并验证。 根据根因修改代码、Prompt 或配置,再用原始失败案例验证。
- 补充回归测试。 将这次故障沉淀成自动化测试或 Evaluation 案例,并观察修改是否影响其他任务。
如果一次失败任务包含多个问题,最好逐一处理。例如,工具返回了不相关的数据,模型又错误地将其判断为充分证据,最终报告还遗漏了引用来源。这三个问题可能互相影响,但根因并不相同。需要分别确认数据检索、证据判断和报告生成是否符合预期。
在团队开发中,还应该保留 Prompt 版本、模型版本、工具版本和代码版本。否则,即使重现了相同输入,也无法确定当前运行环境是否与问题发生时一致。
十、总结
Agent Debugging 的核心是还原执行过程,沿着输入、模型调用、工具执行、状态变化和分支判断逐步定位问题。最终输出只能告诉我们任务失败了,完整的执行轨迹才能帮助我们判断失败发生在哪一步。
LangGraph 提供了清晰的节点和流程边界,Checkpoint 可以帮助检查状态快照,LangSmith 等可观测工具可以帮助查看调用轨迹。它们能降低定位问题的成本,但不能代替业务日志、错误分类和合理的程序控制。
实际开发中还有一个值得坚持的习惯:每修复一个可复现的问题,就把它沉淀为测试用例。 Agent 的执行路径可能变化,模型输出也可能变化,但系统已经识别过的故障,不应该每隔一段时间就重新出现。
希望这篇文章能对你有所帮助。关注我,持续分享更多实用、好用的 AI 干货。