附录：写 Agent 最常踩的坑

本文是《从 0 写 Agent》系列的附录 C：常见问题与坑。案例代码基于开源项目 agents-go（OpenAI Agents SDK 的 Go 移植版）。

读和实践过程中常遇到的疑问和坑，这个附录集中回答。

Q1：Agent 一直循环不结束怎么办

检查 MaxTurns。 默认 10 轮，如果任务复杂可能不够。但更常见的原因是，模型一直在调工具但不满意结果。检查：

• 工具是不是返回了模型无法理解的结果
• 指令是不是没说清楚"什么时候该停"
• 工具的 description 是不是让模型以为"还要再调一次"

Q2：模型不调工具，直接回答

检查工具定义。 最常见原因：

• 工具的 description 太模糊（模型不知道什么时候该用）
• 工具没正确注册到 Agent（Tools 字段没设）
• 模型能力不足（弱模型可能不擅长 function calling）

工具的 description 是 prompt 工程的一部分，要写清楚"这个工具干什么、什么时候用"。

Q3：流式重试为什么不行

因为吐过的 token 改不回来。 第 22 章讲过，流式调用一旦吐过 event，重试会让内容跳变。agents-go 的 RetryModel 在"首 event 前"才能重试。这是设计约束，不是 bug。

Q4：handoff 后模型行为变了

检查 InputFilter。 handoff 后如果配了 InputFilter，目标 Agent 看到的是过滤后的历史，不是完整的。这可能导致它"不知道"某些上下文。如果不希望过滤，别配 InputFilter。

Q5：HITL resume 后 token 重复计了

不应该。 agents-go 的 resume 设计是"复用不重算"（第 13 章）。如果你发现 token 重复计，检查是不是没用 RunState 恢复，而是重新 Run 了。必须用 ResumeRun(state)，不能重新 Run。

Q6：JSON Schema 生成失败

Go 反射的局限。 某些类型（嵌套 channel、复杂 union）反射不出合法 schema。agents-go 的 SchemaFor 失败时不 panic，返回一个"调用时报错"的工具。如果你的工具参数结构体太复杂，简化它，或用 NewRawFunctionTool 手动传 schema。

Q7：MCP 工具调用被 strict mode 拒绝

Schema 不兼容。 很多 MCP server 的 schema 不满足 OpenAI strict 要求。解法，Options{Strict: false} 关闭 strict 转换。但注意关闭后模型可能传不合规参数。

Q8：Session 历史太长撑爆上下文

用 limit + compaction。 GetItems(limit) 只取最近 N 条。或用 CompactionAwareSession（第 11 章）自动压缩。或用服务端状态（previous_response_id）省 token。

Q9：Docker 沙箱起不来

检查权限和配置。 Docker 后端需要：

• 宿主能访问 Docker daemon
• 镜像存在（python:3.12-slim 等）
• 工作目录 volume 可写

agents-go 的 Docker 错误信息比较详细，看 stderr。

Q10：并发工具调用打挂了下游

调 MaxToolConcurrency。 默认不限并发。如果工具调外部 API（有限流），设 MaxToolConcurrency: 3 限制并发。第 5 章讲过，并发上限要匹配最弱的下游。

---

遇到其他问题，查 agents-go 仓库的 issues 和源码注释，它的注释写得像设计文档，很多"为什么"都能在注释里找到答案。

---

本文是《从 0 写 Agent》系列附录，全系列目录见总览。