前言
过去半年一直在做 AI Agent 相关的开发，从最简单的单步工具调用，到复杂的多 Agent 协作系统，踩了无数坑。这篇文章把真实的踩坑经历写出来，希望对正在入坑的你有帮助。
坑 1：Tool Call 死循环
现象：Agent 反复调用同一个工具，直到超出最大轮次限制。
真实案例：让 Agent 查询用户信息，返回空结果，Agent 又查一次，还是空，又查…
原因：没有告诉 Agent "查不到就承认查不到"。LLM 默认倾向于"再试一次"，除非你在 System Prompt 里明确约束。
解决：
// System Prompt 中加这条规则
如果工具返回空结果或错误，直接告诉用户查不到，不要重复调用同一工具超过 1 次。
坑 2：上下文爆炸（Context Overflow）
现象：对话进行几轮后，Token 消耗暴增，API 延迟变高，费用飙升。
原因：每一轮都把完整的工具调用记录塞进对话历史，包括那些巨长的返回值。
解决：
1. OpenAI 的 Token 节省策略：每次请求只保留最近的 N 轮对话 + 系统提示
2. 摘要压缩：当上下文超长时，把早期内容压缩成摘要
3. 结构化日志：工具返回值只保留关键字段，不要全量保留
# 不好的做法：把所有工具返回值都保留
messages.append({"role": "tool", "content": json.dumps(raw_result)})
# 好的做法：只保留关键信息
summary = {
"status": raw_result.get("status"),
"count": len(raw_result.get("items", [])),
"sample": raw_result.get("items", [])[:3]
}
messages.append({"role": "tool", "content": json.dumps(summary)})
坑 3：结构化输出解析失败
现象：模型返回的 JSON 格式不对，或者字段类型不匹配。
原因：LLM 对 JSON Schema 的理解和遵循能力参差不齐，复杂 Schema 下更容易出错。
解决：
1. 用 Function Calling 代替自由格式 JSON——让模型输出结构化数据的第一选择
2. 强制 JSON：在 Prompt 末尾加 请只输出 JSON，不要 markdown 不要代码块标记
3. 容错解析：正则提取 JSON + json.loads + 修正常见错误（单引号变双引号、去除末尾逗号等）
import re, json
def safe_parse_llm_output(text: str) -> dict:
# 尝试提取 ```json ... ``` 块
match = re.search(r'```(?:json)?\s*([\s\S]*?)```', text)
if match:
text = match.group(1)
# 尝试解析
try:
return json.loads(text)
except json.JSONDecodeError:
# 修复常见问题
text = text.replace("'", '"').replace(",}", "}").replace(",]", "]")
return json.loads(text)
坑 4：工具描述写得太随意
现象：Agent 经常调用错误的工具，或者传了错误的参数。
原因：工具描述写得不够清晰，或者参数说明不够详细。
经验：工具描述决定了 Agent 能不能正确使用它。好的描述格式：
{
"name": "search_knowledge_base",
"description": "搜索内部知识库，适用于查询产品文档、技术FAQ、运维手册。不要用来搜索天气、新闻等外部信息。",
"parameters": {
"query": {
"type": "string",
"description": "搜索关键词，应该包含核心业务术语，如「部署失败」而非「报错了」"
}
}
}
关键点：告诉 Agent 什么时候用 和 什么时候不用，参数描述要说清楚传什么内容。
坑 5：并行工具调用（Parallel Tool Calls）的顺序问题
现象：同时调用了多个工具，但有一个工具依赖另一个工具的结果。
原因：Claude 和 GPT-4 都支持一次返回多个 Tool Call，但 Agent 框架可能会并发执行，导致依赖数据没准备好。
解决：
- 在工具设计层面避免隐式依赖
- 如果必须依赖，分两步执行：第一轮拿到结果，第二轮用结果继续
- 工具名加前缀暗示顺序：step1_analyze → step2_generate
坑 6：用户反馈循环
现象：Agent 做错了，用户纠正后，Agent 说"好的已修改"，但其实没改。
原因：Agent 的意图理解和实际执行之间存在 gap。它可能只是口头上同意了，但没有真正触发相应的工具调用。
解决：
- 每次修改操作后，显式调用一个确认工具，把修改后的结果展示给用户
- 不要让 Agent 用自然语言说"已修改"，而是展示证据
坑 7：多 Agent 协作时的幻觉传染
现象：一个 Agent 产生了幻觉信息，传给下一个 Agent，下一个 Agent 基于错误信息继续推理，错误层层放大。
解决：（人工环节）在关键信息传递时，让接收方 Agent 先做事实核查。
总结
AI Agent 开发的核心原则：
1. 给 Agent 足够的约束，不要让它自由发挥
2. 工具设计的质量 > Agent 模型的质量
3. 始终假设 Agent 会犯错，做容错和校验
4. 可观测性——能追踪每一轮的工具调用和决策过程，是调试的救命稻草
希望这些踩坑记录能帮你少走弯路。