1. 从手搓轮子到搭积木Agent 基建的痛点到底在哪如果你最近半年在折腾 AI Agent大概率经历过这样一个阶段一开始兴致勃勃地写了个 ReAct 循环觉得不过如此等到真正要把它做成一个能用的东西才发现真正耗时间的根本不是那个循环本身而是围绕它的一堆脏活累活。我自己的经历就很典型。第一个能跑通的 Agent 大概花了一个下午但接下来两周我几乎全耗在了这些事上让 Agent 能读写文件、记住上一轮对话里用户提到的偏好、在对话太长的时候自动压缩上下文、在工具调用出错时优雅地重试而不是直接崩掉。这些东西单拎出来都不难但凑在一起就是一座小山而且每换一个项目就要重写一遍。这就是所谓的Agent 基建Agent Infrastructure。它不性感不上台面但决定了你的 Agent 到底是玩具还是产品。绝大多数人第一次做 Agent 时80% 的代码都在处理这些基建问题真正跟业务逻辑相关的可能只有 20%。deepagents这个中间件要解决的恰恰就是这 80%。它的核心主张很直接把文件系统、记忆、上下文压缩这些通用能力做成开箱即用的中间件让你用 30 行左右的代码就能搭出一个具备完整基建的 Agent。这篇文章我会从为什么这些基建这么难搞讲起然后拆解 deepagents 中间件的设计思路再给出可以直接抄的实操代码最后聊聊我在实际使用中踩过的坑和总结出的经验。适合谁看如果你已经写过至少一个能跑的 Agent被文件管理、记忆持久化、上下文超限这些问题折磨过那这篇就是写给你的。如果你还没入门也可以先看看一个成熟 Agent 到底需要哪些基建对建立整体认知很有帮助。2. 一个能用的 Agent基建清单到底有多长在讲 deepagents 怎么解决问题之前得先把问题本身说清楚。很多人对 Agent 基建的认知是模糊的觉得不就是调个 API 吗结果一上手就发现处处是坑。我把一个生产级 Agent 需要的基建能力拆成四块你可以对照看看自己漏了哪块。2.1 文件系统Agent 的手和眼睛大模型本身是个缸中之脑它只能处理你喂给它的文本。但真实任务往往需要它去读一个文件、写一个结果、列一个目录、改一行配置。没有文件系统能力Agent 就只能空谈。手写这块的痛点在于你得定义一套工具read_file、write_file、list_dir、edit_file……每个工具都要处理路径安全防止它读到/etc/passwd这种、编码问题、大文件截断、二进制文件识别。我见过太多人写的read_file直接把整个 100MB 的日志读进来塞进上下文然后 API 直接报 token 超限。更麻烦的是沙箱隔离。你肯定不希望 Agent 在你本机的任意目录乱写。所以还得搞一个虚拟文件系统或者受限的工作目录这又是一堆路径规范化、越界检查的代码。2.2 记忆跨轮次、跨会话的连续性记忆分两层。短期记忆是当前对话的上下文这个模型 API 本身帮你管了。真正难的是长期记忆用户上次说我喜欢用 Python 不用 Java这次你希望 Agent 还记得或者 Agent 上次完成了一个任务这次要基于上次的结果继续。手写长期记忆你得决定存哪里文件数据库向量库、存什么原始对话摘要结构化事实、什么时候读每轮都读按需检索、什么时候写每轮都写任务结束时写。每一个决策都影响体验和成本。我早期做过一个每轮都把全部历史塞进去的方案结果 token 消耗爆炸而且模型被无关历史干扰回答质量反而下降。2.3 上下文压缩长对话的续命机制这是最容易被低估的一块。模型的上下文窗口是有限的哪怕现在动辄 128K、200K也架不住一个长任务跑几十轮。当对话接近窗口上限时你必须做点什么否则要么报错要么被迫丢弃早期信息。常见的压缩策略有几种滑动窗口只保留最近 N 轮简单但会丢信息、摘要压缩把早期对话总结成一段话保留语义但损失细节、分层记忆近期原文 远期摘要 关键事实抽取。每种都有取舍手写的话光是调这些策略的参数就够你喝一壶。2.4 工具编排与错误恢复让 Agent 不崩Agent 调用工具会失败——网络超时、参数格式错、返回结果不符合预期。一个健壮的 Agent 需要失败重试、错误信息回传给模型让它自己修正、工具调用超时控制、并发调用的结果合并。这些逻辑如果散落在主循环里代码会迅速变成一团乱麻。把这四块基建列出来你应该能理解为什么手写 Agent 基建是个无底洞了。它们彼此耦合文件系统的输出要进上下文上下文压缩要考虑记忆里的关键事实工具错误要触发记忆更新。deepagents 中间件的价值就是把这四块做成可插拔的模块用统一的接口串起来。3. deepagents 中间件的设计哲学为什么是中间件而不是框架理解了痛点再看 deepagents 的设计选择就顺理成章了。它没有把自己定位成又一个 Agent 框架市面上框架已经够多了而是定位成中间件层。这个定位差异很关键直接决定了它的使用方式和适用场景。3.1 中间件 vs 框架一个容易被混淆的区别框架Framework通常要求你按它的方式来——继承某个基类、实现某个方法、遵循它的生命周期。好处是结构统一坏处是侵入性强你想换个模型、换个工具调用方式可能要大改。中间件Middleware则是挂载式的——你保留自己的主循环和业务逻辑只在需要的地方挂上它提供的能力。deepagents 的中间件模式意味着你的 Agent 主循环还是你自己写但文件系统、记忆、压缩这些能力通过中间件注入进去。这个选择的好处是灵活。比如你已经在用某个 Agent 框架不想推倒重来那 deepagents 的中间件可以作为一个增强层叠加上去。反过来如果你从零开始也可以只挑你需要的中间件不用全盘接受。3.2 三大核心中间件的职责边界deepagents 把基建拆成了三个核心中间件职责边界划得很清楚中间件核心职责解决的问题典型触发时机文件系统中间件提供受限的读写/列目录/编辑能力Agent 无法操作外部文件模型请求文件操作时记忆中间件持久化关键信息跨轮次检索对话无连续性、重复问同样的事每轮对话前后上下文压缩中间件在超限前压缩历史长任务 token 爆炸上下文接近阈值时这种拆分的好处是可组合。你可以只用文件系统中间件比如做一个代码助手也可以三个全上比如做一个长期运行的自动化 Agent。每个中间件内部又做了抽象比如记忆中间件支持多种后端文件、内存、外部存储你可以按场景选。3.3 30 行代码背后的隐藏工作量标题说30 行代码搞定这不是夸张但要说清楚这 30 行省掉了什么。手写的话光是文件系统中间件涉及的路径安全校验、大文件处理、编码识别就够写两三百行记忆中间件的存取策略、检索逻辑又是两三百行上下文压缩的阈值判断、摘要生成、历史重组再来两三百行。加起来近千行而且每行都得测。deepagents 把这近千行封装成了配置项和几个 API 调用。你写的 30 行本质是声明式配置——告诉中间件我要什么能力而不是怎么实现这些能力。这是抽象带来的红利但也要清醒抽象意味着你放弃了部分控制权遇到边界情况时可能需要深入中间件内部去调。4. 30 行代码跑通第一个带基建的 Agent理论讲够了直接上代码。下面这个例子会搭一个具备文件读写、记忆、上下文压缩的 Agent你可以直接复制去跑。我会逐段解释每一行在干什么以及为什么这么写。4.1 环境准备与依赖安装先装依赖。deepagents 通常和某个 Agent 运行时配合使用这里假设你已经有一个基础的模型调用环境。pip install deepagents如果你用的是特定的模型 SDK按需安装。环境变量里配好你的模型 API Key这个各家不同按你实际用的来。注意中间件本身不绑定模型它只负责基建能力。模型调用还是走你自己的那套所以迁移成本很低。4.2 核心代码逐行拆解下面是一个最小可运行示例。我把它拆成几块讲实际写的时候是连在一起的。from deepagents import create_agent from deepagents.middleware import FileSystemMiddleware, MemoryMiddleware, CompressionMiddleware # 1. 初始化三个中间件 fs FileSystemMiddleware(workspace./agent_workspace, max_file_size1_000_000) memory MemoryMiddleware(backendfile, path./agent_memory.json) compression CompressionMiddleware(threshold0.8, strategysummarize) # 2. 组装 Agent agent create_agent( modelyour-model-name, middleware[fs, memory, compression], system_prompt你是一个能操作文件、有记忆的助手。 ) # 3. 跑起来 result agent.run(帮我看一下 workspace 里有哪些文件然后总结一下) print(result)第一段初始化中间件。FileSystemMiddleware的workspace参数指定了 Agent 能操作的根目录所有路径都会被限制在这个目录内这是安全的第一道防线。max_file_size限制单次读取的文件大小防止大文件撑爆上下文。MemoryMiddleware的backendfile表示用文件存记忆适合单机场景如果要多实例共享可以换成外部存储后端。path是记忆文件的落盘位置。CompressionMiddleware的threshold0.8是个关键参数意思是当上下文使用率达到 80% 时触发压缩。strategysummarize指定用摘要策略。这个阈值不能设太高比如 0.95否则压缩还没完成就可能超限也不能太低比如 0.5否则频繁压缩浪费算力还丢信息。第二段组装 Agent把三个中间件塞进middleware列表。顺序有讲究一般文件系统和记忆在前压缩在后因为压缩要处理的是前两者产生的上下文。第三段就是正常调用了。注意这里agent.run的输入是自然语言中间件会在背后自动处理文件操作、记忆读写、上下文压缩你不需要手动干预。4.3 跑通之后验证基建是否真的生效代码跑通不代表基建生效了。我建议做三个验证验证文件系统让 Agent 写一个文件然后你去./agent_workspace目录下看是否真的生成了。再让它尝试读一个 workspace 之外的文件比如/etc/hosts确认它被拒绝。验证记忆第一轮告诉它我叫 A 同学喜欢简洁的回答结束会话。第二轮新开会话问我叫什么看它是否记得。如果记不得检查记忆文件是否真的写入了。验证压缩这个稍微麻烦点需要构造一个长对话。你可以连续问 20 个问题观察日志里是否出现压缩触发的记录以及压缩后回答质量是否明显下降。5. 文件系统中间件路径安全与大文件处理的两个深坑文件系统中间件看起来最简单实际上坑最多。我在这块踩过的坑比记忆和压缩加起来还多。挑两个最典型的讲。5.1 路径穿越一个必须堵死的安全漏洞路径穿越Path Traversal是指 Agent 通过../这样的相对路径跳出你设定的工作目录。比如你限制它在./workspace但它请求读../../etc/passwd如果中间件没做规范化就可能读到系统文件。deepagents 的文件系统中间件默认会做路径规范化把请求路径转成绝对路径然后检查是否在 workspace 之下。但这里有个细节——符号链接symlink。如果 workspace 里有个软链接指向外部规范化后的路径可能仍然在 workspace 内但实际指向外部。严格的实现会解析符号链接后再检查。我的建议是如果你的场景对安全要求高除了依赖中间件的默认检查再在 workspace 层面做一层隔离比如用独立的系统用户运行或者容器化。中间件的检查是应用层的容器隔离是系统层的两层叠加才稳。5.2 大文件截断策略比你想的更重要前面提到max_file_size限制单次读取大小。但限制之后怎么办直接报错还是截断截断的话截哪部分deepagents 默认的策略是头部截断 提示读前 N 字节然后在结果里加一句文件过大仅显示前 N 字节。这个策略对日志类文件重要信息往往在开头或结尾不一定最优。我实际用下来更稳妥的做法是让 Agent 自己决定中间件先返回文件大小和行数让模型判断是读全部、读头部、读尾部还是用 grep 式的搜索。这需要中间件支持元信息查询能力。如果你的场景经常处理大文件值得花时间配置这套逻辑。提示处理日志文件时我习惯让 Agent 先list_dir看文件大小超过阈值就改用搜索关键词而不是读全文这样既省 token 又准。6. 记忆中间件存什么、何时读、怎么不变成垃圾场记忆中间件是最容易用着用着就废掉的一块。刚开始什么都存过一阵发现记忆文件里全是无关紧要的对话检索出来的东西反而干扰模型。核心问题是三个存什么、何时读、怎么清理。6.1 存什么原始对话 vs 结构化事实最朴素的做法是把每轮对话原文存下来。问题是噪声大——用户说嗯好的再试试这些也存进去检索时全是干扰。更好的做法是抽取结构化事实。比如用户说我用 Python 3.11项目在 ~/projects/demo抽取成{language: Python, version: 3.11, project_path: ~/projects/demo}。这样检索精准存储也省。deepagents 的记忆中间件支持配置抽取策略。我的经验是对话类信息存摘要事实类信息存结构化。摘要保留上下文结构化事实用于精确检索。两者结合效果比单一策略好很多。6.2 何时读每轮都读是成本陷阱每轮对话都把全部记忆塞进上下文是最容易犯的错。记忆一多token 成本飙升而且模型被大量无关信息干扰回答质量下降。正确做法是按需检索。中间件根据当前用户输入去记忆里检索相关条目只把相关的塞进上下文。这需要一个检索机制——可以是关键词匹配简单也可以是向量检索精准但重。deepagents 默认用的是轻量检索适合记忆量不大的场景。如果你的记忆条目上千建议换成向量检索后端。切换成本不高但效果提升明显。6.3 记忆清理别让它变成垃圾场记忆会随时间累积旧信息可能已经过时比如用户换了项目路径。如果不清理检索出来的可能是过期信息反而误导模型。我的做法是给记忆条目加时间戳和置信度。检索时优先返回近期、高置信度的条目。同时定期比如每周做一次清理把长期未被检索到的条目归档或删除。deepagents 的记忆中间件支持配置 TTL生存时间超过时间的条目自动失效这个功能很实用。7. 上下文压缩阈值、策略与压缩后失忆的应对上下文压缩是三个中间件里最玄学的一个。压得好长任务丝滑运行压得不好Agent 突然失忆把之前确认过的事忘了。这块我踩的坑最多也最有心得。7.1 阈值设定0.8 不是万能数字前面代码里用了threshold0.8这是个经验值不是铁律。阈值该设多少取决于你的压缩耗时和单轮 token 增量。如果压缩本身要调用模型生成摘要耗时可能几秒到十几秒。如果单轮对话 token 增量大比如每轮都读大文件那阈值要设低一点0.7给压缩留足时间。反之如果单轮增量小、压缩快可以设到 0.85。我的建议是先设 0.75观察几轮日志看压缩触发时上下文使用率是多少、压缩后降到多少、有没有出现压缩还没完成就超限的情况再微调。7.2 压缩策略摘要、抽取、还是分层deepagents 支持几种压缩策略各有适用场景摘要summarize把早期对话总结成一段话。适合对话类场景但细节会丢。抽取extract只保留关键事实和决策丢弃闲聊。适合任务型 Agent。分层hierarchical近期原文 中期摘要 远期事实。最复杂但效果最好。我实测下来任务型 Agent 用抽取策略最划算因为任务型对话里真正重要的就是做了什么决策、得到了什么结果闲聊本来就不该占上下文。对话型 Agent 则适合摘要策略因为语气和上下文连贯性重要。7.3 压缩后失忆如何保住关键信息压缩最大的风险是把不该压的压掉了。比如用户明确说这个参数必须是 42不能改结果被摘要成用户提到了一些参数要求模型下次就可能改掉。应对办法是给关键信息打标记。在记忆中间件里把这类硬约束单独存成高优先级条目压缩时永远不压这些条目每轮都注入上下文。deepagents 的记忆中间件支持固定记忆pinned memory的概念就是干这个的。我的经验是凡是用户用了必须一定不要这类词的都值得 pin 住。宁可多占点 token也别让 Agent 违背硬约束。8. 组合使用的实战心得与几个容易忽略的细节三个中间件单独用都不难组合起来用才是 deepagents 的真正价值也是容易出问题的地方。最后分享几个我在实际项目里总结的细节。8.1 中间件顺序为什么文件系统要在压缩之前中间件的执行顺序会影响结果。一般原则是产生上下文的中间件在前处理上下文的中间件在后。文件系统读取会产生内容进上下文记忆检索也会所以它们在前压缩处理的是已经产生的上下文所以在后。如果顺序反了比如压缩在文件系统之前那压缩时还没读到文件内容压了个寂寞读完文件又超限了。这个坑我踩过一次排查了半天才发现是顺序问题。8.2 日志没有日志的中间件就是黑盒中间件在背后做了很多事如果不打日志出问题时你根本不知道发生了什么。我强烈建议开启中间件的详细日志至少记录文件操作读了什么、写了什么、记忆读写存了什么、检索到什么、压缩触发何时触发、压缩前后 token 数。deepagents 的中间件支持日志级别配置。开发阶段开到 DEBUG生产环境开到 INFO。有了日志排查Agent 为什么突然失忆为什么读不到文件这类问题会快很多。8.3 成本控制记忆和压缩都是隐形开销记忆检索和上下文压缩都会调用模型尤其是摘要策略这些是隐形成本。一个长任务跑下来压缩可能调用模型十几次成本不容忽视。控制办法压缩策略优先选不调用模型的比如抽取策略里的规则抽取只在必要时用模型摘要。记忆检索优先用关键词匹配向量检索作为兜底。这样能把隐形成本压到最低。8.4 什么时候不该用中间件最后说个反直觉的不是所有场景都适合上中间件。如果你的 Agent 就是个简单的问答机器人不需要文件操作、不需要跨会话记忆、对话也不会长到超限那上中间件纯属增加复杂度。中间件的价值在基建复杂到一定程度时才体现。判断标准很简单如果你手写这些基建的代码超过 200 行就该考虑中间件了如果只有几十行自己写反而更可控。我在实际项目里的体会是deepagents 这类中间件最大的价值不是省代码而是省心——它把那些容易出错的边界情况路径安全、大文件、压缩失忆都处理过了你踩坑的概率大大降低。但前提是你得理解它在背后做了什么否则出了问题连从哪查都不知道。这也是我写这篇长文的初衷工具再好用也得知道它的边界在哪。