Agent 流程调试与问题排查实战

2026-06-10调试Agent问题排查

Agent 开发中的三大调试难题

与传统软件不同，Agent 的调试面临三个核心挑战：(1) 非确定性——同样的输入可能产生不同输出，(2) 长链路——从输入到输出经过多层推理，难以定位问题，(3) 黑盒——LLM 的内部推理过程不可见。

问题一：ReAct 循环陷入死循环

症状

Agent 不断重复相同的 Thought-Action-Observation 循环，消耗大量 Token 但无法推进任务。

排查方法

  1. 检查日志中重复的 Action 序列——如果最近 3 步完全相同，几乎可以确定是死循环
  2. 检查工具返回结果是否符合预期——工具返回空值或格式错误时，Agent 容易重试
  3. 检查是否有"应该结束但没有结束"的信号——Agent 拿到了最终答案但仍在思考

解决方案

  • 硬限制：设置 max_steps（建议 10-15），超过后强制中断并要求总结
  • 重复检测：缓存最近 N 步的 action+args 哈希，检测到重复时注入"你已经尝试过这个操作，请换一种方式"
  • 进度注入：每 3 步在 Observation 中追加进度提示："已完成 X/Y 步，请评估是否已拿到足够信息回复用户"
  • 超时熔断：总推理时间超过阈值（如 60s）时强制终止
MAX_STEPS = 12
action_hashes = []

for step in range(MAX_STEPS):
    thought, action, args = agent.think()
    h = hash((action, str(args)))
    if action_hashes.count(h) >= 2:
        observation += "\n[SYSTEM] 已重复执行此操作 2 次，请尝试不同方法或直接给出最佳答案。"
    action_hashes.append(h)
    observation = agent.act(action, args)
    if agent.should_finish(observation):
        break

问题二：工具调用参数错误（参数幻觉）

症状

Agent 调用工具时传入不存在的参数名、错误类型、或编造参数值。

排查方法

  1. 在工具执行前加参数校验层，记录所有校验失败
  2. 对比 Agent 生成的参数和工具的 JSON Schema 定义
  3. 统计高频错误参数，针对性优化工具描述

解决方案

  • Schema 先行校验：用 JSON Schema 验证参数，失败时返回明确的错误信息（含正确格式示例）
  • 工具描述优化：在 function description 中给出参数示例，enum 值明确列出
  • 二次确认机制：对关键操作（如删除、发送），让 Agent 先输出确认意图，再执行
def safe_call(func, args):
    try:
        jsonschema.validate(args, func.schema)
    except ValidationError as e:
        return {"error": f"参数错误: {e.message}", "correct_format": func.schema_example}
    return func(**args)

问题三：RAG 检索质量差

症状

Agent 检索到的文档与用户问题无关，导致回答偏离主题或使用错误知识。

排查方法

  1. 单独测试检索 Pipeline：用相同 query 直接调检索，看返回文档是否相关
  2. 检查 embedding 模型是否与文档类型匹配（中文文档用中文 embedding 模型）
  3. 打印检索得分，低于阈值的文档应该被过滤

解决方案

  • 混合检索：BM25（关键词）+ 向量（语义）双路召回，RRF 融合
  • Re-rank：初检索后加一层重排序（BGE Reranker/Cohere），过滤低分文档
  • 查询重写：用户问句先经 LLM 扩展/改写，提高检索命中率
  • 分块策略优化：根据文档类型选择分块大小（代码 200 tokens，文档 500 tokens）

问题四：上下文窗口溢出

症状

长对话或多轮工具调用后，上下文超过模型窗口限制，Agent 行为异常或直接报错。

解决方案

  • 滑动窗口：只保留最近 N 轮对话，旧消息压缩为摘要
  • 工具结果截断：工具返回超过 2000 字符自动截断 + 摘要
  • 记忆外置：重要信息存入向量数据库/结构化记忆，用时检索
  • Token 预算监控：每次推理前检查 token 余量，不足时触发压缩

问题五：Orchestrator 路由错误

症状

多 Agent 系统中，用户请求被路由到错误的 Specialist Agent。

解决方案

  • 意图分类前置：用专门的小模型做意图分类（比通用 LLM 更准确且更便宜）
  • 置信度阈值：分类置信度 < 0.7 时追问用户澄清
  • 路由日志审计：记录所有路由决策，定期审查误路由 case

调试工具箱

工具用途
LangSmith / LangFuse全链路 Trace，每一步的 prompt/tool call/output 可视
结构化日志JSON 格式日志，包含 step_id、action、input、output、duration、tokens
回放测试记录真实用户输入，回归时重放验证
A/B 对比同一输入发两份请求，对比不同 Prompt/模型的输出差异

调试心智模型

Agent 调试的核心思路：缩小不确定性范围。从最外层（LLM 输出）向内层（Prompt → Tool 结果 → 检索质量）逐层排查，每一层都要有可验证的断言。

← 返回首页

未标记