调试Agent应用时最折磨人的，往往不是模型输出乱码，而是一切看起来都很正常，结果却是错的。前几天我就撞上了这么一档子事：源端接口明明返回了50条业务记录，Agent却只分析了前20条。整个流程没有任何报错，输出格式标准、语气专业，如果不做交叉验证，根本发现不了数据在中途被吞了一半。
这种Agent静默截断是LLM应用里最阴险的一类故障。报错的问题最好查，报错信息会直接告诉你什么环节出了问题；可截断不会开口，模型只会基于它实际看到的内容老老实实工作。你看到的结果是错的，但不知道断在哪一层，甚至不知道"截断"这个行为的存在。这篇博文完整记录一次排查过程：从"怀疑提示词写得不好"到最终定位到一行藏在token预算逻辑里的break，再到落地修复方案和预防机制。如果你在做Agent开发、或者正在用大模型构建批量分析类工具，这篇文章应该能帮你少踩几个同类坑。
1. 现象：数据没到模型手里，输出却显得一切正常
1.1 一个客户反馈分析Agent的诡异结果
这次问题出在一个客户反馈批量分析模块上。这个Agent每天从工单系统拉取当日的客户反馈记录，交给大模型逐条判断情感倾向、紧急程度和处理建议。正常情况下一天的数据量在50条左右，模型返回一个有序的JSON数组，每条记录对应一个分析结果，上线以来一直很稳。
运营第三天突然反馈"结果不全"。我打开日志一看，模型确实正常返回了20条分析结果，每条都有理有据。再对比源端数据，50条里前20条的分析完全正确，后面30条悄无声息地消失。最有迷惑性的一点是，模型输出的JSON格式非常完整，头尾、结构、字段名全对，没有任何"输出截断"的痕迹。从输出看，更像是"输入从头就没那30条"，而不是"模型生成了但被截断"。
1.2 静默截断为什么比显式报错更隐蔽
这里的关键不是"结果少了几条"，而是"少了结果却不报错"。传统软件的故障模型是：要么成功，要么失败，失败一定留下日志和异常。Agent系统不一样，LLM完全不知道自己没看到的数据，它只会把你给的prompt当作全部真理，认认真真基于残缺的输入给出自洽的完整输出。它甚至会天然地"脑补"出一种合理解释：那30条可能本来就不需要分析，或者被去重了，或者超出统计范围。
更麻烦的是，这类故障往往出现在提示词工程做得比较到位、模型输出很稳定的阶段。到这个阶段，人会对链路产生信任，反而不容易怀疑数据被截。很多团队遇到类似情况，第一反应是排查业务数据，第二反应是往提示词里加惩罚性描述，折腾一圈才发现问题根本不在这一层。这种"没有异常信号的异常"，恰恰是排查中最消耗精力的部分。
1.3 先排除模型"幻觉"的干扰
排查开始时，第一道坎是如何区分"模型没看到数据"和"模型看到了但选择忽略"。比如模型可能故意筛选了20条最有代表性的样本，也可能在数十个候选中主动跳过了一些，或者单纯地因为prompt措辞不当而没有逐条分析。这个区分很重要，因为两种情况的修复方向完全不同。为了不掉进"改提示词"的兔子洞，我先回答了一个问题：模型看到的prompt里到底有哪些记录？
这一步直接决定了后续排查的方向。如果模型看到了50条却只输出20条，那是提示词问题，是"模型行为不当"；如果模型本来就只收到20条，那无论怎么优化提示词都没用，问题必然在数据流上游。事实证明，数据流上游的问题会伪装成提示词问题，这也是我把它放在最前面的原因。
2. 排查：从"让模型复述"到每一层的数据计数器
2.1 第一招：让模型复述它真正看到的内容
核心思路是"回溯输入"。既然模型不会主动报告缺失，那就主动问它。我在临时调试prompt里加了一行指令：请先输出你本次收到的全部工单ID列表，再开始分析。结果模型老老实实列出了20个ID，正好对应源端前20条记录。这里有个细节值得注意：模型列出的ID顺序与源端完全一致，说明它的输入是"从开头按顺序截取"的结果，而不是调度乱序。
这一步基本确认了：模型侧接收到的输入确实只有20条。为了排除偶然性，我连续换了好几种措辞重新调试验证，结果始终稳定在20条，排除了LLM随机漏读的可能性。这个技巧成本低、见效快，建议所有Agent排查必用。你不需要看代码，不需要打日志，只需要让模型"自报家门"，问题就能迅速收窄到输入侧。
2.2 绕过Agent，直接验证源端数据
接下来要把问题从"模型侧"推到"上游"。我写了一个独立的小脚本，绕过Agent框架，直接调用工具函数拉取当天工单数据，打印count()。结果显示源端确实返回了50条记录，字段完整、类型正确。这一步消除了"业务数据库来不及同步"的可能性。顺手做的一件事是：把50条记录全量序列化成JSON，单独测了一下token量，大约3000多token。这个数字后来成了定位关键。
为什么要绕开Agent做这一步？因为Agent框架在工具调用时可能有自己的序列化、缓存、改写逻辑，直接在应用界面里看可能被框架层干扰。单独写脚本能保证拿到的是源端真实返回。这也是排查多环节Agent系统的一个通用办法：每一层独立验证，不让关联环节互相污染判断。很多人习惯在日志里看到什么就信什么，但日志本身也可能被上层逻辑篡改过。
2.3 给prompt组装链路装"计数器"
确认源端50条、模型只看到20条之后，问题范围就收窄到了"从工具返回结果到拼接prompt"这一段。大多数Agent框架在这里都会有一段业务代码，负责把工具结果序列化、截断、拼系统提示词、拼对话历史。不少团队还会自己写一个上下文组装器来控制prompt体量，我们的项目也不例外。
我在组装层的入口和出口各加了一行日志：入口日志记录工具返回了50条，出口日志记录实际写入prompt的记录数。跑了一次之后，出口日志显示20条。问题区间被锁定在这段代码里。接下来我打印了组装器中的一个中间变量，这个变量保存的是"待写入的记录列表"。日志确认它被操作后只剩20条，问题集中在那段列表处理逻辑上。
2.4 元凶现身：写在token预算逻辑里的break
翻开代码，真相其实非常朴素。这段代码的目标是"控制prompt总token数不超过3000"，做法是逐条预估每条记录的token成本，超出预算就break跳出循环，然后把已经收集到的记录拼接进prompt。
MAX_TOKENS = 3000 def assemble_context(tool_results): used_tokens = estimate_tokens(SYSTEM_PROMPT + TASK_INSTRUCTION) kept = [] for item in tool_results: # 源端实际有50条 cost = estimate_tokens(json.dumps(item, ensure_ascii=False)) if used_tokens + cost > MAX_TOKENS: break # 问题所在：只有break，没有日志，没有标记 kept.append(item) used_tokens += cost return build_prompt(kept)为什么源端50条、理论上限如果设40条，实际却只进20条？原因在于前20条记录是若干条很长的文本反馈，内容信息量大，token占比高，实际到第21条时就超过了3000 token预算，循环直接break。后面的30条连"被截断"的资格都没有，它们只是从未被读取。更致命的是，这段代码从始至终没有记录"我跳过了哪些记录"，也没有往prompt里写任何与"截断"相关的提示。模型看到的prompt开头写着"以下为全部客户反馈共50条"，实际却只附了20条。指令与数据不一致，正是模型输出"看起来完整、实则缺页"的根本原因。
3. 根因：token预算背后的三个隐藏陷阱
3.1 条数限制和token限制不是一回事
很多团队在做上下文控制时，喜欢在主逻辑里用"最多保留N条"这种直观条件，同时在更外层用token预算兜底。两种限制混在一起，很容易出现"表面上允许40条、实际只够20条"的错位。我们这个项目早期原型里确实有"最多40条"的常量，后来改成纯token预算，但这个"40"的预设还留在很多人的记忆里，导致一开始对不上账。
这条线索也说明了一个工程问题：估算token的精度直接影响截断位置。estimate_tokens通常是根据字符数或经验除数粗略推算的，中文字符、英文单词、标点、JSON转义字符各有不同的真实token占比。如果估算偏低，真实长度就会提前触顶。尤其当system prompt和少量历史消息已经占掉500 token，剩余预算被进一步压缩时，实际可容纳的记录数会比想象中少很多。
3.2 截断逻辑的位置决定了故障的隐蔽程度
这次案例中最值得反思的，是截断动作发生在"工具结果到prompt组装"这层，但始终没有把"截断"这个事实传递给LLM。正确的做法有两种：要么在截断发生时主动丢弃并重写说明，要么干脆不做截断，用分片方式保留完整数据。任何截断都应该是一种显式的、可观测的、带标记的事件。可实际代码里，它只是一个安静的break，连warning日志都没有。
对比来看，如果截断发生在工具返回阶段，并且工具返回结构里带有一个truncated字段，模型至少可以通过meta数据意识到数据不完整。可一旦截断发生在prompt组装阶段，模型看到的唯一信息就是"这里只有20条记录"，它无法感知"应该还有30条"。这是静默二字真正的含义：截断行为本身没有任何痕迹，也没有为下游留下任何解释。
3.3 滑动窗口与上下文缓冲区的叠加影响
在稍微复杂的Agent系统里，还有另一种加速静默截断的机制——滑动窗口。不少框架为了维持长期记忆和对话连续性，会把多轮对话历史塞进固定大小的上下文缓冲区，超出部分被直接丢弃。假设模型调用时的上下文已经被"历史对话加system prompt加任务说明"占掉相当空间，留给工具返回的记录名额就会所剩无几。工具明明返回了50条，进LLM之前又被缓冲区的淘汰策略再挤掉一波。
这类叠加问题在"Agent加滑动窗口加多轮工具调用"场景里特别明显。每次调用工具后，返回结果都会写回上下文缓冲区，下一次调用LLM时，缓冲区里还残留上次的工具输出。如果调用轮次稍多，前面轮次的数据会占据大部分预算，导致当前轮次的工具返回被严重压缩。所以排查这类故障时，不仅要看单环节，还要观察整体缓冲区的占用情况。
3.4 设计根因：成本优化与正确性没有握手
继续往下挖，这类bug的本质其实是工程目标的冲突：为了节省token成本加了预算限制，为了结果正确期望数据完整。两个目标在没有足够约束的情况下碰撞，就会产生这种"便宜但有损"的行为。作为开发者，我们不能取消成本控制，但可以把"有损"变成"有明确代价且有明确信号"的决策。
我后来把token预算细分成两档：硬预算和软预算。硬预算指单次模型调用必须保证不超过的上限，软预算是一个弹性区间。当内容逼近软预算时，系统不是默默break，而是主动降级到分片处理，或者返回"本次输入不完整，需要二次调用"的标记。把决策权交还给调用链，而不是让底层静默处理。这是这次事件给我最大的教训。
4. 修复：把"默默丢弃"改成"分批递送"
4.1 方案一：分批分析，覆盖最广
既然场景是"以下所有记录都要分析"，第一反应自然是改成"每次只喂一批，分批分析再合并"。经过验证，这个思路对逐条输出结论的批量分析任务非常适用。核心流程是保留源端返回的完整列表，按token预算自动切分成若干批，每批单独构造prompt，批次内标注当前是第几批、共几批、总记录数多少，然后调用模型得到局部结果，最后按原顺序合并。
def analyze_in_batches(items, max_tokens=2500): total = len(items) batches = split_by_token_budget(items, max_tokens) merged = [] for idx, batch in enumerate(batches, start=1): prompt = ( f"本次需要分析的记录共{total}条，" f"当前处理第{idx}/{len(batches)}批，本批{len(batch)}条。" + serialize(batch) ) result = call_model(prompt) merged.extend(result) return merged这个方案的代价是模型调用次数从1次变成k次，延迟明显增加；但换来的是数据零丢失和每个批次内上下文更紧凑。对准确性敏感的任务，这点成本完全值得。实际运行时，50条记录通常被切成2到3批，总耗时从原来的8秒增加到20秒左右，但对分析结果来说，完整比快重要得多。
4.2 方案二：先统计后分析，适合聚合类场景
如果50条记录不是每条都需要逐条分析，而是需要整体趋势判断，比如"今天的满意度如何""投诉集中在哪些产品"，就可以采用另一种思路：先让模型对全量记录做结构化压缩，再基于压缩结果分析。第一步让模型输出每条反馈的关键实体、情感标签和内容摘要到一张表里，第二步把压缩表作为prompt输入。50条记录的总token从3000多降到几百token，预算截断问题自然消失。
这种方法的问题在于压缩摘要会丢失部分细粒度信息。如果下游任务对细节敏感，比如需要引用原文中的具体表述，就应结合检索按需取原文，而不是只依赖一步压缩。本质上这是一种"用信息密度换空间"的策略，适合统计派任务，不适合逐条精读派任务。
4.3 方案三：把数据留在工具侧，让模型按需取用
更彻底的设计是改变"数据夹带"模式：不要在prompt里塞全量记录，而是把数据作为工具参数开放给模型。工具提供两个接口，一个list返回ID列表和基础元信息，比如每条记录的长度、标题、时间；另一个get(id)返回某条记录的完整内容。模型第一次调用list时能感知总共有50条记录，知道它们的分布特征，再按需调用get逐条拉取。
这种按需取数模式对摘要型分析尤其有效，模型不会一上来就背着一大堆文本推理，上下文预算的压力会小很多。缺点是对逐条分析型任务不友好，如果50条都要看，模型就要调用50次get，加上中间的消息往返，延迟会非常高。它更像一种架构思路，适合从根源上规避上下文膨胀的项目。
4.4 修复后的验证策略
修复完成后不能只看一次结果就上线，需要做几轮验证。第一轮是数字核对：源端50条，最终合并结果包含50条，逐一比对ID，确保无遗漏、无重复。第二轮是分批正确性：检查每批prompt内部标注的批次信息与实际划分是否一致，确保边界不丢数据。第三轮是随机抽查：从源端尾部随机抽3条记录，验证它们在合并结果中存在，且分析内容与该记录的真实文本一致。第四轮是回归测试：连续运行几天，每天检查输出条数与源端条数差值是否为0。
我这里做了一次完整的脚本回归，把合并后的结果条数与源端逐条比对，连续7天没有出现一条丢失。确认稳定后才重新上线。这个过程看着繁琐，但能避免"修复了一个问题又引入另一个问题"的尴尬。
5. 预防：让Agent自带"计数意识"
5.1 工具返回协议统一加完整性字段
经历过这次事故后，我给自己所有Agent相关工具返回定了两条规矩：返回结构必须带meta描述块；与数据相关的meta至少包含total、returned、truncated三个字段。工具层在返回数据前做一次自我检查，并在meta中如实填写。
{ "meta": { "total": 50, "returned": 50, "truncated": false, "reason": "" }, "items": [] }这样一来，无论后续prompt组装层怎么操作，至少有一次机会在数据源头感知全量还是截断。如果某个环节做了截断处理，它必须同步修改meta，更新truncated信息和reason。这个约定让一切截断行为显式化，为排查和自动化告警留出明确入口。修改工具协议会有一定工作量，但比起每次靠猜来处理这种问题，收益明显更高。
5.2 在prompt中强制声明数量匹配要求
还有一个很便宜但很有效的招，是在系统提示词里写清楚数量匹配检查规则。我在Agent里加了一段约束：当你接收到结构化数据时，先检查数据中声明的数量与实际条目数是否一致，若不一致，请输出数据完整性警告作为第一条信息，并说明缺失情况。
这次事故里如果当时就有这句话，模型一开始就会发现"宣称50条但实际只有20条"，哪怕组装层没有修正，模型也会自己提出疑问，而不是默默分析完20条了事。让模型主动感知数据完整性，等于给链路加了一层免费守护。它不解决根本问题，但能把"静默"变成"出声"，给后续处理赢得时间。
5.3 用结构化日志建立数据流观测
排查这类问题最痛苦的，就是不能从日志里看到每一层的输入输出数量。现在我要求所有上下文组装环节都打印结构化日志，至少包含阶段名称、条目数、token估算值、是否触发降级策略。
{ "stage": "prompt_assembler", "event": "assemble", "input_items": 50, "output_items": 50, "input_tokens": 3400, "output_tokens": 2800, "degradation": false }有了这些日志，再出现数据异常，只需要在每个阶段做一次count()对比，几分钟内就能锁定是哪一层吞了数据，不用再像这次一样一层层写临时脚本探查。日志的价值不在于记录，而在于对比。光记"输出20条"没用，必须同时记"输入50条"，差值才是故障信号。
5.4 最后分享一个兜底技巧
我一直建议Agent开发者在pipeline最终组装处无条件加上一行"记录计数器"。不管前面有多少逻辑，组装完prompt之后，紧跟着往里面追加一句：本次输入共包含N条记录，请先确认你是否完整读取了所有记录，再进行下一步分析。
这句成本极低，但对排查静默截断极其有效。它相当于把数据条数这个信息硬编码进上下文，让LLM在不一致时自己开口说话。我试过之后，从原来的事后翻日志变成模型当场指出问题，排查效率提升了一个量级。这种技巧放在任何Agent框架里都能用，不受具体技术栈限制。
这个方向的长期改进其实也清晰了：把数据完整性断言沉淀为Agent框架的通用组件，任何接入的工具结果都经过完整性检查，不匹配时自动告警并阻塞下一步动作。让Agent系统从架构层面默认不接受"静默亏损"，这比任何事后排查技巧都更根本。
