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 执行可能包含以下记录:

text
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 中写着:

text
你是一个研究助手。

请根据已有证据判断信息是否充分。
如果证据不足,生成下一轮搜索查询。
如果证据充分,结束搜索并生成报告。

但运行时实际发送的消息可能是:

text
messages = [    {        "role": "system",        "content": system_prompt,    },    {        "role": "user",        "content": "研究 Agent 的持久化机制",    },    {        "role": "assistant",        "content": "证据已经充分,可以生成报告。",    },]

假如第三条消息是程序错误地拼接进去的历史内容,模型就可能受到错误上下文的影响。只检查 system_prompt 很难发现这个问题。

因此,排查 LLM 时,应该保存实际发送的完整消息结构,并结合以下几个方面检查:

  1. System Prompt 是否正确,是否包含互相矛盾的要求。
  2. 历史消息是否属于当前任务,有没有混入其他任务的内容。
  3. Tool 定义是否完整,参数类型、必填字段和工具描述是否准确。
  4. 检索结果是否相关,有没有把低质量或互相冲突的内容放进上下文。
  5. 上下文是否被截断,关键证据是否在发送前就丢失了。
  6. 模型返回结果是否符合预期格式,是否包含正确的工具调用信息。

如果实际消息正确,但模型仍然持续做出错误判断,可以进一步比较不同 Prompt、模型或采样参数的表现。此时需要结合 Testing 和 Evaluation 的结果,判断这是偶发输出问题,还是系统性的能力缺陷。

还有一点值得注意:如果使用支持工具调用的模型,模型返回的内容可能包含结构化的工具调用,而不只是普通文本。调试时应检查实际返回的工具名称、参数和结束标记,不能只看模型在界面上展示的文字。

四、排查 Tool:区分选择错误、执行错误和结果错误

Tool 相关问题至少可以分成三类,处理方式并不相同。

第一类是工具选择错误。 例如,Research Agent 明明需要搜索最新的框架文档,却调用了本地知识库检索工具。这可能是工具描述不清楚、工具数量过多、模型判断错误,或者上层流程没有限制工具选择范围。

第二类是工具执行错误。 例如,模型生成的搜索参数缺少必填字段,外部服务超时,接口返回 429,或者数据库连接失败。这类问题通常需要由程序处理,包括参数校验、重试、超时控制和降级。

第三类是工具返回结果错误或不符合预期。 工具可能执行成功,却返回空结果、过期内容、错误的数据结构,甚至返回了与查询主题无关的资料。HTTP 请求成功不等于业务结果正确。

可以为每次 Tool 调用记录一份结构化日志:

text
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 为例,可以定义一个简化的状态结构:

text
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 就可能在资料不足时提前生成报告。

因此,调试状态问题时,应同时检查节点执行前后的状态变化。

例如:

text
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 的流程中可能存在这样的循环:

text
搜索资料
   ↓
分析证据
   ↓
证据是否充分?
   ├── 是 → 生成报告
   └── 否 → 生成新查询 → 再次搜索

如果循环异常,至少要检查三个方面:

  • 退出条件是否正确。 证据检查结果是否被正确写入状态,条件分支是否读取了最新值。
  • 循环次数是否受控。 即使模型持续判断证据不足,程序也应该设置最大搜索轮数、时间或预算限制。
  • 重复执行是否有意义。 如果连续几轮使用相同查询,或者搜索结果没有变化,就需要考虑去重、查询调整和提前终止策略。

在 LangGraph 中,可以使用条件边决定下一步走向,也可以使用图级别的递归限制防止无限执行。不过,递归限制只能提供一道保护,不能替代合理的业务退出条件。程序仍然需要定义达到最大轮数、预算耗尽或连续无新证据时应该如何结束。

六、使用 LangGraph 和 LangSmith 还原执行轨迹

前面的排查方式适用于各种 Agent 实现。使用 LangGraph 时,图结构和节点边界可以帮助我们把执行过程拆分得更清楚。

例如:

text
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 排查问题时,可以先找到一次失败的运行记录,再逐层展开:

  1. 找到出错的节点或调用。
  2. 检查该步骤的输入和输出。
  3. 对照前一步的结果,判断错误从哪里开始出现。
  4. 检查后续步骤是否放大了这个错误。
  5. 将失败案例保存下来,用于后续回归测试。

例如,最终报告引用了错误的资料,可以先检查报告生成节点收到的证据,再向前追踪证据分析节点、搜索结果和实际查询参数。这样通常比直接修改最终报告的 Prompt 更容易找到根因。

LangSmith 的具体可观测能力取决于项目接入方式、运行环境和配置。即使没有使用 LangSmith,也可以通过结构化日志、OpenTelemetry Trace 或自建执行记录实现类似的基本排查流程。

七、如何复现问题:把失败案例变成可重复调试的输入

Agent 的一个麻烦之处是,同样的用户输入再次运行,可能走出不同的执行路径。如果每次排查都重新调用真实搜索服务和 LLM,结果可能发生变化,定位问题就会比较困难。

因此,需要区分两种调试方式。

第一种是重放已有执行过程。 保存当时的模型输入输出、工具参数和工具返回结果,然后在本地重放后续逻辑。这样可以排除外部数据变化的影响,重点检查状态更新、分支判断和报告处理代码。

第二种是重新运行任务。 使用相同的用户输入重新执行 Agent,观察当前模型和工具能否复现问题。这种方式更适合检查模型输出不稳定、Prompt 变化或外部服务状态变化等问题,但不能保证得到与原任务完全相同的结果。

如果要重放一次失败的 Research Agent 任务,可以保存如下记录:

text
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 或更换模型。

  1. 确认失败现象。 明确任务的预期结果和实际结果,尽量用具体案例描述问题。
  2. 找到对应的 Trace。 确认这是哪一次执行,定位出现异常的节点和调用。
  3. 从结果向前追踪。 先检查失败节点的输入,再检查上游节点的输出,寻找错误首次出现的位置。
  4. 判断问题归属。 区分模型判断、Prompt 组装、工具执行、状态更新和流程控制问题。
  5. 构造可重复案例。 保存必要的输入、模型响应、工具结果和状态,尽可能排除外部变化。
  6. 修复并验证。 根据根因修改代码、Prompt 或配置,再用原始失败案例验证。
  7. 补充回归测试。 将这次故障沉淀成自动化测试或 Evaluation 案例,并观察修改是否影响其他任务。

如果一次失败任务包含多个问题,最好逐一处理。例如,工具返回了不相关的数据,模型又错误地将其判断为充分证据,最终报告还遗漏了引用来源。这三个问题可能互相影响,但根因并不相同。需要分别确认数据检索、证据判断和报告生成是否符合预期。

在团队开发中,还应该保留 Prompt 版本、模型版本、工具版本和代码版本。否则,即使重现了相同输入,也无法确定当前运行环境是否与问题发生时一致。

十、总结

Agent Debugging 的核心是还原执行过程,沿着输入、模型调用、工具执行、状态变化和分支判断逐步定位问题。最终输出只能告诉我们任务失败了,完整的执行轨迹才能帮助我们判断失败发生在哪一步。

LangGraph 提供了清晰的节点和流程边界,Checkpoint 可以帮助检查状态快照,LangSmith 等可观测工具可以帮助查看调用轨迹。它们能降低定位问题的成本,但不能代替业务日志、错误分类和合理的程序控制。

实际开发中还有一个值得坚持的习惯:每修复一个可复现的问题,就把它沉淀为测试用例。 Agent 的执行路径可能变化,模型输出也可能变化,但系统已经识别过的故障,不应该每隔一段时间就重新出现。

希望这篇文章能对你有所帮助。关注我,持续分享更多实用、好用的 AI 干货。

本文目录