引言为什么传统Agent总是浅尝辄止你有没有遇到过这样的尴尬场景让AI助手帮你完成一个复杂任务比如调研一下LangGraph技术写一份技术报告并创建相应的代码示例。刚开始AI热情满满调用几个工具搜索一些资料。但没过多久就开始迷失方向——要么陷入死循环要么忘记最初的目标要么因为上下文太长而失忆。这就是传统Agent的致命缺陷它们太浅了。一个简单的LLM调用工具循环架构只能处理单步骤任务。一旦面对需要多轮规划、跨文件操作、长期记忆保持的复杂场景就会力不从心。但现实世界的问题恰恰都是复杂的、多步骤的、需要长期规划的。这就是为什么像Claude Code、Deep Research、Manus这样的应用能够脱颖而出——它们不是简单的工具调用器而是具备深度思考能力的智能体。现在LangChain团队开源了DeepAgents将这些深度智能体的核心能力封装成一个可复用的Python SDK。一、DeepAgents到底是什么1.1 核心定位DeepAgents是LangChain团队继LangGraph、LangChain之后推出的第三个独立开源Agent框架专门用于构建能够处理复杂、多步骤任务的深度智能体。它的目标很明确让智能体具备长期规划与分工能力而不仅仅是工具调用。1.2 与Claude Code的关系DeepAgents的设计灵感直接来源于Claude Code等成功的编程智能体。它观察到一个关键模式所有成功的深度Agent都具备四个核心能力规划工具将复杂任务分解为可执行的子任务子代理Sub-Agents为不同任务创建隔离的上下文窗口文件系统提供持久化状态存储精细化提示词教会模型如何有效使用这些工具DeepAgents将这四大能力打包成一个可组合的框架让你无需从零搭建基础设施。1.3 五大核心能力DeepAgents内置了五大核心能力开箱即用能力作用内置工具规划Planning任务分解与进度追踪write_todos文件系统读写、编辑、搜索文件read_file、write_file、edit_file、ls、glob、grepShell访问在隔离沙箱中执行命令execute子代理将复杂工作委托给具有新鲜上下文的子代理task上下文管理对话过长时自动摘要压缩compact_conversation注意这些不是普通的工具而是通过中间件系统深度集成的能力。二、架构全景图从Monorepo到编译图2.1 Monorepo设计哲学DeepAgents采用Monorepo架构所有代码集中在一个仓库中但分为多个独立版本化的包deepagents/├── libs/│ ├── deepagents/ # 核心SDK│ ├── cli/ # 终端编码代理类似Claude Code│ ├── acp/ # 编辑器集成Zed、VS Code│ ├── evals/ # 评估框架LangSmith追踪│ └── partners/ # 沙箱后端集成│ ├── daytona/ # Daytona远程沙箱│ ├── modal/ # Modal无服务器计算│ ├── quickjs/ # QuickJS进程内沙箱│ └── runloop/ # Runloop沙箱├── examples/ # 示例应用│ ├── deep_research/ # 多步骤网络研究│ ├── content-builder-agent/ # 内容生成代理│ ├── text-to-sql-agent/ # 自然语言转SQL│ └── ralph_mode/ # 自主循环模式└── AGENTS.md # 开发指南这种设计的优势在于•独立版本化每个包可以独立发布和升级•代码复用核心逻辑共享减少重复•生态扩展轻松集成第三方后端和工具2.2 create_deep_agent工厂函数整个框架的入口点是一个看似简单的函数create_deep_agent()。from deepagents import create_deep_agentagent create_deep_agent()result agent.invoke({ messages: [{role: user, content: 研究LangGraph并写一份总结}]})就这么两行代码你就得到了一个功能完整的深度智能体但这个工厂函数背后隐藏着一个复杂的组装过程create_deep_agent 配置参数 模型选择claude-sonnet-4-6 中间件栈默认5层中间件 后端选择StateBackend 工具注册文件系统子代理 LangGraph编译器 CompiledStateGraph编译状态图 流式推理 状态检查点 中断控制这个函数返回的是一个编译后的LangGraph状态图CompiledStateGraph这意味着你可以使用LangGraph的所有高级功能流式响应、状态持久化、检查点恢复等。2.3 核心参数详解create_deep_agent()支持以下关键参数参数作用默认值model指定LLM模型任何支持工具调用的模型claude-sonnet-4-6tools额外的自定义工具Nonesystem_prompt覆盖基础系统提示词内置提示词middleware添加或替换中间件层默认栈subagents配置委托子代理通用代理skillsSKILL.md文件路径用于工作流发现NonememoryAGENTS.md文件路径用于持久化上下文Nonebackend可插拔的文件/命令存储后端StateBackendcheckpointerLangGraph状态持久化Noneinterrupt_on人机协同的工具审批配置None关键要求传入的LLM必须支持工具调用Tool Calling。默认使用Anthropic的Claude Sonnet 4.6但你可以切换到任何提供商OpenAI、Gemini、Ollama等。三、中间件系统DeepAgents的灵魂这是DeepAgents最核心、最优雅的设计。3.1 中间件 vs 普通工具在理解中间件之前先要明确一个关键区别•普通工具被LLM调用执行特定功能返回结果•中间件继承自AgentMiddleware拦截每一次LLM请求在请求发送前进行修改Tools LLM 中间件2 中间件1 Agent User Tools LLM 中间件2 中间件1 Agent User 中间件可以 1. 修改系统提示词 2. 动态过滤工具 3. 跨轮次追踪状态 4. 注入上下文信息 用户请求 拦截请求 处理并传递 修改后的请求 调用工具 返回结果 生成响应 处理响应 最终响应 返回给用户中间件的能力远超普通工具• 动态工具过滤• 系统提示词注入• 消息转换• 跨轮次状态追踪3.2 默认中间件栈create_deep_agent()自动组装的默认中间件栈包含5层用户请求 FilesystemMiddleware文件系统操作 SubAgentMiddleware子代理委托 SummarizationMiddleware自动摘要 MemoryMiddlewareAGENTS.md注入 SkillsMiddlewareSKILL.md工作流 LLM让我们逐层拆解3.2.1 FilesystemMiddleware文件系统中间件提供的工具ls、read_file、write_file、edit_file、glob、grep、execute核心行为• 根据后端能力过滤execute工具某些沙箱不允许shell执行• 将大型工具结果驱逐到文件系统避免上下文爆炸• 提供完整的文件操作能力支持本地和远程存储技术亮点# 示例大型结果自动驱逐到文件系统# 当工具返回超过阈值时自动写入临时文件if len(tool_result) MAX_CONTEXT_SIZE: file_path backend.write_temp_file(tool_result) return f结果已保存到: {file_path}3.2.2 SubAgentMiddleware子代理中间件提供的工具task核心行为• 将子代理指令注入系统提示词• 生成临时子代理拥有独立的上下文窗口• 支持任务委托和结果汇总工作原理后端存储 子代理 SubAgentMiddleware 父代理 后端存储 子代理 SubAgentMiddleware 父代理 子代理拥有 - 独立的上下文窗口 - 临时文件系统 - 专属工具集 调用task工具 创建临时工作区 启动子代理 注入独立上下文 执行子任务 返回结果 清理临时工作区 汇总结果使用场景# 父代理遇到复杂任务时可以委托给子代理agent.invoke({ messages: [{ role: user, content: 使用task工具让子代理负责代码测试部分 }]})3.2.3 SummarizationMiddleware摘要中间件提供的工具自动触发无需显式工具核心行为• 监控token使用量超过阈值时触发压缩• 将历史对话卸载到后端存储• 生成结构化摘要保持对话连续性技术实现class SummarizationMiddleware(AgentMiddleware): def__init__(self, threshold_tokens100000): self.threshold threshold_tokens self.token_count 0 defbefore_llm_call(self, state): self.token_count count_tokens(state[messages]) ifself.token_count self.threshold: # 触发摘要生成 summary self.generate_summary(state[messages]) # 将历史卸载到后端 backend.store_conversation_history(state[messages]) # 替换为摘要 state[messages] [summary] return state8段式上下文压缩DeepAgents采用结构化压缩策略将对话分为8个逻辑段系统指令、工具定义、历史摘要、当前任务等确保关键信息不丢失。3.2.4 MemoryMiddleware记忆中间件提供的工具无上下文注入核心行为• 加载AGENTS.md文件• 在每一轮对话中将内容注入系统提示词• 提供持久化上下文跨会话保持记忆使用示例# AGENTS.md## 项目规范- 使用TypeScript编写- 遵循ESLint规则- 所有函数必须有类型注解## 偏好设置- 优先使用函数式编程- 避免使用any类型中间件会自动读取这个文件并在每次LLM调用时注入system_prompt \n\n## 项目记忆来自AGENTS.md\nsystem_prompt backend.read(AGENTS.md)3.2.5 SkillsMiddleware技能中间件提供的工具无渐进式披露核心行为• 从后端源发现SKILL.md文件• 将元数据注入系统提示词• 支持工作流复用和最佳实践沉淀SKILL.md示例# SKILL.md: React组件开发## 触发条件当用户请求创建React组件时## 工作流程1. 分析组件需求2. 创建TypeScript接口3. 实现组件逻辑4. 添加单元测试5. 编写文档## 代码模板export interface Props { // 属性定义}export const Component: React.FCProps (props) { // 实现};中间件会自动发现这个文件并在适当时机提示LLM使用这个工作流。3.3 中间件执行流程完整的中间件执行流程如下是 否 是 否 用户请求 FilesystemMiddleware1. 注入文件系统工具2. 配置execute权限 SubAgentMiddleware1. 注入task工具2. 配置子代理提示词 SummarizationMiddleware1. 检查token使用量2. 必要时触发摘要 MemoryMiddleware1. 读取AGENTS.md2. 注入到系统提示词 SkillsMiddleware1. 扫描SKILL.md2. 渐进式披露技能 LLM调用 工具调用 执行工具 生成响应 结果过大 写入文件系统 返回给用户关键设计原则•中间件顺序很重要从底层文件系统到高层技能逐层封装•双向流动请求时从上到下响应时从下到上•职责分离每个中间件只负责一个领域3.4 何时使用中间件 vs 普通工具这是一个关键的设计决策使用中间件当你的工具需要• 修改系统提示词• 跨轮次追踪状态• 对所有SDK消费者可用• 动态过滤或注入上下文使用普通工具tools[]列表当• 函数是无状态的• 功能是自包含的• 不需要修改提示词• 不需要跨轮次跟踪四、可插拔后端系统抽象的力量4.1 BackendProtocol抽象DeepAgents的所有文件和命令操作都通过BackendProtocol抽象层进行。class BackendProtocol(Protocol): 后端协议定义 defread(self, path: str) - str: 读取文件 ... defwrite(self, path: str, content: str) - None: 写入文件 ... defedit(self, path: str, edits: List[Edit]) - None: 编辑文件 ... defls(self, path: str) - List[str]: 列出目录 ... defglob(self, pattern: str) - List[str]: glob匹配文件 ... defgrep(self, pattern: str, path: str) - List[Match]: 搜索文件内容 ... defupload_files(self, files: List[File]) - None: 上传文件 ... defdownload_files(self, paths: List[str]) - List[File]: 下载文件 ...classSandboxBackendProtocol(BackendProtocol): 沙箱后端扩展协议 defexecute(self, command: str) - ExecutionResult: 执行shell命令 ...这个抽象的价值•同一份代理代码可以在不同后端上运行•无需修改业务逻辑只需切换后端实现•支持懒加载通过BackendFactory实现运行时配置4.2 后端实现全景图DeepAgents提供了多种后端实现BackendProtocol抽象接口 StateBackend内存/临时存储 FilesystemBackend本地磁盘 LangSmithBackend云存储 Partner Backends第三方沙箱 Daytona远程开发沙箱 Modal无服务器计算 Runloop托管沙箱 QuickJS进程内JS沙箱后端包使用场景StateBackend内置临时、内存存储默认FilesystemBackend内置本地磁盘访问开发环境LangSmithBackend内置通过LangSmith云托管Daytonalibs/partners/daytona远程开发沙箱Modallibs/partners/modal无服务器计算环境Runlooplibs/partners/runloop托管沙箱执行QuickJSlibs/partners/quickjs进程内JavaScript沙箱4.3 后端选择策略如何选择适合的后端开发阶段# 使用本地文件系统便于调试from deepagents.backends import FilesystemBackendagent create_deep_agent( backendFilesystemBackend(root_path./workspace))生产环境# 使用远程沙箱确保安全隔离from deepagents.partners.daytona import DaytonaBackendagent create_deep_agent( backendDaytonaBackend( api_keyos.environ[DAYTONA_API_KEY], sandbox_idmy-sandbox ))云原生场景# 使用LangSmith后端便于追踪和监控from deepagents.backends import LangSmithBackendagent create_deep_agent( backendLangSmithBackend( project_idmy-project, api_keyos.environ[LANGSMITH_API_KEY] ))4.4 后端工厂模式支持懒加载和运行时配置from deepagents import BackendFactory, ToolRuntimedef backend_factory(runtime: ToolRuntime): 后端工厂函数 if runtime.environment production: return DaytonaBackend(api_keyget_api_key()) else: return FilesystemBackend(root_path./dev-workspace)agent create_deep_agent(backendbackend_factory)优势• 延迟初始化减少启动开销• 根据运行时环境动态选择后端• 支持热切换后端五、核心技术亮点深度剖析5.1 任务规划机制DeepAgents的规划能力基于write_todos工具实现。工作流程待办存储 LLM Agent User 待办存储 LLM Agent User 创建子代理 alt [需要委托] loop [执行子任务] loop [任务执行循环] 复杂任务请求 分析任务 分解为子任务 创建待办列表 返回todo_id 执行当前任务 更新进度 确认更新 调用task工具 标记完成 返回最终结果代码示例# 自动任务规划result agent.invoke({ messages: [{ role: user, content: 完成以下任务 1. 调研LangGraph最新文档 2. 分析其核心架构 3. 编写技术报告 4. 创建示例代码 }]})# LLM会自动调用write_todos创建计划# 待办列表# [ ] 搜索LangGraph文档# [ ] 阅读核心概念# [ ] 分析架构图# [ ] 撰写报告大纲# [ ] 编写示例代码# [ ] 完成报告5.2 子代理委托机制子代理是DeepAgents处理复杂任务的关键。核心技术上下文隔离每个子代理拥有独立的上下文窗口临时文件系统子代理在临时工作区操作结果汇总父代理收集子代理结果并整合示例# 父代理委托子代理parent_agent.invoke({ messages: [{ role: user, content: 使用task工具让子代理负责单元测试部分 }]})# 子代理执行# 1. 创建临时工作区# 2. 编写测试代码# 3. 运行测试# 4. 返回结果# 父代理汇总# 子代理已完成测试通过率95%优势• 避免上下文污染• 并行执行多个子任务• 每个子代理专注单一职责5.3 上下文管理机制DeepAgents采用多层上下文管理策略上下文管理 短期记忆当前对话 中期记忆AGENTS.md 长期记忆后端存储 摘要记忆压缩历史 消息队列token限制内 项目规范偏好设置工作流 完整对话历史工具执行记录文件变更 结构化摘要关键决策任务进度自动摘要触发# 当对话超过阈值时if token_count 100000: # 1. 生成结构化摘要 summary { 任务目标: 调研LangGraph, 已完成: [文档搜索, 架构分析], 待完成: [编写报告], 关键发现: [基于图的工作流, 中间件系统] } # 2. 将完整历史卸载到后端 backend.store(conversation_history.json, full_messages) # 3. 替换为摘要 messages [format_summary(summary)]5.4 文件系统操作文件系统是DeepAgents的基石。核心操作# 1. 读取文件content backend.read(src/main.py)# 2. 写入文件backend.write(src/new_file.py, print(hello))# 3. 编辑文件支持差异编辑backend.edit(src/main.py, [ {old_str: print(hello), new_str: print(world)}])# 4. 列出目录files backend.ls(./src)# 5. 全局搜索matches backend.glob(**/*.py)# 6. 内容搜索results backend.grep(def main, ./src)# 7. 执行命令沙箱后端result backend.execute(python src/main.py)大型结果驱逐# 当工具返回过大时def handle_large_result(result: str) - str: if len(result) MAX_CONTEXT_SIZE: # 自动写入临时文件 temp_path f/tmp/result_{uuid.uuid4()}.txt backend.write(temp_path, result) return f结果过大已保存到: {temp_path} return result5.5 完整代码示例让我们看一个完整的实战示例from deepagents import create_deep_agentfrom deepagents.backends import FilesystemBackendfrom langchain_anthropic import ChatAnthropic# 1. 配置后端backend FilesystemBackend(root_path./my-project)# 2. 创建代理agent create_deep_agent( modelChatAnthropic(modelclaude-sonnet-4-6), backendbackend, memory[./AGENTS.md], # 加载项目记忆 skills[./skills/], # 加载技能库 system_prompt你是一个专业的软件工程师。 遵循AGENTS.md中的规范使用SKILL.md中的工作流。 遇到复杂任务时使用task工具委托子代理。)# 3. 执行复杂任务result agent.invoke({ messages: [{ role: user, content: 为项目创建一个完整的用户认证模块 - 实现JWT认证 - 添加密码加密 - 编写单元测试 - 生成API文档 }]})# 4. 流式响应for chunk in agent.stream({ messages: [{role: user, content: 开始开发}]}): ifmessagesin chunk: msg chunk[messages][-1] print(f{msg[role]}: {msg[content]})六、实战应用场景6.1 场景一深度研究代理# 多步骤网络研究from deepagents import create_deep_agentresearch_agent create_deep_agent( tools[tavily_search], # 网络搜索工具 system_prompt你是一个专业研究员。使用search工具收集信息使用write_todos规划研究步骤。)result research_agent.invoke({ messages: [{ role: user, content: 研究LangGraph的技术架构写一份5000字的技术报告 }]})# 代理会自动# 1. 制定研究计划# 2. 搜索相关文档# 3. 阅读关键资料# 4. 整理笔记# 5. 撰写报告6.2 场景二内容生成代理# 带记忆和技能的内容生成content_agent create_deep_agent( memory[./content_style.md], # 写作风格 skills[./skills/blog_post.md], # 博客写作流程 backendFilesystemBackend(root_path./content))result content_agent.invoke({ messages: [{ role: user, content: 写一篇关于DeepAgents的技术博客 }]})# 代理会# 1. 遵循写作风格指南# 2. 使用博客写作工作流# 3. 保存草稿到文件系统# 4. 迭代优化内容6.3 场景三Text-to-SQL代理# 自然语言转SQLsql_agent create_deep_agent( tools[execute_sql], memory[./database_schema.md], # 数据库 schema system_prompt你是一个SQL专家。 根据database_schema.md中的表结构 将自然语言转换为SQL查询。)result sql_agent.invoke({ messages: [{ role: user, content: 找出上个月销售额最高的10个产品 }]})# 代理会# 1. 理解查询需求# 2. 参考schema生成SQL# 3. 执行查询# 4. 返回结果七、性能优化与最佳实践7.1 性能优化技巧1. 合理设置摘要阈值from deepagents.middleware import SummarizationMiddlewareagent create_deep_agent( middleware[ SummarizationMiddleware(threshold_tokens50000) # 降低阈值更早触发摘要 ])2. 使用检查点恢复from langgraph.checkpoint import MemorySaveragent create_deep_agent( checkpointerMemorySaver())# 长时间任务可以中断后恢复config {configurable: {thread_id: task_123}}result agent.invoke(state, configconfig)3. 并行执行子代理# 同时启动多个子代理tasks [ agent.invoke({messages: [{role: user, content: 任务1}]}), agent.invoke({messages: [{role: user, content: 任务2}]}), agent.invoke({messages: [{role: user, content: 任务3}]}),]results await asyncio.gather(*tasks)7.2 最佳实践1. 精心设计AGENTS.md# AGENTS.md## 项目结构- src/ - 源代码- tests/ - 单元测试- docs/ - 文档## 编码规范- 使用TypeScript- 所有函数必须有类型注解- 遵循ESLint规则## 测试要求- 覆盖率80%- 每个模块必须有单元测试- 使用Jest框架2. 创建可复用的SKILL.md# SKILL.md: API开发## 触发条件当用户请求创建REST API时## 工作流程1. 定义路由结构2. 实现业务逻辑3. 添加错误处理4. 编写API文档5. 创建集成测试## 模板代码import { Router } from express;export const router Router();router.get(/endpoint, async (req, res) { try { // 业务逻辑 res.json(result); } catch (error) { res.status(500).json({ error: error.message }); }});3. 选择合适的后端• 开发FilesystemBackend• 测试StateBackend快速、隔离• 生产Daytona/Modal安全、可扩展八、CLI与生态工具DeepAgents不仅仅是SDK还提供了完整的生态工具链。8.1 Deep Agents CLI类似于Claude Code的终端编码代理# 安装pip install deepagents-cli# 使用deepagent# 交互式终端(deepagent) 帮我修复这个bug功能特性• 交互式TUI界面• 流式响应• 网络搜索集成• 对话恢复• 远程沙箱支持• 持久化记忆• 自定义技能• 无头模式脚本化• 人机协同审批8.2 ACP连接器编辑器集成支持在支持ACP的编辑器如Zed中运行Deep Agent// .zed/settings.json{ agent: { type: deepagents, model: claude-sonnet-4-6, backend: filesystem }}优势• 无缝集成编辑器• 动态模型切换不丢失对话历史• 直接操作项目文件8.3 评估框架DeepAgents提供行为测试框架from deepagents.evals import run_evaluationresults run_evaluation( agentmy_agent, test_cases[ { input: 创建用户登录功能, expected: [auth.py, test_auth.py], assertions: [ success: 文件必须存在, efficiency: 工具调用10次 ] } ])# 结果追踪到LangSmith# 生成雷达图跨模型对比两层断言•成功断言硬失败验证正确性•效率断言仅记录不失败九、设计哲学与安全模型9.1 信任LLM安全模型DeepAgents遵循**“信任LLM”**的安全模型• 代理可以做工具允许的任何事情• 边界应该在工具和沙箱层强制执行•不依赖模型自我约束实践建议# 错误做法期望模型自律# 请不要删除重要文件# 正确做法在工具层限制class SafeFilesystemBackend(BackendProtocol): def write(self, path: str, content: str): if path in PROTECTED_FILES: raise PermissionError(无法写入受保护文件) # 正常写入9.2 开源与Provider无关•100%开源MIT许可证•Provider无关支持任何支持工具调用的LLM•基于LangGraph生产级运行时特性# 可以切换到任何模型agent create_deep_agent(modelopenai:gpt-4o)agent create_deep_agent(modelgemini:gemini-pro)agent create_deep_agent(modelollama:llama3)十、总结与展望10.1 DeepAgents的核心价值通过这篇文章我们深入剖析了DeepAgents的技术架构中间件系统这是DeepAgents的灵魂通过5层中间件实现了文件系统、子代理、摘要、记忆、技能等核心能力可插拔后端BackendProtocol抽象让同一份代码可以在内存、本地磁盘、远程沙箱上运行基于LangGraph利用编译状态图获得流式响应、状态持久化、检查点恢复等生产级特性开箱即用create_deep_agent()一行代码获得完整功能同时保持高度可定制10.2 与LangChain生态的关系DeepAgents与LangChain、LangGraph形成清晰分工•LangChain基础的LLM工具链•LangGraph工作流编排•DeepAgents深度智能体框架三者可以组合使用构建复杂AI应用。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】