【DeepAgents 从入门到精通】DeepAgents初识

第 1 章：DeepAgents 是什么

1.1 本章目标

完成本章学习后，你将具备以下能力：

1. 理解 LangChain 生态中 LangChain、LangGraph、DeepAgents 三者的层级关系与分工
2. 掌握 DeepAgents 作为 “agent harness”（代理马具）的核心理念与四大设计特点
3. 独立完成 DeepAgents 的安装与环境搭建，并成功运行第一个 Hello World Agent
4. 理解create_deep_agent()函数签名中每个参数的含义与默认值
5. 了解 DeepAgents 自动提供的六大内置能力：planning（规划）、filesystem（文件系统）、subagents（子代理）、summarization（摘要）、human-in-the-loop（人机协同）

1.2 核心概念

1.2.0 前置概念速览

在深入 DeepAgents 之前，你需要先了解几个核心术语。以下用最通俗的类比解释：

学习建议：如果你对以上某个术语感到陌生，不要担心–随着教程深入，你会逐步理解每个概念。现在只需要知道它们"大概是什么"即可。第 2 章将深入剖析所有架构细节。

1.2.1 LangChain 生态图谱

要理解 DeepAgents，首先需要看清 LangChain 生态的三层架构。这三层如同建造一栋大楼：

• LangChain是"建筑材料"（building blocks）-- 提供模型调用、工具定义、消息处理等基础组件
• LangGraph是"施工框架"（runtime）-- 提供状态图、持久化、流式处理、人机协同等运行时能力
• DeepAgents是"精装样板间"（agent harness）-- 在 LangChain + LangGraph 之上，预置了规划、文件系统、子代理、摘要等开箱即用的能力

通俗类比：如果把构建 AI Agent 比作造车：

• LangChain 是发动机、轮胎、方向盘等零部件
• LangGraph 是底盘和电路系统，让零部件能协同工作
• DeepAgents 是一辆整车，你坐进去就能开，不必从零组装

1.2.2 DeepAgents 核心理念：Agent Harness（代理马具）

DeepAgents 官方将自己定位为“agent harness”，而非一个 agent framework。这个比喻非常精准：

• 马具（harness）不是马本身，而是让骑手能够驾驭马的一套装备
• DeepAgents不是 agent 本身，而是让开发者能够驾驭 LLM 的一套"鞍具"

它具备四个关键设计特点：

1.3 安装与环境搭建

# 安装 deepagents 核心包pipinstalldeepagents# 安装常用模型提供商（按需选择）pipinstall-U"langchain[openai]"# OpenAIpipinstall-U"langchain[anthropic]"# Anthropicpipinstall-U"langchain[google-genai]"# Google Gemini# 如需 MCP 协议支持pipinstalllangchain-mcp-adapters# 设置 API KeyexportOPENAI_API_KEY="sk-..."# 或exportANTHROPIC_API_KEY="sk-..."

1.4 create_deep_agent() 函数签名

fromdeepagentsimportcreate_deep_agent agent=create_deep_agent(model:str|BaseChatModel|None=None,tools:Sequence[BaseTool|Callable|dict[str,Any]]|None=None,*,system_prompt:str|SystemMessage|None=None,middleware:Sequence[AgentMiddleware]=(),subagents:Sequence[SubAgent|CompiledSubAgent|AsyncSubAgent]|None=None,skills:list[str]|None=None,memory:list[str]|None=None,permissions:list[FilesystemPermission]|None=None,backend:BackendProtocol|BackendFactory|None=None,interrupt_on:dict[str,bool|InterruptOnConfig]|None=None,response_format:ResponseFormat[ResponseT]|type[ResponseT]|dict[str,Any]|None=None,state_schema:type[DeepAgentState]|None=None,context_schema:type[ContextT]|None=None,checkpointer:Checkpointer|None=None,store:BaseStore|None=None,debug:bool=False,name:str|None=None,cache:BaseCache|None=None,)->CompiledStateGraph

参数速查表：

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_lower=city.lower()ifcity_lowerinweather_data:returnf"The weather in{city.title()}is{weather_data[city_lower]}."returnf"It's always sunny in{city}!"# 2. 创建 DeepAgentagent=create_deep_agent(model="openai:gpt-4o-mini",# 使用 provider:model 格式tools=[get_weather],system_prompt="You are a helpful weather assistant. Use the get_weather tool to answer weather questions.",)# 3. 运行 Agentresult=agent.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]: Here's 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 步 – 创建 Agent：create_deep_agent()是 DeepAgents 的核心工厂函数。它接收模型标识符、工具列表和系统提示词，内部自动完成：

• 构建默认中间件栈（TodoListMiddleware+FilesystemMiddleware+SubAgentMiddleware）
• 基于 LangGraph 创建状态图（StateGraph）
• 注册所有内置工具（ls、read_file、write_file、edit_file、glob、grep、write_todos、task）

第 3 步 – 运行 Agent：agent.invoke()将消息列表传递给 Agent。Agent 的 LangGraph 运行时执行 plan-act-observe-reflect 循环，直到模型决定不再需要调用工具为止。

第 4 步 – 输出结果：result["messages"]包含完整的对话历史，包括 SystemMessage、HumanMessage、AIMessage、ToolMessage。你可以遍历消息列表来获取最终回复。

1.6 DeepAgents 自动提供了什么

当你调用create_deep_agent()时，以下能力自动就绪或可选启用，分为两类：

自动就绪（无需任何配置，开箱即用）

可选启用（需要显式配置才会生效）

1.7 API 列表速查

1.8 常见错误与避坑

错误 1：混淆create_deep_agent和create_agent

# 错误：LangChain 的 create_agent 没有内置文件系统和子代理fromlangchain.agentsimportcreate_agent agent=create_agent(model="openai:gpt-4o-mini",tools=[...])# agent 没有 ls, read_file, write_todos, task 等工具# 正确：使用 deepagents 的 create_deep_agentfromdeepagentsimportcreate_deep_agent agent=create_deep_agent(model="openai:gpt-4o-mini",tools=[...])# agent 自动拥有完整的内置工具集

错误 2：忘记设置 API Key

# 错误：未设置环境变量agent=create_deep_agent(model="openai:gpt-4o-mini")# 抛出 AuthenticationError# 正确：先设置 API Keyimportos os.environ["OPENAI_API_KEY"]="sk-..."agent=create_deep_agent(model="openai:gpt-4o-mini")

错误 3：工具函数没有 docstring

# 错误：没有 docstringdefget_weather(city:str)->str:returnf"Weather in{city}"# 正确：包含完整 docstring（会被转化为 tool description）defget_weather(city:str)->str:"""Get the current weather for a given city. Args: city: The name of the city to look up. """returnf"Weather in{city}"

错误 4：在model参数中写错 provider 前缀

# 错误：不存在的 provider 或格式错误agent=create_deep_agent(model="gpt-4o-mini")# 缺少 provider 前缀# 正确：使用 provider:model 格式agent=create_deep_agent(model="openai:gpt-4o-mini")agent=create_deep_agent(model="anthropic:claude-sonnet-4-6")

错误 5：混淆invoke和ainvoke的调用场景

# 错误：在 async 函数中调用同步 invokeasyncdefmain():result=agent.invoke(...)# 会阻塞事件循环# 正确：在 async 函数中使用 ainvokeasyncdefmain():result=awaitagent.ainvoke(...)

1.9 最佳实践

1. 始终为工具函数编写完整的 docstring：DeepAgents 依赖 docstring 为 LLM 生成工具描述，缺失 docstring 会导致 LLM 不知道何时调用该工具。
2. 使用provider:model格式指定模型：这种格式让你可以在不同提供商之间快速切换，无需修改代码结构。
3. 善用system_prompt：明确的系统提示词显著提升 Agent 行为质量，尤其是明确告诉 Agent 何时使用task工具委派子代理。
4. 从简单开始，逐步增加复杂度：先用create_deep_agent(model=..., tools=[...])跑通基本流程，再逐步添加subagents、middleware、permissions等高级参数。
5. 使用 LangSmith 追踪 Agent 执行：设置LANGCHAIN_TRACING_V2=true和LANGCHAIN_API_KEY，在 LangSmith 中可视化查看 Agent 的每一步推理和工具调用。

1.10 本章小结

1. DeepAgents 是 LangChain 生态中的"agent harness"，位于 LangChain（基础组件）和 LangGraph（运行时）之上，提供开箱即用的 Agent 能力。
2. 通过create_deep_agent()一行代码即可创建功能完整的 Agent，自动获得 planning、filesystem、subagents、summarization 等六大能力。
3. 安装只需pip install deepagents，支持 OpenAI、Anthropic、Google、AWS Bedrock 等多种模型提供商，真正实现 model-agnostic。