文章讨论构建真实世界AI智能体时常见问题处理长文档的JSON解析输出如坐标、置信度分数占用整个上下文窗口导致智能体无法有效工作。作者提出解决方案将解析输出分离为纯内容Markdown格式用于智能体推理和元数据存储在文件系统中按需通过工具查询并优化提示词以鼓励代理使用搜索工具而非全载文档。导读随着模型上下文窗口不断扩大我们似乎习惯了“暴力输入”但 1M Token 的杂乱数据往往不如 200k 的精炼信息。本文深入剖析了构建复杂 Agent如法律、金融、建筑领域时的常见性能瓶颈原始解析输出对模型推理的干扰。通过引入“Markdown 编号块 沙盒代码查询”的架构模式我们不仅能保留精确到 PDF 像素级的引用能力还能让 Agent 的注意力重新聚焦在逻辑推理上。这是一场关于“信息密度”与“工具调用”的技术进化。作者 Raunakraunakdoesdev是一位专注开源科学、优雅软件架构与精致界面的独立开发者与创业者。目前正在构建Reducto AI擅长AI代理、文档解析与复杂工作流优化曾在Anthropic黑客松获奖热衷分享真实世界AI工程经验。我在构建现实世界智能体时看到的最常见问题——以及如何修复它。最近我反复从构建各种文档相关智能体的客户那里听到同一个问题。他们通过 API 处理长文档将生成的 JSON 响应喂给智能体结果在智能体还没开始干正事之前整个上下文窗口Context Window就已经被塞满了。我在很多场景中都见过这种情况审查合同的法律 AI 智能体、处理理赔的保险智能体有时是处理 10-K 表格提取数据的金融智能体。但问题的本质总是一样的原始解析输出包含的信息远超智能体所需而这些多余的信息正严重损害性能。一个例子建筑工作流智能体最近的一个例子让这个问题变得尤为清晰一位客户正在构建一个用于建筑项目的“变更单Change Order”审查智能体。他们带着一份 100 页的变更单来找我们这份文档解析后产生了20 万行 JSON 代码。该工作流允许承包商提交变更单智能体则根据原始合同、进度表和单价表进行交叉比对并在审查电子表格中标记出不一致之处。由于用户是负责数百万美元索赔的建筑项目经理PM每一项发现都需要链接回原始 PDF 的精确区域。他们利用沙盒环境、电子表格工具和边界框Bounding Box引用构建了整个系统。听起来很扎实对吧但智能体在处理长文档时总是卡住。他们的第一直觉是在系统顶层增加一些东西比如目录、章节摘要或者想办法给智能体一个可以进一步钻取的压缩视图。我扫了一眼那 20 万个 token 里到底装了什么立刻发现了一个更好的解决方案。问题所在原始 API 响应并非为智能体输入而设计Reducto 的解析响应是为了工程灵活性而设计的。每个模块Block都有边界框坐标、OCR 置信度分数、类型分类、坐标数据——这是一个对文档丰富且忠实的还原。这正是你开发文档阅读器或版面分析工具时所需要的。但这不是你希望放入智能体上下文窗口里的东西。当你把原始 JSON 交给智能体时大部分 token 并不是文档内容而是像素坐标、置信度浮点数和结构化元数据。智能体正试图在密集的边界框数组中艰难前行同时还要推理合同条款和单价。我们为工程师结构化 JSON而不是为了让智能体直接消耗。大多数结构化 API 响应可能都是如此不只是我们的。这中间有一个很多团队都忽略了的预处理步骤。更好的解决方案在解析输出进入智能体之前将其拆分为两种表示内容Content和元数据Metadata。从 API 响应中提取内容如.result.chunks[0].content并写入一个.md (Markdown)文件。丢掉坐标、置信度分数和块元数据。剩下的就是一个干净、可读的文档版本。难点在于许多客户需要“块级引用”。当智能体标记某项内容时产品需要高亮显示原始 PDF 中的精确区域。你不能扔掉边界框但你也不需要把它们放在上下文窗口里。修复方法很简单在 Markdown 中为每个块编号。块 0 | 第一节一般条款 块 1 | 承包商应提供所有人工、材料和设备... 块 2 | 附件 B 中规定的单价应作为所有定价的依据... 块 3 | 1.1 工作范围 块 4 | 本变更单涵盖的工作包括对...的修改完整的解析 JSON或从中提取的 CSV存放在智能体的沙盒文件系统中。智能体阅读并推理 Markdown 内容。当它发现值得引用的内容时——比如第 47 块中的单价不一致——它会编写一段简单的 pandas 代码从结构化文件中提取对应的边界框。元数据永远不会占用上下文窗口。它只在需要时通过代码按需获取。这就是为什么沙盒化编码智能体在处理文档工作时如此强大。智能体对待结构化元数据就像开发者一样将其视为待查询的数据而不是待阅读的文本。原本 20 万 token 的 JSON 变成了一个用于理解的干净 Markdown 文件 一个用于空间查询的结构化文件。设置这一切只需要大约 20 行的后处理代码。一个值得修正的提示词模式Prompt Pattern在许多系统提示词中总能看到类似这样的指令“从头到尾阅读每个附件文档。”这听起来很合理你希望智能体严谨周全。但模型非常擅长执行指令哪怕指令本身并不合理。当你告诉智能体从头到尾阅读每个文档时它会尝试将每个文件都加载到上下文窗口中。对于一份 100 页的变更单加上证明文件智能体在做任何有用的工作之前上下文预算就已经耗尽了。这样写效果会好得多“利用附件文档回答问题。使用子智能体或工具来有效管理上下文。如果文件很大请搜索相关章节而不是加载整个文档。”区别是巨大的。第一种提示词产生的智能体像是一个在考试前死记硬背教科书的学生第二种则像是一个研究员它会搜索grep相关章节、阅读特定片段、利用工具提取特定数据。它是在引导navigate文档而不是试图背诵文档。这对工具设计也很重要。如果你的智能体正在填写审查表格一个能通过关键词或章节标题搜索并返回相关块的工具远比一个将整个文件甩进对话里的工具更有用。完整的流水线方案对于文档密集型智能体行之有效的通用方案如下文档上传Reducto 解析 API获取全保真 JSON预处理约 20 行代码提取块内容 → 带有编号的.md 文件存储元数据 → 沙盒中的CSV/JSON 文件可选生成章节索引智能体沙盒.md 文件智能体阅读并推理元数据文件智能体在需要时通过代码查询工具搜索、grep、代码执行、带有引用的单元格写入智能体引用第 47 块→ 编写 pandas 片段 → 提取边界框应用层在原始 PDF 中渲染高亮引用当然还有其他可行的方法向量搜索分块Chunking with vector search层级化摘要Hierarchical summarization微调检索Fine-tuned retrieval但对于智能体需要跨文档进行详细交叉引用并产生精确引用的用例将内容与元数据分离并给智能体提供干净的 Markdown对我们合作过的团队来说效果非常好。核心原则人们很容易尝试用更大的上下文窗口来解决长文档问题。但是一个包含 90% 坐标元数据的 100 万 token 上下文效果不如一个拥有干净 Markdown 和优秀工具的 20 万 token 上下文。上下文不是免费的。每一个 token 都会影响模型的行为而那些对任务无用的 token 会积极地挤占掉那些有用的 token。我们的 Reducto API 旨在实现最高保真度。对于在它之上进行构建的工程师来说这是正确的默认设置。但 API 返回的所有数据与智能体实际需要的数据之间存在差距。我们已经看到客户通过弥合这一差距显著提升了准确率和性能从而为他们的终端用户带来了更好的结果和性能更佳的智能体。您在处理此类问题时有什么其他方法或想法吗欢迎交流原文https://x.com/raunakdoesdev/status/2029610657008783407参考阅读别再死磕模型调优了Cursor和Manus告诉我们: 外壳(Harness)才是真正的护城河像智能体一样观察Anthropic 团队谈 Claude Code 工具设计的演进与艺术我们如何构建安全可扩展的智能体沙箱基础架构关于软件开发未来的三点思考