当前位置：首页 > news >正文

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

news 2026/6/1 10:46:16

本文首发于 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 延迟变高，费用飙升。

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

解决：

每次请求只保留最近的 N 轮对话 + 系统提示
当上下文超长时，把早期内容压缩成摘要
工具返回值只保留关键字段，不要全量保留

# 不好的做法：把所有工具返回值都保留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 下更容易出错。

解决：

用 Function Calling 代替自由格式 JSON
强制 JSON：在 Prompt 末尾加请只输出 JSON，不要 markdown 不要代码块标记
容错解析：正则提取 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":"搜索关键词，应该包含核心业务术语，如「部署失败」而非「报错了」"}}}