半年 AI Agent 开发踩了 7 个坑，每一个都是代码换来的教训

本文首发于 Zyentor（智元界） —— AI 开发者社区
原文链接：https://www.zyentor.com/news/3161

前言

过去半年一直在做 AI Agent 相关的开发，从最简单的单步工具调用，到复杂的多 Agent 协作系统，踩了无数坑。这篇文章把真实的踩坑经历写出来，希望对正在入坑的你有帮助。

坑 1：Tool Call 死循环

现象：Agent 反复调用同一个工具，直到超出最大轮次限制。

真实案例：让 Agent 查询用户信息，返回空结果，Agent 又查一次，还是空，又查…

原因：没有告诉 Agent “查不到就承认查不到”。LLM 默认倾向于"再试一次"，除非你在 System Prompt 里明确约束。

解决：

// System Prompt 中加这条规则 如果工具返回空结果或错误，直接告诉用户查不到，不要重复调用同一工具超过 1 次。

坑 2：上下文爆炸（Context Overflow）

现象：对话进行几轮后，Token 消耗暴增，API 延迟变高，费用飙升。

原因：每一轮都把完整的工具调用记录塞进对话历史，包括那些巨长的返回值。

解决：

1. 每次请求只保留最近的 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 + 修正常见错误

importre,jsondefsafe_parse_llm_output(text:str)->dict:# 尝试提取 ```json ... ```块match=re.search(r'```(?:json)?\s*([\s\S]*?)```',text)ifmatch:text=match.group(1)# 尝试解析try:returnjson.loads(text)exceptjson.JSONDecodeError:# 修复常见问题text=text.replace("'",'"').replace(",}","}").replace(",]","]")returnjson.loads(text)

坑 4：工具描述写得太随意

现象：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. 可观测性——能追踪每一轮的工具调用和决策过程，是调试的救命稻草

本文首发于 Zyentor（智元界） —— AI 开发者社区，聚合 AI 资讯、工具导航、技术论坛、开发者资源下载。
原文链接：https://www.zyentor.com/news/3161