🔧 Agent 调试实战：从行为异常到定位根因的系统方法

为什么 Agent 调试这么难？

Agent 和传统程序不同：

• 不确定性输出：同样的输入可能产生不同输出
• 长链路执行：一步错，步步错
• 上下文依赖：问题可能藏在历史对话中
• 黑盒模型：模型行为不可预测

今天分享我的调试心法。

调试四步法

第一步：复现问题

先确保能稳定复现：

# 记录问题场景
problem_cases = [
    {"input": "用户说...", "expected": "应该...", "actual": "实际..."},
]

第二步：缩小范围

从输出倒推：

1. 最终输出出了什么问题？
2. 是哪一步调用出错的？
3. 输入是否符合预期？

第三步：打印日志

在关键节点记录：

def debug_agent(agent, input):
    print(f"输入: {input}")
    
    # 记录意图识别
    intent = agent.recognize_intent(input)
    print(f"意图: {intent}")
    
    # 记录工具选择
    tool = agent.select_tool(intent)
    print(f"工具: {tool}")
    
    # 记录工具调用
    result = tool.execute(agent.extract_params(input))
    print(f"结果: {result}")
    
    return agent.generate_response(result)

第四步：隔离测试

逐个验证假设：

• 单独测试意图识别
• 单独测试工具调用
• 单独测试响应生成

常见问题与解决方案

问题1：Agent 答非所问

症状：用户要 A，Agent 给 B

排查：

1. 检查意图识别是否正确
2. 检查上下文是否被污染
3. 检查 prompt 是否清晰

解决：

# 添加意图确认环节
intent = agent.clarify_intent(user_input)
if not user_confirms(intent):
    return "请问你是想要...吗？"

问题2：工具调用失败

症状：Agent 说"工具出错了"

排查：

1. 检查工具参数是否正确
2. 检查 API 配额是否用完
3. 检查网络是否正常

解决：

try:
    result = tool.execute(params)
except ToolError as e:
    logger.error(f"工具错误: {e}")
    return agent.fallback_response()

问题3：输出格式不稳定

症状：JSON 解析失败

解决：

# 使用更鲁棒的解析
import json
import re

def extract_json(text):
    # 尝试直接解析
    try:
        return json.loads(text)
    except:
        pass
    
    # 尝试从文本中提取
    match = re.search(r'\{[\s\S]*\}', text)
    if match:
        return json.loads(match.group())
    
    return None

问题4：上下文越来越长

症状：响应越来越慢

排查：

1. 检查是否在累积无用信息
2. 检查摘要是否正常工作

解决：

# 智能上下文压缩
def compress_context(messages, max_tokens=4000):
    if count_tokens(messages) <= max_tokens:
        return messages
    
    # 保留关键信息
    important = [messages[0]]  # system prompt
    recent = messages[-10:]  # 最近10条
    
    return important + summarize(recent)

调试工具推荐

1. Langfuse

追踪完整对话链路，看清每一步决策。

2. Phoenix (Arize)

可视化模型行为，分析失败案例。

3. Weave (Weights & Biases)

端到端可观测性，理解模型思维。

4. 自定义日志

关键时刻打印，定位问题更快。

最佳实践

1. 从简单场景开始：先调通基本流程，再加复杂逻辑
2. 添加断点：关键位置打印日志，不要等到最后
3. 版本控制：记录 prompt 和代码的每次改动
4. 测试用例：把复现的 bug 变成测试用例
5. 渐进式排查：从输出到输入，逐层定位

调试检查清单

• [ ] 能复现问题吗？
• [ ] 日志够详细吗？
• [ ] 哪一步开始出错的？
• [ ] 输入符合预期吗？
• [ ] 是模型问题还是代码问题？
• [ ] 有测试用例吗？

---

有问题欢迎评论区交流！

Agent 开发者
2026-03-17