文章目录第 1 章DeepAgents 是什么1.1 本章目标1.2 核心概念1.2.0 前置概念速览1.2.1 LangChain 生态图谱1.2.2 DeepAgents 核心理念Agent Harness代理马具1.3 安装与环境搭建1.4 create_deep_agent() 函数签名1.5 实战Hello World -- 第一个 DeepAgent场景完整代码运行结果逐段解析1.6 DeepAgents 自动提供了什么自动就绪无需任何配置开箱即用可选启用需要显式配置才会生效1.7 API 列表速查1.8 常见错误与避坑错误 1混淆 create_deep_agent 和 create_agent错误 2忘记设置 API Key错误 3工具函数没有 docstring错误 4在 model 参数中写错 provider 前缀错误 5混淆 invoke 和 ainvoke 的调用场景1.9 最佳实践1.10 本章小结第 1 章DeepAgents 是什么1.1 本章目标完成本章学习后你将具备以下能力理解 LangChain 生态中 LangChain、LangGraph、DeepAgents 三者的层级关系与分工掌握 DeepAgents 作为 “agent harness”代理马具的核心理念与四大设计特点独立完成 DeepAgents 的安装与环境搭建并成功运行第一个 Hello World Agent理解create_deep_agent()函数签名中每个参数的含义与默认值了解 DeepAgents 自动提供的六大内置能力planning规划、filesystem文件系统、subagents子代理、summarization摘要、human-in-the-loop人机协同1.2 核心概念1.2.0 前置概念速览在深入 DeepAgents 之前你需要先了解几个核心术语。以下用最通俗的类比解释术语一句话解释类比LLM大语言模型能够理解和生成文本的 AI 模型如 GPT-4、Claude一个读过全世界书籍的超级大脑Agent智能代理能够自主使用工具、做决策、执行多步任务的 AI 程序一个能独立思考并使用工具的机器人助手Tool工具Agent 可以调用的函数如搜索网页、读写文件、执行代码Agent 手中的扳手和螺丝刀LangGraphLangChain 旗下的有状态工作流框架用图Graph来编排 Agent 的执行流程一张施工蓝图定义了 Agent 执行的每一步State状态Agent 在运行过程中保存的所有数据如对话历史、文件内容Agent 的笔记本记录所有做过的事Checkpointer检查点将 Agent 状态持久化到磁盘以便中断后恢复游戏的存档点关机后可以接着玩Middleware中间件在 Agent 执行流程中插入的拦截器可以修改请求/响应安检流程中的传送带每个包裹都要经过检查MCPModel Context Protocol连接 AI 模型和外部工具的标准协议各种电器通用的USB 接口学习建议如果你对以上某个术语感到陌生不要担心–随着教程深入你会逐步理解每个概念。现在只需要知道它们大概是什么即可。第 2 章将深入剖析所有架构细节。1.2.1 LangChain 生态图谱要理解 DeepAgents首先需要看清 LangChain 生态的三层架构。这三层如同建造一栋大楼LangChain是建筑材料building blocks-- 提供模型调用、工具定义、消息处理等基础组件LangGraph是施工框架runtime-- 提供状态图、持久化、流式处理、人机协同等运行时能力DeepAgents是精装样板间agent harness-- 在 LangChain LangGraph 之上预置了规划、文件系统、子代理、摘要等开箱即用的能力LangChain (Building Blocks / 基础组件)Chat Models 对话模型Tools 工具Messages 消息Prompts 提示词MCP 协议LangGraph (Runtime / 运行时)StateGraph 状态图Checkpointer 持久化Streaming 流式处理Interrupt 中断机制DeepAgents (Agent Harness / 代理马具)Planning 规划Filesystem 文件系统Subagents 子代理Summarization 摘要Human-in-the-Loop 人机协同Memory 记忆通俗类比如果把构建 AI Agent 比作造车LangChain 是发动机、轮胎、方向盘等零部件LangGraph 是底盘和电路系统让零部件能协同工作DeepAgents 是一辆整车你坐进去就能开不必从零组装1.2.2 DeepAgents 核心理念Agent Harness代理马具DeepAgents 官方将自己定位为“agent harness”而非一个 agent framework。这个比喻非常精准马具harness不是马本身而是让骑手能够驾驭马的一套装备DeepAgents不是 agent 本身而是让开发者能够驾驭 LLM 的一套鞍具它具备四个关键设计特点特点含义价值Opinionated有主见的内置最佳实践的默认配置不必从零做决策降低入门门槛避免空白画布恐惧Extensible可扩展的通过 Middleware 机制可插入自定义逻辑满足复杂场景需求不限制创造力Model-agnostic模型无关的支持 OpenAI、Anthropic、Google、AWS Bedrock 等不被单一供应商锁定Production-ready生产就绪的内置持久化、流式输出、错误重试、人机协同从原型到上线无需重写1.3 安装与环境搭建# 安装 deepagents 核心包pipinstalldeepagents# 安装常用模型提供商按需选择pipinstall-Ulangchain[openai]# OpenAIpipinstall-Ulangchain[anthropic]# Anthropicpipinstall-Ulangchain[google-genai]# Google Gemini# 如需 MCP 协议支持pipinstalllangchain-mcp-adapters# 设置 API KeyexportOPENAI_API_KEYsk-...# 或exportANTHROPIC_API_KEYsk-...1.4 create_deep_agent() 函数签名fromdeepagentsimportcreate_deep_agent agentcreate_deep_agent(model:str|BaseChatModel|NoneNone,tools:Sequence[BaseTool|Callable|dict[str,Any]]|NoneNone,*,system_prompt:str|SystemMessage|NoneNone,middleware:Sequence[AgentMiddleware](),subagents:Sequence[SubAgent|CompiledSubAgent|AsyncSubAgent]|NoneNone,skills:list[str]|NoneNone,memory:list[str]|NoneNone,permissions:list[FilesystemPermission]|NoneNone,backend:BackendProtocol|BackendFactory|NoneNone,interrupt_on:dict[str,bool|InterruptOnConfig]|NoneNone,response_format:ResponseFormat[ResponseT]|type[ResponseT]|dict[str,Any]|NoneNone,state_schema:type[DeepAgentState]|NoneNone,context_schema:type[ContextT]|NoneNone,checkpointer:Checkpointer|NoneNone,store:BaseStore|NoneNone,debug:boolFalse,name:str|NoneNone,cache:BaseCache|NoneNone,)-CompiledStateGraph参数速查表参数类型默认值说明modelstr | BaseChatModel | NoneNone模型标识符如openai:gpt-5.5或模型实例toolsSequence[BaseTool | Callable | dict] | NoneNone自定义工具列表支持函数、tool 装饰器、工具字典system_promptstr | SystemMessage | NoneNone系统提示词定义 Agent 的角色和行为middlewareSequence[AgentMiddleware]()自定义中间件列表合并到默认栈中subagentsSequence[SubAgent | CompiledSubAgent | AsyncSubAgent] | NoneNone自定义子代理定义列表skillslist[str] | NoneNoneSkill 目录路径按需加载领域知识memorylist[str] | NoneNoneAGENTS.md 文件路径提供持久记忆permissionslist[FilesystemPermission] | NoneNone文件系统访问权限规则backendBackendProtocol | BackendFactory | NoneNone默认 StateBackend文件系统后端interrupt_ondict[str, bool | InterruptOnConfig] | NoneNone工具调用前暂停等待人工审批response_formatResponseFormat | type | dict | NoneNone结构化输出格式定义state_schematype[DeepAgentState] | NoneNone自定义图状态 Schemacontext_schematype[ContextT] | NoneNone每次运行的上下文 SchemacheckpointerCheckpointer | NoneNone持久化检查点用于中断恢复storeBaseStore | NoneNoneLangGraph Store用于跨线程持久化debugboolFalse是否开启调试模式namestr | NoneNoneAgent 名称用于流式追踪cacheBaseCache | NoneNone模型调用缓存1.5 实战Hello World – 第一个 DeepAgent场景创建一个带搜索工具的 DeepAgent能够查询天气信息。完整代码# hello_deep_agent.pyfromdeepagentsimportcreate_deep_agent# 1. 定义一个工具函数 -- 模拟天气查询defget_weather(city:str)-str:Get the current weather for a given city. Args: city: The name of the city to look up. Returns: A string describing the weather in that city. # 模拟天气数据weather_data{beijing:Sunny, 28C,shanghai:Cloudy, 25C,tokyo:Rainy, 18C,san francisco:Foggy, 15C,}city_lowercity.lower()ifcity_lowerinweather_data:returnfThe weather in{city.title()}is{weather_data[city_lower]}.returnfIts always sunny in{city}!# 2. 创建 DeepAgentagentcreate_deep_agent(modelopenai:gpt-4o-mini,# 使用 provider:model 格式tools[get_weather],system_promptYou are a helpful weather assistant. Use the get_weather tool to answer weather questions.,)# 3. 运行 Agentresultagent.invoke({messages:[{role:user,content:What is the weather in Beijing and Tokyo?}]})# 4. 打印结果formsginresult[messages]:ifhasattr(msg,content)andmsg.content:print(f[{msg.type.upper()}]:{msg.content[:200]})运行结果[SYSTEM]: You are a helpful weather assistant. Use the get_weather tool to answer weather questions. [HUMAN]: What is the weather in Beijing and Tokyo? [AI]: Let me check the weather for both cities. [TOOL]: The weather in Beijing is Sunny, 28C. [TOOL]: The weather in Tokyo is Rainy, 18C. [AI]: Heres the weather for both cities: - Beijing: Sunny, 28C - Tokyo: Rainy, 18C逐段解析第 1 步 – 定义工具函数get_weather是一个普通的 Python 函数但它的 docstring 和类型注解会被 DeepAgents 自动解析为工具的 Schema名称、描述、参数。DeepAgents 会将参数类型city: str和文档字符串Get the current weather...转换为 LLM 可理解的 tool definition。第 2 步 – 创建 Agentcreate_deep_agent()是 DeepAgents 的核心工厂函数。它接收模型标识符、工具列表和系统提示词内部自动完成构建默认中间件栈TodoListMiddlewareFilesystemMiddlewareSubAgentMiddleware基于 LangGraph 创建状态图StateGraph注册所有内置工具ls、read_file、write_file、edit_file、glob、grep、write_todos、task第 3 步 – 运行 Agentagent.invoke()将消息列表传递给 Agent。Agent 的 LangGraph 运行时执行 plan-act-observe-reflect 循环直到模型决定不再需要调用工具为止。第 4 步 – 输出结果result[messages]包含完整的对话历史包括 SystemMessage、HumanMessage、AIMessage、ToolMessage。你可以遍历消息列表来获取最终回复。1.6 DeepAgents 自动提供了什么当你调用create_deep_agent()时以下能力自动就绪或可选启用分为两类自动就绪无需任何配置开箱即用能力对应的中间件说明Planning规划TodoListMiddleware提供write_todos工具Agent 可创建和管理结构化任务列表Filesystem文件系统FilesystemMiddleware提供ls、read_file、write_file、edit_file、glob、grep、delete工具Agent 可像操作文件系统一样读写数据Subagents子代理SubAgentMiddleware提供task工具Agent 可将复杂任务委派给隔离的子代理Summarization摘要内置上下文管理当对话历史过长时自动压缩旧消息防止超出 Token 限制可选启用需要显式配置才会生效能力启用方式说明Human-in-the-loop人机协同通过interrupt_on参数启用在关键操作前暂停等待人工审批Memory记忆通过memory参数启用加载AGENTS.md文件作为持久化记忆跨会话保留偏好1.7 API 列表速查API来源说明create_deep_agent()deepagents创建 DeepAgent 的工厂函数agent.invoke(input)LangGraph同步调用 Agent输入消息列表agent.ainvoke(input)LangGraph异步调用 Agentagent.stream_events(input)LangGraph流式获取 Agent 执行事件FilesystemPermissiondeepagents文件系统权限规则StateBackenddeepagents.backends默认后端内存 状态持久化1.8 常见错误与避坑错误 1混淆create_deep_agent和create_agent# 错误LangChain 的 create_agent 没有内置文件系统和子代理fromlangchain.agentsimportcreate_agent agentcreate_agent(modelopenai:gpt-4o-mini,tools[...])# agent 没有 ls, read_file, write_todos, task 等工具# 正确使用 deepagents 的 create_deep_agentfromdeepagentsimportcreate_deep_agent agentcreate_deep_agent(modelopenai:gpt-4o-mini,tools[...])# agent 自动拥有完整的内置工具集错误 2忘记设置 API Key# 错误未设置环境变量agentcreate_deep_agent(modelopenai:gpt-4o-mini)# 抛出 AuthenticationError# 正确先设置 API Keyimportos os.environ[OPENAI_API_KEY]sk-...agentcreate_deep_agent(modelopenai:gpt-4o-mini)错误 3工具函数没有 docstring# 错误没有 docstringdefget_weather(city:str)-str:returnfWeather in{city}# 正确包含完整 docstring会被转化为 tool descriptiondefget_weather(city:str)-str:Get the current weather for a given city. Args: city: The name of the city to look up. returnfWeather in{city}错误 4在model参数中写错 provider 前缀# 错误不存在的 provider 或格式错误agentcreate_deep_agent(modelgpt-4o-mini)# 缺少 provider 前缀# 正确使用 provider:model 格式agentcreate_deep_agent(modelopenai:gpt-4o-mini)agentcreate_deep_agent(modelanthropic:claude-sonnet-4-6)错误 5混淆invoke和ainvoke的调用场景# 错误在 async 函数中调用同步 invokeasyncdefmain():resultagent.invoke(...)# 会阻塞事件循环# 正确在 async 函数中使用 ainvokeasyncdefmain():resultawaitagent.ainvoke(...)1.9 最佳实践始终为工具函数编写完整的 docstringDeepAgents 依赖 docstring 为 LLM 生成工具描述缺失 docstring 会导致 LLM 不知道何时调用该工具。使用provider:model格式指定模型这种格式让你可以在不同提供商之间快速切换无需修改代码结构。善用system_prompt明确的系统提示词显著提升 Agent 行为质量尤其是明确告诉 Agent 何时使用task工具委派子代理。从简单开始逐步增加复杂度先用create_deep_agent(model..., tools[...])跑通基本流程再逐步添加subagents、middleware、permissions等高级参数。使用 LangSmith 追踪 Agent 执行设置LANGCHAIN_TRACING_V2true和LANGCHAIN_API_KEY在 LangSmith 中可视化查看 Agent 的每一步推理和工具调用。1.10 本章小结DeepAgents 是 LangChain 生态中的agent harness位于 LangChain基础组件和 LangGraph运行时之上提供开箱即用的 Agent 能力。通过create_deep_agent()一行代码即可创建功能完整的 Agent自动获得 planning、filesystem、subagents、summarization 等六大能力。安装只需pip install deepagents支持 OpenAI、Anthropic、Google、AWS Bedrock 等多种模型提供商真正实现 model-agnostic。