1. 半年实战复盘那些“看起来解决了”的坑到底长什么样做 AI Agent 应用这半年我最大的感受不是技术难而是**“假性完成”**太坑人。什么叫假性完成就是 demo 跑通了、日志没报错、测试用例全绿你满心欢喜上线结果真实用户一用问题全冒出来。更可怕的是这些问题往往不是崩溃式的而是“看起来解决了”——Agent 还在跑但跑出来的东西不对工具还在调但调用的参数是错的对话还在继续但上下文已经丢了。我做的项目是一个基于LangChain4j和Spring AI的企业级 AI Agent 中台核心场景是让 Agent 帮运营人员自动处理工单、查询数据、生成报表。技术栈上用了ReAct模式做推理循环Function Calling做工具调用MCP协议做工具注册和发现前端用 React 做交互通过 SSE 和 WebSocket 做流式推送。听起来挺完整对吧但就是这套“完整”的架构让我在半年里踩了五个大坑每一个都符合“看起来解决了”的特征。这篇文章不是教你从零搭建 AI Agent 的入门教程市面上那种文章太多了。我想聊的是那些文档里不会写、面试里不会问、但真实生产环境一定会遇到的坑。如果你正在做 AI Agent 应用或者准备从 0 到 1 搭建智能体这些经验能帮你省下至少两个月的试错时间。特别是当你用到 ReAct、MCP、Function Calling 这些热词背后的技术时我会告诉你哪些地方最容易“看起来没问题实际上全是问题”。先说一下我的项目背景方便你判断这些经验的适用性。后端是 Java 生态Spring Boot 3 LangChain4j Spring AIAgent 推理框架用的是自己手写的 ReAct 循环因为 LangChain4j 自带的 Agent 执行器在某些场景下不够灵活工具层通过 MCP 协议统一注册支持动态发现和热加载。前端是 React TypeScript用 SSE 做流式输出WebSocket 做双向通信。并发量不算高日均几千次 Agent 调用但就是这几千次调用暴露了五个典型问题。这五个坑分别是ReAct 循环的“假收敛”、Function Calling 的参数幻觉、MCP 工具注册的“幽灵工具”、上下文窗口的“记忆错乱”、以及并发场景下的“状态污染”。每一个我都花了大量时间排查有些甚至排查了两周才定位到根因。下面我会逐个拆解告诉你问题现象是什么、为什么会出现、怎么排查、以及最终的解决方案。2. 坑一ReAct 循环的“假收敛”——Agent 说完成了其实它在糊弄你2.1 问题现象日志全绿结果全错ReAct 模式的核心是“推理-行动-观察”循环Agent 先思考下一步做什么然后调用工具观察结果再决定下一步。理论上当 Agent 认为任务完成时它会输出一个 Final Answer循环结束。但我在实际运行中发现Agent 经常在没有真正完成任务的情况下就输出了 Final Answer。举个例子我让 Agent 查一下“上个月华东区销售额最高的三个产品”。Agent 的推理过程是这样的Thought: 我需要查询销售数据Action: 调用querySalesData工具参数{region: 华东, period: 上个月}Observation: 返回了一个包含几十条记录的列表Thought: 我已经拿到了数据可以回答了Final Answer: “上个月华东区销售额最高的产品是 A、B、C”看起来没问题对吧但实际结果是错的。因为工具返回的数据没有排序Agent 只是取了前三条而不是销售额最高的三条。更离谱的是有时候工具返回的是分页数据第一页只有 10 条Agent 直接在这 10 条里找“最高”完全忽略了后面还有几百条。这就是“假收敛”Agent 在信息不完整或未经验证的情况下就自信地宣布任务完成。日志里看不到任何错误ReAct 循环正常结束Final Answer 格式也正确但答案就是错的。2.2 根因分析为什么 Agent 会“糊弄”这个问题的根因有三层。第一层是ReAct 提示词的设计缺陷。大多数 ReAct 提示词模板只告诉 Agent“当你认为任务完成时输出 Final Answer”但没有告诉它“什么才算真正完成”。Agent 没有“验证”的概念它只是根据当前观察到的信息做判断。如果观察到的信息看起来能回答问题它就认为任务完成了。第二层是工具返回值的语义缺失。我的querySalesData工具返回的是一个 JSON 数组但没有告诉 Agent 这个数组是否完整、是否已排序、是否有分页。Agent 看到数组里有数据就默认这是全部数据。这就像你问同事要一份报表同事给了你第一页你以为这就是全部直接拿去汇报了。第三层是缺乏外部验证机制。ReAct 循环本身是自封闭的Agent 自己判断自己是否完成没有外部校验。这就像考试没有阅卷老师考生自己给自己打分当然容易“自我感觉良好”。2.3 解决方案强制验证 工具语义增强我最终的解决方案是三个措施组合。第一在 ReAct 提示词中加入强制验证步骤。我修改了提示词要求 Agent 在输出 Final Answer 之前必须执行一个“验证思考”在输出 Final Answer 之前你必须回答以下问题 1. 我是否已经获取了完成任务所需的全部信息 2. 我获取的信息是否完整没有分页、没有截断 3. 我是否对信息进行了必要的处理排序、过滤、聚合 4. 如果以上任何一个问题的答案是否定的请继续执行 Action不要输出 Final Answer。这个改动看起来很简单但效果非常明显。Agent 开始主动检查信息的完整性而不是拿到什么就用什么。第二增强工具返回值的语义。我修改了所有工具的返回结构不再返回裸数组而是返回一个带有元信息的对象{ data: [...], total: 347, page: 1, pageSize: 10, hasMore: true, sortedBy: null, message: 返回第1页数据共347条未排序 }这样 Agent 就能从返回值中知道数据是否完整、是否需要继续获取。这个改动让“假收敛”的概率下降了大约 70%。第三加入外部验证钩子。在 ReAct 循环结束前我加了一个可选的验证函数。对于关键任务系统会自动调用一个轻量级的验证 Agent检查 Final Answer 是否合理。比如对于“销售额最高的三个产品”这个问题验证 Agent 会检查答案中的产品是否真的在返回数据中、销售额是否确实高于其他产品。实操心得不要指望 Agent 自己“变聪明”。你需要通过提示词、工具设计和外部验证三层机制强制它变得严谨。这就像带新人你不能只说“把事办好”你得告诉他“什么叫办好”。2.4 排查技巧如何发现“假收敛”“假收敛”最麻烦的地方是它不报错。我的排查方法是记录完整的 ReAct 轨迹包括每一步的 Thought、Action、Observation 和 Final Answer。然后定期抽样人工检查重点看那些“推理步骤少于 3 步就输出 Final Answer”的案例。通常如果一个复杂任务只用了 1-2 步就完成大概率是“假收敛”。另外我会在工具层加一个“调用次数统计”。如果某个任务理论上需要调用 3 个工具但实际只调用了 1 个系统会标记为“可疑完成”进入人工复核队列。这个机制帮我抓到了不少隐藏问题。3. 坑二Function Calling 的参数幻觉——Agent 编造了一个不存在的参数3.1 问题现象工具调用“成功”了但参数是编的Function Calling 是 AI Agent 的核心能力之一它让 Agent 能够根据用户需求自动生成工具调用的参数。但我在实际使用中发现Agent 经常编造不存在的参数值而且这些调用居然“成功”了。比如我有一个工具queryOrder定义如下{ name: queryOrder, parameters: { orderId: {type: string, description: 订单ID格式为 ORD-XXXXXX}, status: {type: string, enum: [pending, shipped, delivered, cancelled]} } }用户说“帮我查一下订单 ORD-123456 的状态”。Agent 生成的调用是{orderId: ORD-123456, status: all}注意status参数的值是all但我的枚举里根本没有all这个值。更离谱的是我的工具实现里没有对status做严格校验all被当作一个普通字符串传入了查询逻辑结果查询返回了空列表。Agent 拿到空列表后告诉用户“该订单不存在”。用户很困惑订单明明存在为什么说找不到我排查了半天才发现是 Agent 自己编了一个status参数值导致查询条件错误。3.2 根因分析LLM 的“填空本能”这个问题的根因在于LLM 的生成机制。当你给 LLM 一个函数签名时它会尝试“填满”所有参数即使某些参数是可选的或者用户没有明确提供。LLM 的本能是“补全”而不是“留空”。如果提示词没有明确告诉它“不确定的参数应该省略”它就会自己编一个看起来合理的值。另一个原因是参数描述的模糊性。我的status参数描述是“订单状态”但没有明确说明“如果不确定请不要传这个参数”。LLM 看到这个描述会认为这是一个必填参数然后从上下文中猜测一个值。当上下文中没有明确的状态信息时它就会编一个。还有一个容易被忽略的原因Function Calling 的 schema 校验缺失。很多框架在生成调用参数后不会严格校验参数是否符合 schema。即使参数值不在枚举范围内框架也会照常执行调用。这就像安检门没通电谁都能过。3.3 解决方案严格 Schema 校验 提示词约束我的解决方案分三步。第一步在工具层加入严格的参数校验。所有工具在执行前必须先通过 JSON Schema 校验。如果参数不符合 schema比如枚举值不在范围内、必填参数缺失、类型不匹配直接返回错误不执行实际逻辑。public class ToolValidator { public ValidationResult validate(String toolName, MapString, Object params) { JsonSchema schema toolRegistry.getSchema(toolName); SetValidationMessage errors schema.validate(params); if (!errors.isEmpty()) { return ValidationResult.fail(参数校验失败: errors); } return ValidationResult.success(); } }这个改动让“参数幻觉”从“静默错误”变成了“显式错误”。Agent 收到校验失败的信息后会重新尝试生成参数而不是继续用错误的参数执行。第二步在提示词中明确约束。我在系统提示词中加入了以下内容当调用工具时请严格遵守以下规则 1. 只传递你确定知道的参数值不要猜测或编造。 2. 如果某个参数你不确定请省略该参数而不是填一个默认值。 3. 如果工具返回参数校验错误请仔细阅读错误信息修正参数后重试。 4. 不要传递 schema 中未定义的参数。第三步在 Function Calling 的 schema 中增加“可选性”标注。对于非必填参数我在描述中明确写上“可选如果不确定请省略”。这个看似微小的改动显著降低了 Agent 编造参数的概率。注意事项不要依赖 LLM 的“自觉性”。你必须假设它会犯错然后在工具层做好防御。Schema 校验是最后一道防线绝对不能省。3.4 排查技巧如何发现参数幻觉参数幻觉的排查相对容易因为它在工具层会留下痕迹。我的做法是记录所有工具调用的原始参数和校验结果然后定期分析排查维度具体方法预期发现枚举值越界统计不在枚举范围内的参数值Agent 编造的“合理但不存在”的值必填参数缺失统计校验失败的调用Agent 遗漏关键参数的情况参数类型错误统计类型不匹配的调用Agent 对参数类型的理解偏差多余参数统计 schema 未定义的参数Agent 自行“发明”的参数我通过这个表格发现最常见的参数幻觉是枚举值越界占比约 60%。其次是必填参数缺失占比约 25%。这两类问题通过 Schema 校验都能有效拦截。4. 坑三MCP 工具注册的“幽灵工具”——工具明明下线了Agent 还在调4.1 问题现象调用了一个已经不存在的工具MCP 协议是我用来做工具注册和发现的。所有工具通过 MCP Server 注册Agent 通过 MCP Client 动态获取工具列表。这个设计的好处是工具可以热插拔不需要重启 Agent 服务。但问题来了有一次我下线了一个旧版本的querySalesData工具换成了新版本的querySalesDataV2。MCP Server 已经更新了工具列表但 Agent 在后续的对话中仍然调用了querySalesData。调用失败了Agent 收到错误后居然没有切换到新工具而是反复重试旧工具直到达到最大重试次数。更诡异的是我在日志里看到 Agent 的工具列表里确实有querySalesDataV2但它就是不用。这就像你手机通讯录里存了新号码但拨号时还是拨了旧号码。4.2 根因分析工具列表的缓存不一致这个问题的根因是MCP 工具列表的缓存不一致。MCP Client 在启动时会从 Server 拉取工具列表然后缓存在本地。当 Server 端的工具列表发生变化时Client 不会自动刷新缓存除非显式调用刷新接口。但问题不止于此。即使 Client 刷新了缓存Agent 的对话上下文中可能还保留着旧工具的信息。因为 LLM 的上下文窗口里包含了之前的对话历史而对话历史中可能引用了旧工具。当 Agent 基于上下文做推理时它会“记得”旧工具的存在即使当前工具列表里已经没有它了。还有一个隐藏更深的问题MCP 工具注册的命名冲突。当我同时注册querySalesData和querySalesDataV2时Agent 有时会混淆两个工具的功能把 V2 的参数传给 V1或者反过来。这就像公司里有两个同名的人快递员很容易送错。4.3 解决方案版本化命名 缓存刷新 上下文清理我的解决方案是三个措施。第一工具命名版本化。我不再使用querySalesDataV2这种命名而是把版本号放在工具描述里工具名保持稳定。比如{ name: querySalesData, description: 查询销售数据当前版本v2支持分页和排序, version: 2.0 }这样 Agent 始终调用同一个工具名但实际执行的是最新版本。旧版本在 MCP Server 端直接下线不再注册。第二MCP Client 定期刷新工具列表。我设置了一个定时任务每 5 分钟从 MCP Server 拉取一次工具列表并对比本地缓存。如果有变化更新缓存并记录日志。同时在每次新的对话开始时强制刷新一次工具列表确保 Agent 拿到的是最新工具。第三对话上下文中的工具引用清理。当工具列表发生变化时我会在系统提示词中插入一条通知“工具列表已更新请使用最新的工具列表。”同时对于长对话我会在上下文压缩时移除对已下线工具的引用。实操心得MCP 协议虽然方便但它的缓存机制需要你手动管理。不要假设工具列表会自动同步一定要加刷新机制和版本管理。另外工具命名尽量保持稳定版本信息放在描述里避免 Agent 混淆。4.4 排查技巧如何发现幽灵工具幽灵工具的排查关键是对比 Agent 实际调用的工具列表和 MCP Server 当前注册的工具列表。我的做法是在 Agent 每次调用工具时记录工具名和调用时间。在 MCP Server 端记录工具注册和下线的时间线。定期对比两个列表找出“Agent 调用了但 Server 已下线”的工具。这个对比帮我发现了多个幽灵工具案例。最常见的情况是工具下线后Agent 在旧对话中仍然引用它。通过上下文清理和缓存刷新这个问题基本消失了。5. 坑四上下文窗口的“记忆错乱”——Agent 把三天前的对话当成了刚刚发生的5.1 问题现象Agent 混淆了不同会话的上下文我的 AI Agent 支持多轮对话用户可以在一个会话中连续提问。但我在测试中发现Agent 经常把不同会话的上下文混淆。比如用户 A 在会话 1 中问了“上个月销售额”用户 B 在会话 2 中问了“这个月库存”Agent 在回答用户 B 时居然引用了用户 A 的销售额数据。更严重的是有时候 Agent 会把三天前的对话当成刚刚发生的。用户今天问“帮我查一下订单”Agent 回答“您刚才不是已经查过了吗”——但实际上用户上次查订单是三天前的事。这个问题在并发场景下尤其明显。当多个用户同时使用 Agent 时上下文窗口的管理变得非常复杂。如果上下文隔离没做好就会出现“串台”。5.2 根因分析上下文窗口的管理策略问题这个问题的根因是上下文窗口的管理策略。LLM 的上下文窗口是有限的当对话历史超过窗口大小时需要做压缩或截断。我的初始实现是简单地保留最近 N 条消息但这种方式有两个问题第一没有区分会话。所有会话的消息都放在同一个队列里按时间排序。当会话 A 的消息和会话 B 的消息交错时Agent 会认为它们是同一个对话。第二没有时间衰减。三天前的消息和刚刚的消息在上下文中的权重是一样的。Agent 无法区分“刚刚发生”和“很久以前”。第三压缩策略过于粗暴。当上下文超限时我直接截断最早的消息。但这可能导致关键信息丢失比如用户最初设定的查询条件。5.3 解决方案会话隔离 时间衰减 智能压缩我的解决方案是三个层面的改造。第一严格的会话隔离。每个会话有独立的上下文窗口会话之间不共享消息。在 Agent 处理请求时只加载当前会话的上下文。这个改动从架构上杜绝了“串台”问题。public class SessionContextManager { private MapString, DequeMessage sessionContexts new ConcurrentHashMap(); public ListMessage getContext(String sessionId) { DequeMessage context sessionContexts.getOrDefault(sessionId, new ArrayDeque()); return new ArrayList(context); } public void addMessage(String sessionId, Message message) { sessionContexts.computeIfAbsent(sessionId, k - new ArrayDeque()).addLast(message); } }第二时间衰减机制。在构建上下文时我给每条消息加上时间戳并在提示词中标注消息的时间。对于超过一定时间的消息降低其优先级或直接移除。比如[3天前] 用户: 帮我查一下上个月销售额 [刚刚] 用户: 那这个月呢这样 Agent 就能理解“上个月”是三天前的问题“这个月”是当前的问题。第三智能压缩策略。当上下文超限时我不再简单截断而是用 LLM 做摘要压缩。把早期的对话压缩成一段摘要保留关键信息同时释放上下文空间。[历史摘要] 用户之前询问了上个月华东区销售额Agent 返回了 A、B、C 三个产品用户表示满意。 [最近对话] 用户: 那这个月呢注意事项上下文管理是 AI Agent 最容易出问题的地方之一。不要用“一刀切”的策略要根据会话、时间、重要性做差异化处理。另外并发场景下一定要用线程安全的数据结构避免状态污染。5.4 排查技巧如何发现记忆错乱记忆错乱的排查需要完整的对话日志。我的做法是记录每个会话的完整消息历史包括时间戳和会话 ID。在 Agent 输出中检查是否引用了其他会话的信息。定期抽样人工检查 Agent 的回答是否与当前会话的上下文一致。我还会做一个“时间一致性检查”如果 Agent 的回答中提到了“刚才”“之前”等时间词检查它引用的消息是否真的在时间上接近。如果 Agent 说“您刚才查过”但实际查询发生在几小时前就标记为可疑。6. 坑五并发场景下的“状态污染”——两个用户同时用Agent 疯了6.1 问题现象并发请求导致 Agent 行为异常我的 AI Agent 中台需要支持多用户并发。在压力测试中我发现当并发量超过 10 时Agent 的行为开始变得异常。具体表现包括Agent 把用户 A 的查询结果返回给了用户 BAgent 在用户 A 的会话中执行了用户 B 的工具调用Agent 的 ReAct 循环状态混乱Thought 和 Action 不匹配最严重的一次两个用户同时查询订单Agent 把订单 A 的数据返回给了用户 B导致数据泄露。虽然只是测试环境但这个问题如果上线后果不堪设想。6.2 根因分析共享状态没有隔离这个问题的根因是共享状态没有做好隔离。我的 Agent 实现中有几个地方使用了共享状态第一ReAct 循环的状态对象。我最初把 ReAct 的中间状态当前步骤、已执行的动作、观察结果放在了一个单例对象中。当多个请求同时进入时它们共享同一个状态对象导致状态互相覆盖。第二工具调用的上下文。工具在执行时需要访问当前会话的上下文比如用户 ID、会话 ID。我最初用 ThreadLocal 存储这些信息但在异步场景下ThreadLocal 会失效。第三LLM 客户端的连接池。LLM 客户端是共享的但我在调用时没有做好请求隔离导致响应错乱。6.3 解决方案请求级隔离 异步安全 连接池管理我的解决方案是三个层面的改造。第一请求级状态隔离。每个请求创建独立的 ReAct 状态对象不共享任何可变状态。状态对象在请求开始时创建请求结束时销毁。public class AgentRequest { private final String requestId; private final String sessionId; private final ReActState state; private final MapString, Object toolContext; // 每个请求独立的状态不共享 }第二异步安全的上下文传递。我不再使用 ThreadLocal而是把上下文作为参数显式传递。在异步调用中使用CompletableFuture的上下文传播机制确保上下文在异步线程中也能正确传递。public CompletableFutureAgentResponse processAsync(AgentRequest request) { return CompletableFuture.supplyAsync(() - { // 显式使用 request 中的上下文不依赖 ThreadLocal return doProcess(request); }, executor); }第三LLM 客户端的请求隔离。我确保每次 LLM 调用都有独立的请求 ID并在响应中校验请求 ID防止响应错乱。同时连接池的大小根据并发量动态调整避免连接争用。实操心得并发问题是 AI Agent 从 demo 到生产必须跨过的坎。不要假设你的代码是线程安全的尤其是当你在使用共享的 LLM 客户端、工具注册表、上下文管理器时。每个请求都要有独立的生命周期状态不能跨请求共享。6.4 排查技巧如何发现状态污染状态污染的排查比较困难因为它往往在并发量高时才出现。我的做法是压力测试用 JMeter 或 Gatling 模拟并发请求观察 Agent 行为是否异常。请求追踪给每个请求分配唯一 ID在日志中追踪请求的完整生命周期。响应校验在响应返回前校验响应中的会话 ID 是否与请求的会话 ID 一致。状态快照在关键步骤记录状态快照对比不同请求的状态是否互相影响。我通过压力测试发现当并发量超过 10 时状态污染的概率约为 5%。通过请求级隔离改造后这个问题彻底消失。7. 五个坑的共性总结与我的实操建议7.1 共性问题都是“看起来解决了”回顾这五个坑它们的共同特征是在单次测试、低并发、短对话的场景下它们都不会出现。只有当你把 Agent 放到真实环境中面对多样化的用户输入、高并发、长对话时这些问题才会暴露。这五个坑的另一个共性是它们都不是代码错误而是设计缺陷。ReAct 循环的假收敛是提示词设计问题Function Calling 的参数幻觉是 schema 设计问题MCP 幽灵工具是缓存设计问题上下文记忆错乱是管理策略问题并发状态污染是架构设计问题。这些问题不会导致编译错误或运行时异常但会导致 Agent 行为不符合预期。7.2 我的实操建议清单基于这半年的经验我整理了一份 AI Agent 开发的实操建议清单供你参考问题领域建议措施优先级ReAct 循环加入强制验证步骤要求 Agent 在输出 Final Answer 前自检高Function Calling工具层严格 Schema 校验拒绝不合规参数高MCP 工具管理定期刷新工具列表工具命名保持稳定版本信息放描述中上下文管理会话隔离时间衰减智能压缩高并发安全请求级状态隔离异步安全上下文传递高可观测性完整记录 ReAct 轨迹、工具调用、上下文变化高7.3 最后的经验分享如果你正在做 AI Agent 应用我建议你在开发早期就建立完整的可观测性体系。不要等到出了问题才去加日志。ReAct 的每一步 Thought、Action、Observation每次工具调用的参数和结果每个会话的上下文变化都应该被记录下来。这些日志是你排查问题的唯一依据。另外不要迷信“框架能解决一切”。LangChain4j、Spring AI 这些框架确实能帮你快速搭建 Agent但它们不能帮你解决设计层面的问题。ReAct 循环怎么设计、工具怎么注册、上下文怎么管理、并发怎么隔离这些都需要你自己想清楚。最后多做压力测试和异常测试。正常流程跑通不代表没问题真正的问题往往出现在边界场景空输入、超长输入、并发冲突、工具超时、LLM 返回格式错误。这些场景才是检验 Agent 健壮性的试金石。我在实际使用中发现AI Agent 的开发难度不在于“让它跑起来”而在于“让它稳定地跑对”。这中间的差距就是这五个坑所代表的那些“看起来解决了”的问题。希望我的经验能帮你少走一些弯路。