一、概述与定位1.1 什么是 Deep Agentsdeepagents是一个构建于 LangChain 核心构建块之上的独立库以 LangGraph 作为运行时引擎是最简便的方式来构建由 LLM 驱动的 agent 和应用——内置任务规划、文件系统上下文管理、子 agent 派发和长期记忆等能力。create_deep_agent是这个库的核心入口函数其设计理念可以用一句话概括在标准工具调用循环之上以声明式参数组合出生产级 agent。这与框架不同——框架要求开发者理解底层图结构Harness 则把工程复杂度封装在内部对外暴露语义清晰的配置接口。这一设计的源头来自对 Claude Code 架构的研究与抽象。研究发现使 agent 真正具备深度执行能力的要素是四个组合的协同详尽的系统提示词、子 agent 机制、对文件系统的访问权限以及任务规划工具。create_deep_agent正是这四项能力的统一入口。1.2 在技术栈中的位置层次组件职责运行时LangGraph图执行、checkpointer、store、streaming、HITL 暂停恢复构建块LangChain模型抽象BaseChatModel、工具协议BaseTool、init_chat_modelHarnessdeepagents中间件管道、文件系统、子 agent、规划工具、上下文压缩二、完整方法签名defcreate_deep_agent(model:str|BaseChatModel|NoneNone,tools:Sequence[BaseTool|Callable|dict]|NoneNone,*,system_prompt:str|SystemMessage|NoneNone,middleware:Sequence[AgentMiddleware](),subagents:list[SubAgent|CompiledSubAgent]|NoneNone,skills:list[str]|NoneNone,memory:list[str]|NoneNone,response_format:ResponseFormat|NoneNone,context_schema:type[Any]|NoneNone,checkpointer:Checkpointer|NoneNone,store:BaseStore|NoneNone,backend:BackendProtocol|BackendFactory|NoneNone,interrupt_on:dict[str,bool|InterruptOnConfig]|NoneNone,debug:boolFalse,name:str|NoneNone,cache:BaseCache|NoneNone,)-CompiledStateGraph强制要求所使用的 LLM 必须支持工具调用Tool Calling。三、返回值CompiledStateGraph函数返回一个 LangGraphCompiledStateGraph实例这是一个完整配置、可立即执行的 agent 图。该对象支持以下核心接口方法说明.invoke(input, config)同步调用阻塞直到完成返回最终 state.ainvoke(input, config)异步调用适合 async/await 环境.stream(input, config)流式调用逐步产生 state 更新事件.astream(input, config)异步流式调用.get_graph(xrayTrue)获取图结构对象可调用.draw_mermaid_png()可视化标准调用形式agentcreate_deep_agent(tools[my_tool])resultagent.invoke({messages:[{role:user,content:完成这个任务}]},config{configurable:{thread_id:thread-001}})四、参数详解所有参数按功能语义分为四个层次模型层 → model 能力扩展层 → tools · middleware · subagents · skills · memory 状态持久化层 → checkpointer · store · backend 运行时控制层 → system_prompt · interrupt_on · response_format context_schema · debug · name · cache4.1model类型str | BaseChatModel | None默认值claude-sonnet-4-6支持三种传入形式字符串如openai:gpt-5内部调用init_chat_model、已初始化的BaseChatModel实例、或None使用默认模型。提供商示例字符串备注Anthropicclaude-sonnet-4-6默认原生支持 Prompt Caching 中间件OpenAIopenai:gpt-5默认启用 Responses API精细控制请传初始化实例Azure OpenAIazure_openai:gpt-4.1需设置相应环境变量Google Geminigoogle_genai:gemini-2.5-flash需安装langchain[google-genai]AWS Bedrockanthropic.claude-3-5-sonnet...需配置 AWS credentials4.2tools类型Sequence[BaseTool | Callable | dict] | None默认值None用户自定义工具与以下内置工具并联组合共同暴露给 LLM工具提供方功能write_todosTodoListMiddleware任务规划强制外显计划ls / read_file / write_file / edit_file / glob / grepFilesystemMiddleware虚拟文件系统操作executeFilesystemMiddleware沙箱执行 shell 命令仅限沙箱 backendtaskSubAgentMiddleware委托子 agent工具推荐使用标准 Python 函数配合完整类型注解和 docstring框架自动提取 schematooldefquery_database(sql:str,limit:int10)-list[dict]:在数据库中执行查询。 Args: sql: SQL 查询语句 limit: 返回最大行数 returndb.execute(sql,limitlimit)4.3system_prompt类型str | SystemMessage | None默认值None自定义系统指令。传入字符串时前置拼接到内置 base agent prompt 之前传入SystemMessage则作为额外内容块追加。该参数不替换内置 prompt仅用于补充业务特定的角色定义或行为约束。最终系统提示词由多个部分按固定顺序组装详见第六章。4.4middleware类型Sequence[AgentMiddleware]默认值空序列追加在内置中间件栈末尾的自定义中间件。每个中间件可以注册工具、注入系统提示词片段、拦截 LLM 调用前后的消息以及包裹工具执行逻辑。详见第五章。4.5subagents类型list[SubAgent | CompiledSubAgent] | None默认值None子 agent 配置列表支持两种形式SubAgent字典形式声明式定义框架在 build time 自动编译为完整的CompiledStateGraph。字段类型必填继承主 agent说明namestr是—唯一标识符descriptionstr是—主 agent 据此决定何时委托system_promptstr是否子 agent 系统指令toolslist否否子 agent 可用工具modelstr|BaseChatModel否是默认模型覆盖middlewarelist否否额外中间件interrupt_ondict否是可覆盖子 agent 级 HITL 配置skillslist[str]否否独立技能路径与主 agent 完全隔离CompiledSubAgent预编译图形式命令式定义适合需要自定义节点或复杂状态机的场景。runnable字段必须是已调用.compile()的 LangGraph 图且 state schema 中必须包含messages键。两者的本质区别SubAgent由框架管图CompiledSubAgent由开发者管图。4.6skills与memoryskills是符合 agentskills.io 规范的SKILL.md文件路径列表。框架在 agent 启动时加载这些文件将技能名称和描述从 frontmatter 提取注入系统提示词完整技能文档存于文件系统供 agent 按需读取。后加载的同名技能覆盖先加载的后者优先原则。memory是AGENTS.md文件的路径列表用于在 agent 启动时注入跨会话的持久指令或历史上下文。如需实现真正的跨会话长期记忆应将store参数配合BaseStore使用。4.7response_format类型ResponseFormat | None默认值None将 agent 最终输出约束为结构化格式。传入 Pydantic 模型或 JSON Schemaagent 的最终响应将符合该 schema结果存储在 state 的structured_response字段中。4.8context_schema类型type[Any] | None默认值None定义图运行作用域run-scoped的静态上下文类型。这是一个类型变量描述每次invoke时通过context参数传入的只读配置对象。该对象在整个运行期间对所有工具和中间件可见但不会被发送给 LLM也不参与 agent state 管理。context_schema与 state 的本质区别对比项statecontextcontext_schema生命周期随对话持续演变整个 run 期间静态不变写入方agent、工具、中间件均可修改仅调用方在invoke时传入LLM 可见性是消息历史等否纯本地配置对象典型用途任务进度、文件内容、中间结果user_id、API 密钥、DB 连接等dataclassclassTenantContext:tenant_id:strdb_url:strpermissions:list[str]tooldefquery_data(sql:str,runtime:ToolRuntime[TenantContext])-list:查询租户数据。ctxruntime.contextifreadnotinctx.permissions:raisePermissionError(无读取权限)returnexecute_sql(ctx.db_url,sql)agentcreate_deep_agent(tools[query_data],context_schemaTenantContext)# 每次调用注入不同租户上下文agent 逻辑完全复用agent.invoke({messages:[...]},contextTenantContext(tenant_idA,db_url...,permissions[read]))4.9checkpointer、store与backend三者各司其职构成持久化层checkpointerLangGraph checkpointer在同一线程内跨多次invoke持久化 agent state消息历史、文件、todos 等实现多轮对话恢复。storeLangGraphBaseStore提供跨线程键值持久化存储。StoreBackend必须配合此参数使用也是跨会话长期记忆的基础设施。backend抽象虚拟文件系统的底层实现支持传入实例或工厂函数lambda rt: StateBackend(rt)Backend存储位置适用场景注意事项StateBackend默认LangGraph state单线程临时工作区重启后丢失主子 agent 共享FilesystemBackend本地磁盘开发 CLI、本地编码工具⚠️ 禁止用于 Web 服务StoreBackendLangGraph Store跨会话持久记忆需同时传入storeCompositeBackend按路径路由到不同 backend混合场景最灵活SandboxBackend远程沙箱Modal/Daytona/Deno隔离代码执行唯一支持execute工具的 backend4.10interrupt_on类型dict[str, bool | InterruptOnConfig] | None在指定工具调用前暂停 agent 执行等待人工审批。通过 LangGraph checkpoint 实现确定性的暂停-恢复语义而非事件轮询。使用此参数必须同时配置checkpointeragentcreate_deep_agent(tools[...],checkpointerMemorySaver(),interrupt_on{edit_file:True,# 每次编辑文件前暂停execute:True,# 每次执行命令前暂停})五、内部图组装过程create_deep_agent的执行分为五个有序阶段发生在 build time返回的CompiledStateGraph在 run time 直接复用不重新构建。阶段一模型解析。None→get_default_model()返回claude-sonnet-4-6字符串 →init_chat_model()BaseChatModel实例 → 直接使用。OpenAI 系列字符串默认启用 Responses API。阶段二Backend 初始化。若backend为工厂函数BackendFactory则在图节点内按需调用使其通过runtime访问当前线程的 LangGraph state。若为None默认使用lambda rt: StateBackend(rt)。阶段三中间件栈构建。按固定顺序实例化并组装内置中间件详见第六章。自定义中间件追加在栈末尾。阶段四子 agent 编译。SubAgentMiddleware对每个SubAgent字典配置调用create_agent将其编译为CompiledStateGraph并以名称为键缓存在内存中。这是唯一一次图构建后续所有调用复用同一份编译后的图结构。阶段五图编译。将所有工具、中间件、checkpointer、store、context_schema等组装为最终的StateGraph调用.compile()生成可执行的CompiledStateGraph。六、中间件系统与系统提示词组装机制6.1 内置中间件栈按执行顺序序号中间件激活条件核心职责#1TodoListMiddleware始终激活注册write_todos追加规划指令到 system prompt#2MemoryMiddlewarememory非空before_agent加载 AGENTS.md 并注入 prompt#3SkillsMiddlewareskills非空before_agent加载 SKILL.md 并注入 prompt#4FilesystemMiddleware始终激活注册文件系统工具追加工具文档到 prompt#5SubAgentMiddleware始终激活编译子 agent注册task工具追加子 agent 描述#6SummarizationMiddleware始终激活before_model检查上下文阈值默认 85%并触发压缩#7AnthropicPromptCachingMiddleware始终激活wrap_model_call为静态 prompt 打缓存断点仅 Anthropic 模型生效#8PatchToolCallsMiddleware始终激活before_model修复历史中的悬空工具调用记录#9用户自定义 middlewaremiddleware非空追加在栈末尾完全由开发者控制#10HumanInTheLoopMiddlewareinterrupt_on非空wrap_tool_call在匹配工具前通过 checkpoint 暂停执行注意顺序不可随意调换。例如SummarizationMiddleware修改消息历史必须在AnthropicPromptCachingMiddleware之前执行后者需要操作定型后的 prompt 状态。6.2 Middleware Hook 执行时机每个中间件可选择性实现五个 hook分属三种触发时机一次性触发before_agent(state, rt)在 agent 首次启动时执行一次MemoryMiddleware、SkillsMiddleware在此加载外部文件after_agent(state, rt)在 agent 结束时执行一次。每次 LLM 调用循环中触发before_model调用前可修改消息或短路跳转、wrap_model_call包裹调用本身可重试或替换模型、after_model调用后适合日志和后处理。工具执行时触发wrap_tool_call(req, handler)在每次工具被调用时触发。HumanInTheLoopMiddleware正是在此通过 LangGraph checkpoint 暂停图执行等待人工响应后再恢复。6.3 系统提示词的最终组装顺序最终系统提示词由以下部分按固定顺序拼接① 用户自定义 system_prompt前置 ② Base agent prompt内置固定 ③ TodoList 规划指令 ④ Memory promptAGENTS.md 内容memory 非空时 ⑤ Skills prompt技能列表 frontmatterskills 非空时 ⑥ 虚拟文件系统工具文档 ⑦ SubAgent 描述列表 task 工具说明 ⑧ 用户自定义 middleware 追加的片段 ⑨ HITL 审批指令interrupt_on 非空时 ⑩ 本地上下文CLI 模式专有七、核心设计机制深度解析7.1write_todos规划工具的本质从技术实现层面write_todos内部称TodoWrite是一个空操作no-op工具。它不向外部世界发送任何请求唯一的作用是将 LLM 生成的任务列表写入 LangGraph state 中的一个字典结构。这个工具的真正目的是强迫 LLM 将隐式的行动计划外显化将其记录在上下文窗口中。标准 LLM 的长期脑内规划能力有限ReAct 循环每次只关注单个推理-行动步骤鼓励战术性而非战略性思考。通过让模型调用工具这一行为本身迫使其在执行前先完整写出结构化计划。从认知工程角度理解LLM 在调用write_todos时被迫将隐式思维链外显为结构化待办列表这一写入行为重新激活了与任务目标相关的注意力权重相当于在有限上下文窗口中人工制造了工作记忆的锚点从而将推理模式从逐步反应式reactive转变为先规划后执行plan-then-act。官方系统提示词规定了明确的使用规范应在收到新指令后立即调用以捕获需求开始执行任务前标记in_progress完成后标记completed并补充后续任务。单步简单任务和闲聊场景不应使用。7.2 三级上下文压缩机制这是 Deep Agents 处理长时任务的核心工程能力三级机制按触发阈值递进第一级工具输入截断Tool Input Offloading。当文件写入和编辑操作在 agent 的对话历史中留下包含完整文件内容的工具调用记录时由于这些内容已持久化到文件系统它们在历史记录中变为冗余数据。当会话上下文超过模型可用窗口的 85% 时框架截断历史中较旧的工具调用将其替换为指向磁盘文件的指针从而缩小活跃上下文体积。第二级工具输出卸载Tool Result Offloading。当工具调用结果超过 20,000 token 时Deep Agent 会将响应卸载到配置的 backend并以文件路径引用加前 10 行预览来替代原始内容。agent 此后可按需重新读取或搜索该内容。第三级对话历史摘要Summarization。当前两级均无法控制上下文体积时触发对话历史摘要。框架生成一份内联摘要替代早期对话记录并将完整摘要写入文件系统供后续参考。触发阈值可通过SummarizationMiddleware的配置参数调整。此外框架还通过SummarizationToolMiddleware额外提供compact_conversation工具允许 agent 在自动触发阈值之前主动压缩历史。7.3 子 Agent 的生命周期图复用 vs. State 隔离子 agent 的生命周期分为两个完全分离的阶段Build time仅一次SubAgentMiddleware在create_deep_agent阶段对每个SubAgent配置调用create_agent将其编译为CompiledStateGraph并以名称为键缓存在内存中。Run time每次调用每次主 agent 调用task工具时执行流程如下校验subagent_type参数过滤父 agent 的 state排除messages、todos、structured_response、skills_metadata、memory_contents等字段构建一个只包含本次任务描述的全新消息列表对缓存的CompiledStateGraph调用ainvoke传入全新 state从结果的messages列表中提取最终消息作为ToolMessage返回给主 agent。因此准确的表述是编译好的图是复用的每次调用传入全新的初始 state。子 agent 不保留上一次调用的任何上下文这正是上下文隔离的实现机制。7.4AnthropicPromptCachingMiddleware每次 LLM 调用中system prompt 的内容几乎完全相同工具文档、技能列表等静态内容。该中间件通过wrap_model_callhook在调用前为这些静态内容块标记 Anthropic Prompt Cache 断点使相同内容在后续调用中直接命中缓存显著降低重复计算的 token 成本。该中间件仅对 Anthropic 模型生效其他提供商无影响。7.5PatchToolCallsMiddleware在 HITL 暂停-拒绝、工具执行被中断等场景下消息历史中会出现悬空工具调用dangling tool call——即AIMessage中存在tool_call但没有对应的ToolMessage结果导致后续 LLM 调用时消息历史不合法多数模型 API 要求工具调用与结果成对出现。PatchToolCallsMiddleware在before_modelhook 中检测并修复这类记录是 HITL 机制的必要配套基础设施。八、典型使用场景8.1 基础单 agent 工具调用fromdeepagentsimportcreate_deep_agentdefget_stock_price(symbol:str)-dict:获取股票实时价格。return{symbol:symbol,price:150.23}agentcreate_deep_agent(tools[get_stock_price],system_prompt你是专业金融助理回答准确简洁。,)resultagent.invoke({messages:[{role:user,content:AAPL 现在多少钱}]})8.2 持久化对话多轮会话fromlanggraph.checkpoint.memoryimportMemorySaver agentcreate_deep_agent(tools[...],checkpointerMemorySaver())config{configurable:{thread_id:session-001}}# 第一轮agent.invoke({messages:[{role:user,content:分析 Q3 财报}]},configconfig)# 第二轮自动恢复上一轮上下文agent.invoke({messages:[{role:user,content:与 Q2 相比如何}]},configconfig)8.3 多 agent 协作子 agent 委托code_reviewer{name:code-reviewer,description:专门进行代码审查检查安全漏洞、性能问题和代码规范,system_prompt:你是资深代码审查专家重点关注安全性、性能和可维护性。,tools:[read_file,glob],model:openai:gpt-5,}test_runner{name:test-runner,description:执行测试套件并生成测试报告,system_prompt:你是测试工程师负责运行测试并分析结果。,tools:[],}agentcreate_deep_agent(system_prompt你是技术负责人协调代码审查和测试流程。,subagents[code_reviewer,test_runner],backendFilesystemBackend(root_dir/project),)8.4 Human-in-the-Loop关键操作审批agentcreate_deep_agent(tools[deploy_service,rollback_deployment],checkpointerMemorySaver(),interrupt_on{deploy_service:True,rollback_deployment:True})config{configurable:{thread_id:deploy-001}}# agent 在调用 deploy_service 前自动暂停等待审批agent.invoke({messages:[...]},configconfig)# 审核后传 None 恢复执行复用同一 thread_idagent.invoke(None,configconfig)8.5 结构化输出frompydanticimportBaseModelclassAnalysisReport(BaseModel):summary:strkey_findings:list[str]risk_level:strrecommendations:list[str]agentcreate_deep_agent(tools[fetch_data],response_formatAnalysisReport)resultagent.invoke({messages:[...]})report:AnalysisReportresult[structured_response]8.6 Run-scoped 上下文注入dataclassclassTenantContext:tenant_id:strdb_url:stragentcreate_deep_agent(tools[query_tenant_data],context_schemaTenantContext)# 相同 agent 逻辑不同租户的隔离执行fortenantintenants:agent.invoke({messages:[...]},contextTenantContext(tenant_idtenant.id,db_urltenant.db_url))九、选型建议与注意事项9.1 何时使用 Deep Agents适合需要 3 步以上的复杂多步骤任务需要通过文件系统管理大量中间结果需要将工作委托给多个专业化子 agent需要跨会话持久化上下文和记忆。不适合单步简单工具调用用 LangChaincreate_agent需要精细控制图结构直接用 LangGraph任务简单到不需要规划write_todos的开销大于收益。9.2 Backend 安全注意事项FilesystemBackend授予 agent 对本地磁盘的直接读写权限严禁在 Web 服务或 HTTP API 中使用。结合网络工具时存在密钥泄露SSRF风险文件修改不可逆。仅在受控的本地开发或 CI/CD 环境中使用。生产环境的代码执行场景应使用SandboxBackend。9.3 中间件开发的竞态条件在任意 hook 中直接对self.x做 mutation 会导致竞态条件因为子 agent、并行工具调用和不同线程上的并发调用会同时运行。正确做法是将需要跨 hook 传递的状态写入通过context_schema声明的自定义字段通过 state dict 更新返回而非存储在self实例上。9.4 子 Agent 设计原则description字段必须清晰、具体、动词导向主 agent 据此决策何时委托。每个子 agent 只配备完成其职责所需的最少工具。子 agent 的最终报告应简洁避免将大量中间细节回传给主 agent否则失去上下文隔离的意义。框架层面已防止无限递归子 agent 不继承主 agent 的SubAgentMiddleware。十、总结create_deep_agent的架构本质是一个分层组合系统LangGraph 提供可靠的图执行运行时中间件管道在 build time 完成 prompt 组装与工具注册可插拔 backend 解耦了存储策略与 agent 逻辑三级上下文压缩机制使长时任务成为可能子 agent 机制通过图复用加 state 隔离实现高效的上下文隔离context_schema提供了干净的 run-scoped 配置注入通道。这一设计的深意在于它将软件工程领域已被验证的模式——分层、管道、依赖注入、策略模式、工厂模式——系统性地移植到了 LLM agent 工程之中。开发者无需理解底层 LangGraph 图结构即可通过声明式参数组合出生产级 agent而当需要精细控制时CompiledSubAgent、自定义 middleware 和 backend 协议又提供了充分的扩展空间。
Deep Agents之create_deep_agent 深度技术解析
发布时间：2026/7/7 4:35:04
一、概述与定位1.1 什么是 Deep Agentsdeepagents是一个构建于 LangChain 核心构建块之上的独立库以 LangGraph 作为运行时引擎是最简便的方式来构建由 LLM 驱动的 agent 和应用——内置任务规划、文件系统上下文管理、子 agent 派发和长期记忆等能力。create_deep_agent是这个库的核心入口函数其设计理念可以用一句话概括在标准工具调用循环之上以声明式参数组合出生产级 agent。这与框架不同——框架要求开发者理解底层图结构Harness 则把工程复杂度封装在内部对外暴露语义清晰的配置接口。这一设计的源头来自对 Claude Code 架构的研究与抽象。研究发现使 agent 真正具备深度执行能力的要素是四个组合的协同详尽的系统提示词、子 agent 机制、对文件系统的访问权限以及任务规划工具。create_deep_agent正是这四项能力的统一入口。1.2 在技术栈中的位置层次组件职责运行时LangGraph图执行、checkpointer、store、streaming、HITL 暂停恢复构建块LangChain模型抽象BaseChatModel、工具协议BaseTool、init_chat_modelHarnessdeepagents中间件管道、文件系统、子 agent、规划工具、上下文压缩二、完整方法签名defcreate_deep_agent(model:str|BaseChatModel|NoneNone,tools:Sequence[BaseTool|Callable|dict]|NoneNone,*,system_prompt:str|SystemMessage|NoneNone,middleware:Sequence[AgentMiddleware](),subagents:list[SubAgent|CompiledSubAgent]|NoneNone,skills:list[str]|NoneNone,memory:list[str]|NoneNone,response_format:ResponseFormat|NoneNone,context_schema:type[Any]|NoneNone,checkpointer:Checkpointer|NoneNone,store:BaseStore|NoneNone,backend:BackendProtocol|BackendFactory|NoneNone,interrupt_on:dict[str,bool|InterruptOnConfig]|NoneNone,debug:boolFalse,name:str|NoneNone,cache:BaseCache|NoneNone,)-CompiledStateGraph强制要求所使用的 LLM 必须支持工具调用Tool Calling。三、返回值CompiledStateGraph函数返回一个 LangGraphCompiledStateGraph实例这是一个完整配置、可立即执行的 agent 图。该对象支持以下核心接口方法说明.invoke(input, config)同步调用阻塞直到完成返回最终 state.ainvoke(input, config)异步调用适合 async/await 环境.stream(input, config)流式调用逐步产生 state 更新事件.astream(input, config)异步流式调用.get_graph(xrayTrue)获取图结构对象可调用.draw_mermaid_png()可视化标准调用形式agentcreate_deep_agent(tools[my_tool])resultagent.invoke({messages:[{role:user,content:完成这个任务}]},config{configurable:{thread_id:thread-001}})四、参数详解所有参数按功能语义分为四个层次模型层 → model 能力扩展层 → tools · middleware · subagents · skills · memory 状态持久化层 → checkpointer · store · backend 运行时控制层 → system_prompt · interrupt_on · response_format context_schema · debug · name · cache4.1model类型str | BaseChatModel | None默认值claude-sonnet-4-6支持三种传入形式字符串如openai:gpt-5内部调用init_chat_model、已初始化的BaseChatModel实例、或None使用默认模型。提供商示例字符串备注Anthropicclaude-sonnet-4-6默认原生支持 Prompt Caching 中间件OpenAIopenai:gpt-5默认启用 Responses API精细控制请传初始化实例Azure OpenAIazure_openai:gpt-4.1需设置相应环境变量Google Geminigoogle_genai:gemini-2.5-flash需安装langchain[google-genai]AWS Bedrockanthropic.claude-3-5-sonnet...需配置 AWS credentials4.2tools类型Sequence[BaseTool | Callable | dict] | None默认值None用户自定义工具与以下内置工具并联组合共同暴露给 LLM工具提供方功能write_todosTodoListMiddleware任务规划强制外显计划ls / read_file / write_file / edit_file / glob / grepFilesystemMiddleware虚拟文件系统操作executeFilesystemMiddleware沙箱执行 shell 命令仅限沙箱 backendtaskSubAgentMiddleware委托子 agent工具推荐使用标准 Python 函数配合完整类型注解和 docstring框架自动提取 schematooldefquery_database(sql:str,limit:int10)-list[dict]:在数据库中执行查询。 Args: sql: SQL 查询语句 limit: 返回最大行数 returndb.execute(sql,limitlimit)4.3system_prompt类型str | SystemMessage | None默认值None自定义系统指令。传入字符串时前置拼接到内置 base agent prompt 之前传入SystemMessage则作为额外内容块追加。该参数不替换内置 prompt仅用于补充业务特定的角色定义或行为约束。最终系统提示词由多个部分按固定顺序组装详见第六章。4.4middleware类型Sequence[AgentMiddleware]默认值空序列追加在内置中间件栈末尾的自定义中间件。每个中间件可以注册工具、注入系统提示词片段、拦截 LLM 调用前后的消息以及包裹工具执行逻辑。详见第五章。4.5subagents类型list[SubAgent | CompiledSubAgent] | None默认值None子 agent 配置列表支持两种形式SubAgent字典形式声明式定义框架在 build time 自动编译为完整的CompiledStateGraph。字段类型必填继承主 agent说明namestr是—唯一标识符descriptionstr是—主 agent 据此决定何时委托system_promptstr是否子 agent 系统指令toolslist否否子 agent 可用工具modelstr|BaseChatModel否是默认模型覆盖middlewarelist否否额外中间件interrupt_ondict否是可覆盖子 agent 级 HITL 配置skillslist[str]否否独立技能路径与主 agent 完全隔离CompiledSubAgent预编译图形式命令式定义适合需要自定义节点或复杂状态机的场景。runnable字段必须是已调用.compile()的 LangGraph 图且 state schema 中必须包含messages键。两者的本质区别SubAgent由框架管图CompiledSubAgent由开发者管图。4.6skills与memoryskills是符合 agentskills.io 规范的SKILL.md文件路径列表。框架在 agent 启动时加载这些文件将技能名称和描述从 frontmatter 提取注入系统提示词完整技能文档存于文件系统供 agent 按需读取。后加载的同名技能覆盖先加载的后者优先原则。memory是AGENTS.md文件的路径列表用于在 agent 启动时注入跨会话的持久指令或历史上下文。如需实现真正的跨会话长期记忆应将store参数配合BaseStore使用。4.7response_format类型ResponseFormat | None默认值None将 agent 最终输出约束为结构化格式。传入 Pydantic 模型或 JSON Schemaagent 的最终响应将符合该 schema结果存储在 state 的structured_response字段中。4.8context_schema类型type[Any] | None默认值None定义图运行作用域run-scoped的静态上下文类型。这是一个类型变量描述每次invoke时通过context参数传入的只读配置对象。该对象在整个运行期间对所有工具和中间件可见但不会被发送给 LLM也不参与 agent state 管理。context_schema与 state 的本质区别对比项statecontextcontext_schema生命周期随对话持续演变整个 run 期间静态不变写入方agent、工具、中间件均可修改仅调用方在invoke时传入LLM 可见性是消息历史等否纯本地配置对象典型用途任务进度、文件内容、中间结果user_id、API 密钥、DB 连接等dataclassclassTenantContext:tenant_id:strdb_url:strpermissions:list[str]tooldefquery_data(sql:str,runtime:ToolRuntime[TenantContext])-list:查询租户数据。ctxruntime.contextifreadnotinctx.permissions:raisePermissionError(无读取权限)returnexecute_sql(ctx.db_url,sql)agentcreate_deep_agent(tools[query_data],context_schemaTenantContext)# 每次调用注入不同租户上下文agent 逻辑完全复用agent.invoke({messages:[...]},contextTenantContext(tenant_idA,db_url...,permissions[read]))4.9checkpointer、store与backend三者各司其职构成持久化层checkpointerLangGraph checkpointer在同一线程内跨多次invoke持久化 agent state消息历史、文件、todos 等实现多轮对话恢复。storeLangGraphBaseStore提供跨线程键值持久化存储。StoreBackend必须配合此参数使用也是跨会话长期记忆的基础设施。backend抽象虚拟文件系统的底层实现支持传入实例或工厂函数lambda rt: StateBackend(rt)Backend存储位置适用场景注意事项StateBackend默认LangGraph state单线程临时工作区重启后丢失主子 agent 共享FilesystemBackend本地磁盘开发 CLI、本地编码工具⚠️ 禁止用于 Web 服务StoreBackendLangGraph Store跨会话持久记忆需同时传入storeCompositeBackend按路径路由到不同 backend混合场景最灵活SandboxBackend远程沙箱Modal/Daytona/Deno隔离代码执行唯一支持execute工具的 backend4.10interrupt_on类型dict[str, bool | InterruptOnConfig] | None在指定工具调用前暂停 agent 执行等待人工审批。通过 LangGraph checkpoint 实现确定性的暂停-恢复语义而非事件轮询。使用此参数必须同时配置checkpointeragentcreate_deep_agent(tools[...],checkpointerMemorySaver(),interrupt_on{edit_file:True,# 每次编辑文件前暂停execute:True,# 每次执行命令前暂停})五、内部图组装过程create_deep_agent的执行分为五个有序阶段发生在 build time返回的CompiledStateGraph在 run time 直接复用不重新构建。阶段一模型解析。None→get_default_model()返回claude-sonnet-4-6字符串 →init_chat_model()BaseChatModel实例 → 直接使用。OpenAI 系列字符串默认启用 Responses API。阶段二Backend 初始化。若backend为工厂函数BackendFactory则在图节点内按需调用使其通过runtime访问当前线程的 LangGraph state。若为None默认使用lambda rt: StateBackend(rt)。阶段三中间件栈构建。按固定顺序实例化并组装内置中间件详见第六章。自定义中间件追加在栈末尾。阶段四子 agent 编译。SubAgentMiddleware对每个SubAgent字典配置调用create_agent将其编译为CompiledStateGraph并以名称为键缓存在内存中。这是唯一一次图构建后续所有调用复用同一份编译后的图结构。阶段五图编译。将所有工具、中间件、checkpointer、store、context_schema等组装为最终的StateGraph调用.compile()生成可执行的CompiledStateGraph。六、中间件系统与系统提示词组装机制6.1 内置中间件栈按执行顺序序号中间件激活条件核心职责#1TodoListMiddleware始终激活注册write_todos追加规划指令到 system prompt#2MemoryMiddlewarememory非空before_agent加载 AGENTS.md 并注入 prompt#3SkillsMiddlewareskills非空before_agent加载 SKILL.md 并注入 prompt#4FilesystemMiddleware始终激活注册文件系统工具追加工具文档到 prompt#5SubAgentMiddleware始终激活编译子 agent注册task工具追加子 agent 描述#6SummarizationMiddleware始终激活before_model检查上下文阈值默认 85%并触发压缩#7AnthropicPromptCachingMiddleware始终激活wrap_model_call为静态 prompt 打缓存断点仅 Anthropic 模型生效#8PatchToolCallsMiddleware始终激活before_model修复历史中的悬空工具调用记录#9用户自定义 middlewaremiddleware非空追加在栈末尾完全由开发者控制#10HumanInTheLoopMiddlewareinterrupt_on非空wrap_tool_call在匹配工具前通过 checkpoint 暂停执行注意顺序不可随意调换。例如SummarizationMiddleware修改消息历史必须在AnthropicPromptCachingMiddleware之前执行后者需要操作定型后的 prompt 状态。6.2 Middleware Hook 执行时机每个中间件可选择性实现五个 hook分属三种触发时机一次性触发before_agent(state, rt)在 agent 首次启动时执行一次MemoryMiddleware、SkillsMiddleware在此加载外部文件after_agent(state, rt)在 agent 结束时执行一次。每次 LLM 调用循环中触发before_model调用前可修改消息或短路跳转、wrap_model_call包裹调用本身可重试或替换模型、after_model调用后适合日志和后处理。工具执行时触发wrap_tool_call(req, handler)在每次工具被调用时触发。HumanInTheLoopMiddleware正是在此通过 LangGraph checkpoint 暂停图执行等待人工响应后再恢复。6.3 系统提示词的最终组装顺序最终系统提示词由以下部分按固定顺序拼接① 用户自定义 system_prompt前置 ② Base agent prompt内置固定 ③ TodoList 规划指令 ④ Memory promptAGENTS.md 内容memory 非空时 ⑤ Skills prompt技能列表 frontmatterskills 非空时 ⑥ 虚拟文件系统工具文档 ⑦ SubAgent 描述列表 task 工具说明 ⑧ 用户自定义 middleware 追加的片段 ⑨ HITL 审批指令interrupt_on 非空时 ⑩ 本地上下文CLI 模式专有七、核心设计机制深度解析7.1write_todos规划工具的本质从技术实现层面write_todos内部称TodoWrite是一个空操作no-op工具。它不向外部世界发送任何请求唯一的作用是将 LLM 生成的任务列表写入 LangGraph state 中的一个字典结构。这个工具的真正目的是强迫 LLM 将隐式的行动计划外显化将其记录在上下文窗口中。标准 LLM 的长期脑内规划能力有限ReAct 循环每次只关注单个推理-行动步骤鼓励战术性而非战略性思考。通过让模型调用工具这一行为本身迫使其在执行前先完整写出结构化计划。从认知工程角度理解LLM 在调用write_todos时被迫将隐式思维链外显为结构化待办列表这一写入行为重新激活了与任务目标相关的注意力权重相当于在有限上下文窗口中人工制造了工作记忆的锚点从而将推理模式从逐步反应式reactive转变为先规划后执行plan-then-act。官方系统提示词规定了明确的使用规范应在收到新指令后立即调用以捕获需求开始执行任务前标记in_progress完成后标记completed并补充后续任务。单步简单任务和闲聊场景不应使用。7.2 三级上下文压缩机制这是 Deep Agents 处理长时任务的核心工程能力三级机制按触发阈值递进第一级工具输入截断Tool Input Offloading。当文件写入和编辑操作在 agent 的对话历史中留下包含完整文件内容的工具调用记录时由于这些内容已持久化到文件系统它们在历史记录中变为冗余数据。当会话上下文超过模型可用窗口的 85% 时框架截断历史中较旧的工具调用将其替换为指向磁盘文件的指针从而缩小活跃上下文体积。第二级工具输出卸载Tool Result Offloading。当工具调用结果超过 20,000 token 时Deep Agent 会将响应卸载到配置的 backend并以文件路径引用加前 10 行预览来替代原始内容。agent 此后可按需重新读取或搜索该内容。第三级对话历史摘要Summarization。当前两级均无法控制上下文体积时触发对话历史摘要。框架生成一份内联摘要替代早期对话记录并将完整摘要写入文件系统供后续参考。触发阈值可通过SummarizationMiddleware的配置参数调整。此外框架还通过SummarizationToolMiddleware额外提供compact_conversation工具允许 agent 在自动触发阈值之前主动压缩历史。7.3 子 Agent 的生命周期图复用 vs. State 隔离子 agent 的生命周期分为两个完全分离的阶段Build time仅一次SubAgentMiddleware在create_deep_agent阶段对每个SubAgent配置调用create_agent将其编译为CompiledStateGraph并以名称为键缓存在内存中。Run time每次调用每次主 agent 调用task工具时执行流程如下校验subagent_type参数过滤父 agent 的 state排除messages、todos、structured_response、skills_metadata、memory_contents等字段构建一个只包含本次任务描述的全新消息列表对缓存的CompiledStateGraph调用ainvoke传入全新 state从结果的messages列表中提取最终消息作为ToolMessage返回给主 agent。因此准确的表述是编译好的图是复用的每次调用传入全新的初始 state。子 agent 不保留上一次调用的任何上下文这正是上下文隔离的实现机制。7.4AnthropicPromptCachingMiddleware每次 LLM 调用中system prompt 的内容几乎完全相同工具文档、技能列表等静态内容。该中间件通过wrap_model_callhook在调用前为这些静态内容块标记 Anthropic Prompt Cache 断点使相同内容在后续调用中直接命中缓存显著降低重复计算的 token 成本。该中间件仅对 Anthropic 模型生效其他提供商无影响。7.5PatchToolCallsMiddleware在 HITL 暂停-拒绝、工具执行被中断等场景下消息历史中会出现悬空工具调用dangling tool call——即AIMessage中存在tool_call但没有对应的ToolMessage结果导致后续 LLM 调用时消息历史不合法多数模型 API 要求工具调用与结果成对出现。PatchToolCallsMiddleware在before_modelhook 中检测并修复这类记录是 HITL 机制的必要配套基础设施。八、典型使用场景8.1 基础单 agent 工具调用fromdeepagentsimportcreate_deep_agentdefget_stock_price(symbol:str)-dict:获取股票实时价格。return{symbol:symbol,price:150.23}agentcreate_deep_agent(tools[get_stock_price],system_prompt你是专业金融助理回答准确简洁。,)resultagent.invoke({messages:[{role:user,content:AAPL 现在多少钱}]})8.2 持久化对话多轮会话fromlanggraph.checkpoint.memoryimportMemorySaver agentcreate_deep_agent(tools[...],checkpointerMemorySaver())config{configurable:{thread_id:session-001}}# 第一轮agent.invoke({messages:[{role:user,content:分析 Q3 财报}]},configconfig)# 第二轮自动恢复上一轮上下文agent.invoke({messages:[{role:user,content:与 Q2 相比如何}]},configconfig)8.3 多 agent 协作子 agent 委托code_reviewer{name:code-reviewer,description:专门进行代码审查检查安全漏洞、性能问题和代码规范,system_prompt:你是资深代码审查专家重点关注安全性、性能和可维护性。,tools:[read_file,glob],model:openai:gpt-5,}test_runner{name:test-runner,description:执行测试套件并生成测试报告,system_prompt:你是测试工程师负责运行测试并分析结果。,tools:[],}agentcreate_deep_agent(system_prompt你是技术负责人协调代码审查和测试流程。,subagents[code_reviewer,test_runner],backendFilesystemBackend(root_dir/project),)8.4 Human-in-the-Loop关键操作审批agentcreate_deep_agent(tools[deploy_service,rollback_deployment],checkpointerMemorySaver(),interrupt_on{deploy_service:True,rollback_deployment:True})config{configurable:{thread_id:deploy-001}}# agent 在调用 deploy_service 前自动暂停等待审批agent.invoke({messages:[...]},configconfig)# 审核后传 None 恢复执行复用同一 thread_idagent.invoke(None,configconfig)8.5 结构化输出frompydanticimportBaseModelclassAnalysisReport(BaseModel):summary:strkey_findings:list[str]risk_level:strrecommendations:list[str]agentcreate_deep_agent(tools[fetch_data],response_formatAnalysisReport)resultagent.invoke({messages:[...]})report:AnalysisReportresult[structured_response]8.6 Run-scoped 上下文注入dataclassclassTenantContext:tenant_id:strdb_url:stragentcreate_deep_agent(tools[query_tenant_data],context_schemaTenantContext)# 相同 agent 逻辑不同租户的隔离执行fortenantintenants:agent.invoke({messages:[...]},contextTenantContext(tenant_idtenant.id,db_urltenant.db_url))九、选型建议与注意事项9.1 何时使用 Deep Agents适合需要 3 步以上的复杂多步骤任务需要通过文件系统管理大量中间结果需要将工作委托给多个专业化子 agent需要跨会话持久化上下文和记忆。不适合单步简单工具调用用 LangChaincreate_agent需要精细控制图结构直接用 LangGraph任务简单到不需要规划write_todos的开销大于收益。9.2 Backend 安全注意事项FilesystemBackend授予 agent 对本地磁盘的直接读写权限严禁在 Web 服务或 HTTP API 中使用。结合网络工具时存在密钥泄露SSRF风险文件修改不可逆。仅在受控的本地开发或 CI/CD 环境中使用。生产环境的代码执行场景应使用SandboxBackend。9.3 中间件开发的竞态条件在任意 hook 中直接对self.x做 mutation 会导致竞态条件因为子 agent、并行工具调用和不同线程上的并发调用会同时运行。正确做法是将需要跨 hook 传递的状态写入通过context_schema声明的自定义字段通过 state dict 更新返回而非存储在self实例上。9.4 子 Agent 设计原则description字段必须清晰、具体、动词导向主 agent 据此决策何时委托。每个子 agent 只配备完成其职责所需的最少工具。子 agent 的最终报告应简洁避免将大量中间细节回传给主 agent否则失去上下文隔离的意义。框架层面已防止无限递归子 agent 不继承主 agent 的SubAgentMiddleware。十、总结create_deep_agent的架构本质是一个分层组合系统LangGraph 提供可靠的图执行运行时中间件管道在 build time 完成 prompt 组装与工具注册可插拔 backend 解耦了存储策略与 agent 逻辑三级上下文压缩机制使长时任务成为可能子 agent 机制通过图复用加 state 隔离实现高效的上下文隔离context_schema提供了干净的 run-scoped 配置注入通道。这一设计的深意在于它将软件工程领域已被验证的模式——分层、管道、依赖注入、策略模式、工厂模式——系统性地移植到了 LLM agent 工程之中。开发者无需理解底层 LangGraph 图结构即可通过声明式参数组合出生产级 agent而当需要精细控制时CompiledSubAgent、自定义 middleware 和 backend 协议又提供了充分的扩展空间。
 获取与实战)
