代码学习参考https://github.com/Bald0Wang/deepagents-in-action官方教程参考Deep Agents 实战 — 从零构建生产级 AI Agent 的完整指南主要代码学习参照如上github地址同时配套官方教程学习。ch01-ch02一、从 Framework 到 Harness层次代表核心价值我的理解底层 RuntimeLangGraph持久化、流式、人机协作、状态管理Agent 世界的操作系统中层 FrameworkLangChain模型抽象、工具接口、Agent 循环、中间件在 LangGraph 之上包了一层更易上手上层 HarnessDeep Agents预置文件系统、任务规划、子 Agent、长期记忆直接给你一个装好的工具间二、五分钟上手第一个Deep Agentfrom langchain_openai import ChatOpenAI from deepagents import create_deep_agent model ChatOpenAI( modelos.environ.get(MODEL_NAME, deepseek-v4-flash), api_keyos.environ[DEEPSEEK_API_KEY], base_urlhttps://api.deepseek.com/v1, # 硅基流动则是 api.siliconflow.cn/v1 ) agent create_deep_agent( modelmodel, tools[get_weather], # 自定义工具 system_promptYou are a helpful assistant., ) result agent.invoke({messages: [{role: user, content: 北京今天天气怎么样}]}) print(result[messages][-1].content)结构很清晰注册模型写工具函数注册成工具invoke自定义工具的三要素参数类型标注告诉Agent每个参数该传什么类型Docstring: 告诉Agent这个工具的用途何时调用默认值标记可选参数减少必填降低出错三、基础环境配置本项目基于linux系统作为windows用户可以配置WSL来进行学习。具体详细配置步骤可以见本人另一篇帖子。WSLWindows Subsystem for Linux是微软为 Windows 用户提供的一个子系统它允许你在 Windows 上原生运行 Linux不是虚拟机不是双系统直接使用 Bash、apt、gcc、Python、Node.js 等 Linux 工具。安装/启动命令行wsl --install -d Ubuntu-24.04 //从网上下载并安装Ubuntu 从cmd进入Ubuntu命令 wsl -d Ubuntu-24.04 //启动并进入已安装好的Ubuntu进入项目目录下激活虚拟环境source .venv/bin/activateVs Code打开当前linux项目(此时还在Ubuntu内 输入code .)code .排查网络相关问题时可输入命令行查看代理配置env | gerp -i proxych03虚拟文件系统一、本章核心概念1. 七个工具把它们当作 CLI 的“文件操作语言”工具CLI 助手通常何时调用关键实践ls用户说“看看项目有什么”先理解目录再决定检索范围glob找所有 Python、测试或 Markdown 文件适合“按文件名/扩展名找”grep找 TODO、配置项、函数名、错误文本适合“按内容找”先文件级再看命中行read_file阅读 README、报错日志、大文件使用offset/limit分片避免整文件进上下文write_file新建报告、迁移脚本、草稿文件对产物写入目录做隔离edit_file精准改一处配置或文案用完整旧字符串替换匹配多处时应拒绝或显式全量替换delete删除 Agent 自己生成的临时文件生产环境应纳入审批/审计2. 五种常见后端落到具体应用后端真实落点与生命周期最适合的应用不适合什么CLI 示例StateBackend默认LangGraph Agent State同一线程可见换线程丢失学习、一次性任务、推理草稿用户长期偏好、需要交付给人类的真实文件生成本次排查计划和临时检索结果FilesystemBackend本地磁盘写入会持久保存本地编程助手、受控 CI 工作区、文档批处理Web 服务直接暴露给外部用户在仓库副本中改 README、生成报告LocalShellBackend本地磁盘 宿主机shellTrue个人开发机上可信的代码助手生产环境、多用户系统、处理不可信输入pytest -q、格式化、Git 状态检查StoreBackendLangGraph Store跨线程持久用户偏好、长期知识、跨会话任务档案临时大产物、需要真实项目文件的场景记住“该用户习惯使用 pytest”CompositeBackend根据路径把数据路由到多个后端真正的产品临时工作区 长期记忆共存只有一个简单生命周期的小脚本/workspace/临时/memories/持久二、核心代码理解1. 01_builtin_file_tools.py分为Part A 和 Part BPart A不用 LLM直接测文件后端直接调用FilesystemBackend验证write / read / glob / grep / edit / delete结果确定适合用assert做测试重点是确认“底层文件能力没问题”沙箱目录.sandboxroot_dirSANDBOX指定真实文件只能写到.sandbox里virtual_modeTrue让/workspace/a.txt映射到.sandbox/workspace/a.txt作用是限制文件访问范围避免误操作真实系统目录分片读取read(offset100, limit50)表示跳过前 100 行再读 50 行适合大文件避免一次把整个文件放进上下文glob 和 grepglob找文件路径比如**/*.mdgrep找文件内容比如搜索TODO常见思路先找文件再找内容再局部读取edit 后再验证先把一处TODO改成DONE再grep(TODO)从 3 处变 2 处说明修改真的生效Part B让 Agent 自己调文件工具不再手写backend.write()、backend.read()只给 Agent 自然语言任务Agent 自己决定何时调用write_file / ls / read_file / grep / edit_file / deletePart A 和 Part B 的区别Part A测“工具本身对不对”Part B测“LLM 会不会正确使用工具”最核心的测试思想先做无 LLM 的确定性测试再做有 LLM 的端到端测试这样出问题时更容易判断是工具坏了还是 Agent 调度错了2. 02_context_auto_management.pyDeep Agent 的上下文并不是简单地不断把所有内容塞给 LLM而是会通过“卸载”和“总结”两种机制主动控制 Context Window。Part Atool_token_limit_before_evict 低于工具输出 token 数时工具结果自动写入虚拟文件系统对话历史只留「路径引用 前 10 行预览」。Part BSummarizationMiddleware 用 trigger{messages: N} 低成本触发完整历史写入文件存档对话历史替换为结构化摘要。Part APart B防什么单个 Tool Result 太大整个对话历史太长MiddlewareFilesystemMiddlewareSummarizationMiddleware触发条件tool_token_limit_before_evict300trigger{messages: 6}被处理的内容工具返回结果老对话消息原文去哪/large_tool_results/.../conversation_history/...上下文里留下什么引用 previewsummary 最近上下文最终目的减少超大工具结果占用 token防止长对话撑爆 context3. 03_backends.py覆盖课程五种后端- StateBackend : 临时存储同线程内持久换线程即丢- FilesystemBackend : 本地磁盘 virtual_mode 路径沙箱- LocalShellBackend : 文件工具 execute本地 Shell无沙箱- StoreBackend : 跨线程持久化namespace 按用户隔离- CompositeBackend : 混合路由/memories/ - Store其余 - StateBackend数据真正放哪换thread_id后进程结束后特点StateBackendAgent state❌ 看不到通常丢失临时工作区FilesystemBackend本地磁盘✅ 文件还在✅ 还在真实文件系统LocalShellBackend本地磁盘✅✅还能执行 ShellStoreBackendLangGraph Store✅ 能看到取决于 Store 实现长期记忆、按 namespace 隔离CompositeBackend按路径分流看路由看路由不同目录使用不同存储