最近做 Agent 相关功能时，我发现自己有一个很明显的习惯：只要模型的表现不符合预期，第一反应就是改 Prompt。

工具选错了，改工具调用提示词；RAG 回答不准确，补一句“请严格依据参考资料”；多轮对话开始跑偏，再加几条限制。

有时候确实有效。但改得多了之后，我慢慢发现，很多看起来像 Prompt 的问题，其实根本不发生在 Prompt 这一层。

召回错了，Prompt 再严格也没用

做 RAG 问答时，我遇到过一种很容易误判的情况：模型的回答和预期不一致，看起来像是它没有遵守“依据知识库回答”的要求。

继续检查后才发现，真正的问题可能是：

• 文档切分把关键上下文拆散了；

• TopK 召回的片段相关，但不足以回答问题；

• 旧版本文档和新版本同时进入了上下文；

• 相似度高的重复片段挤掉了真正有用的内容。

如果交给模型的材料本身就不对，再强调十遍“不要编造”也解决不了问题。

所以我现在排查 RAG，通常会先看实际召回了哪些 chunk、对应的文档版本是什么、排序分数是多少，而不是马上改 Prompt。

工具调用异常，可能是工具定义没写清楚

Agent 选错工具时，也不一定是模型“理解能力不行”。

假设系统里同时存在“查询待办”和“搜索知识库”两个工具，如果它们的名称、描述和适用范围写得很接近，模型就很难稳定区分。

参数设计同样重要。一个工具接收模糊的 Map<String, Object>，另一个工具把必填项、枚举值和字段含义定义清楚，后者通常更容易被正确调用。

这时，与其在总 Prompt 里不断追加：

请认真判断用户意图，并选择最合适的工具。

不如直接把工具边界写清楚：

• 这个工具解决什么问题；

• 什么情况下不能使用；

• 哪些参数必填；

• 缺少信息时应该追问，而不是猜测。

很多工具调用问题，本质上是接口设计问题，只是最后通过模型暴露了出来。

多轮对话跑偏，也不只是“提示词不够强”

对话轮数增加后，Agent 可能忘记早期约束，也可能被大量历史消息干扰。

我以前会下意识地加强系统提示词，后来才意识到，如果完整历史、RAG 片段、工具描述和工具返回值全部塞进上下文，真正重要的信息本来就可能被淹没。

这时候更应该检查：

• 历史消息是否需要滑动窗口裁剪；

• 长对话是否应该生成摘要；

• 当前任务是否真的需要加载全部工具；

• 工具返回的原始 JSON 是否应该压缩；

• 用户、会话和租户上下文有没有串用。

Prompt 可以告诉模型“关注重点”，但不能无限抵消上下文中的噪声。

我现在怎么排查 Agent 问题

现在遇到 Agent 效果异常，我会先简单判断问题发生在哪一层：

1. 输入层：用户意图是否完整，是否需要追问；

2. 检索层：召回内容是否正确、完整且为最新版本；

3. 工具层：工具名称、描述、参数和边界是否清晰；

4. 上下文层：历史消息和工具结果是否过多或互相冲突；

5. 执行层：超时、异常、重试和幂等是否处理正确；

6. 模型层：前面都正常，再考虑 Prompt 或模型能力。

这个顺序并不是绝对的，但能避免把所有问题都归结为一句“模型不稳定”。

Prompt 很重要，但它不是万能补丁

我现在依然会认真写 Prompt，只是不再把它当成 Agent 系统的总开关。

一个 Agent 最终表现出来的效果，是检索、工具、上下文、执行链路和模型共同作用的结果。Prompt 只能约束模型如何使用已经拿到的信息，却不能自动修复错误的召回结果、含糊的工具接口和缺失的异常处理。

所以，Agent 效果不好时，当然可以改 Prompt。

但在动手之前，最好先问一句：

这真的是 Prompt 的问题吗？