最近在尝试把一些重复性工作交给 AI Agent 自动化时，我发现了一个很有意思的现象：很多开发者，包括我自己，都曾陷入一个“工具陷阱”——我们花大量时间学习 LangChain、LangGraph 这些框架的 API 和概念，但真正要落地一个能稳定运行、处理复杂逻辑的 Agent 项目时，却常常卡在第一步：如何把想法变成一个可运行、可调试、可扩展的代码结构。

这就像你拿到了乐高积木的所有零件说明书，却不知道从哪块开始拼，才能搭出一座不会散架的城堡。直到我深入实践了DeepAgents这个项目，它提供了一套近乎“保姆级”的工程化起点，我才意识到，Agent 开发的真正难点，往往不在于理解某个框架的“是什么”，而在于掌握从零到一构建一个健壮 Agent 系统的“怎么做”和“为什么这么做”。

今天，我们就以 DeepAgents 为蓝本，抛开那些抽象的概念，直接进入实战。我会手把手带你搭建一个 DeepAgents 项目，并在这个过程中，重点拆解三个核心问题：Agent Skills 如何动态扩展、LangChain 与 LangGraph 在实际项目中究竟如何分工、以及如何设计一个能长期运行且状态可控的 Agent 系统。你会发现，当把这些框架放到一个具体的项目上下文里时，它们的价值和使用边界会清晰得多。

1. 为什么从 DeepAgents 开始：它解决的远不止“跑通一个 Demo”

在接触 DeepAgents 之前，你可能已经看过不少 LangChain 的“Hello World”示例：几行代码调用一个 LLM，完成一次问答。这能让你快速感受到能力，但离一个真正的“Agent 项目”还差得很远。一个生产可用的 Agent 系统，至少需要处理以下几个问题：

• 技能（Skills）的管理与加载：Agent 需要调用工具（如搜索、计算、读写文件）。这些工具如何定义、如何被 Agent 发现和调用、如何安全地管理？
• 工作流（Workflow）与状态管理：任务往往不是一步完成的，需要多个步骤、有条件分支、有循环。如何定义这个流程？每一步的状态如何传递和更新？
• 记忆（Memory）与上下文（Context）：Agent 如何记住之前的对话和操作？长上下文如何有效利用而不至于让提示词（Prompt）爆炸？
• 项目结构与可维护性：代码如何组织才能清晰地区分配置、工具定义、Agent 逻辑、工作流和主程序？

DeepAgents 的价值就在于，它直接提供了一个回答了上述问题的、开箱即用的项目脚手架。它不是另一个框架，而是基于 LangChain 和 LangGraph 的最佳实践集成。你克隆它的项目，相当于直接拿到了一个“Agent 系统”的骨架，你要做的不是从零砌砖，而是在这个骨架上填充血肉——也就是你的具体业务逻辑。

1.1 环境准备与项目初探：先看到全貌

我们首先把项目跑起来，建立最直观的认知。

1. 获取项目：通常你可以从 GitHub 找到 DeepAgents 的仓库。使用 Git 克隆到本地。

   git clone <deepagents-repo-url> cd deepagents

2. 依赖安装：查看项目根目录的requirements.txt或pyproject.toml文件，使用 pip 或 poetry 安装。

   pip install -r requirements.txt

   这里通常会包含langchain,langgraph,langchain-community等核心包，以及项目自身的一些工具依赖。

3. 配置 API 密钥：DeepAgents 需要连接大模型（如 OpenAI, Anthropic 等）。在项目根目录或config/目录下，你会找到类似.env.example的模板文件。复制它并重命名为.env，然后填入你的 API Key。

   OPENAI_API_KEY=sk-你的密钥 # 或 ANTHROPIC_API_KEY=你的密钥

4. 运行第一个示例：项目一般会提供examples/目录。找一个最简单的示例运行，比如python examples/basic_agent.py。这一步的目标不是理解所有代码，而是确认环境无误，并能看到 Agent 运行起来的输入输出日志。

当你看到终端里 Agent 开始“思考”（调用 LLM）和“行动”（调用工具）时，你对 Agent 的认知就从“概念”进入了“可交互的程序”阶段。接下来，我们深入这个程序的内部。

1.2 解剖项目结构：理解“最佳实践”的布局

DeepAgents 的目录结构本身就是一份重要的学习资料。一个典型的布局可能如下：

deepagents/ ├── agents/ # 存放不同 Agent 的定义 ├── skills/ # 核心！存放所有可被 Agent 调用的技能（工具） │ ├── __init__.py │ ├── web_search.py │ ├── calculator.py │ └── file_ops.py ├── workflows/ # 存放用 LangGraph 定义的工作流 ├── config/ # 配置文件和环境变量管理 ├── memory/ # 记忆存储和后端（如向量数据库）集成 ├── examples/ # 使用示例 ├── tests/ # 测试用例 └── main.py # 应用入口

这个结构清晰地体现了关注点分离：

• skills/管“能做什么”（工具）。
• agents/管“谁来做”（赋予 LLM 调用工具的能力和身份）。
• workflows/管“按什么顺序做”（编排多个 Agent 或步骤）。
• memory/管“记住什么”。
• config/管“用什么参数做”。

为什么这个结构重要？因为它解决了 Agent 项目初期最头疼的“代码往哪放”的问题。当你需要新增一个功能，比如让 Agent 能发邮件，你就很自然地知道要去skills/目录下创建一个email_sender.py。这种约束性，对于保持项目长期可维护性至关重要。

2. 核心实践一：动态构建与管理 Agent Skills

Skills 是 Agent 的“手和脚”。DeepAgents 通常采用一种基于装饰器或类注册的机制来动态加载 Skills，这比在代码里硬编码一长串工具列表要优雅和灵活得多。

2.1 如何定义一个 Skill

打开skills/目录下的任意一个文件，比如calculator.py，你会看到类似这样的结构：

from langchain.tools import tool from pydantic import Field, BaseModel # 定义输入参数的模型（可选，但推荐，用于类型验证和说明） class CalculatorInput(BaseModel): a: float = Field(description=”第一个数字”) b: float = Field(description=”第二个数字”) operator: str = Field(description=”运算符，支持 +, -, *, /”) # 使用 @tool 装饰器定义技能 @tool(args_schema=CalculatorInput, return_direct=False) def calculator(a: float, b: float, operator: str) -> str: “””执行简单的四则运算。当需要计算时使用此工具。””” try: if operator == ‘+’: result = a + b elif operator == ‘-‘: result = a – b elif operator == ‘*’: result = a * b elif operator == ‘/’: if b == 0: return “错误：除数不能为零” result = a / b else: return f”错误：不支持的运算符 ‘{operator}’，请使用 +, -, *, /” return f”计算结果：{a} {operator} {b} = {result}” except Exception as e: return f”计算过程中发生错误：{str(e)}”

关键点解析：

1. @tool装饰器：这是 LangChain 提供的，它将一个普通 Python 函数“包装”成一个 LangChain Tool 对象。args_schema参数指定了输入模型，这能让 LLM 更清晰地理解需要提供哪些参数。
2. 文档字符串（Docstring）：“””执行简单的四则运算…”””这部分极其重要！LLM 主要靠这个描述来决定在什么情况下调用这个工具。描述要准确、简洁。
3. 错误处理：在 Skill 内部进行健壮的错误处理并返回友好信息，能防止整个 Agent 因为一个工具调用失败而崩溃。

2.2 Skills 如何被动态加载

DeepAgents 通常会在skills/__init__.py或一个专门的注册中心里，自动发现并注册所有@tool装饰的函数。其核心逻辑可能是遍历skills模块，收集所有 Tool 对象。

# skills/__init__.py 可能简化后的逻辑 import importlib import pkgutil from langchain.tools import BaseTool def get_all_skills(): all_tools = [] # 遍历当前包下的所有模块 for _, module_name, _ in pkgutil.iter_modules(__path__): full_module_name = f”{__name__}.{module_name}” module = importlib.import_module(full_module_name) # 遍历模块中的属性，找到 BaseTool 的实例或 @tool 装饰的函数 for attr_name in dir(module): attr = getattr(module, attr_name) if isinstance(attr, BaseTool): all_tools.append(attr) # 有时 @tool 装饰后可能还不是 BaseTool，需要进一步处理 elif callable(attr) and hasattr(attr, ‘_tool’): # 检查是否有 _tool 属性 all_tools.append(attr._tool) return all_tools # 导出一个工具列表 ALL_SKILLS = get_all_skills()

这样，在创建 Agent 时，你就可以直接from skills import ALL_SKILLS，然后将这个列表传给 Agent。新增一个 Skill 只需要在skills/目录下新建一个.py文件并正确定义，它就会被自动纳入系统。这种设计实现了“开闭原则”，扩展功能时无需修改核心 Agent 的创建代码。

2.3 与 MCP（Model Context Protocol）的思考

在热搜词里看到了 “skills和mcp区别”。这里简单厘清一下：

• Skills (在 DeepAgents/LangChain 语境下)：指的是 Agent 可以调用的、具体的、封装好的函数工具（如计算器、搜索、读写文件）。它们是实现层面、项目内的。
• MCP (Model Context Protocol)：是 Anthropic 提出的一种协议，旨在标准化服务器（提供工具、数据源）与客户端（如 Claude 桌面应用）之间的通信方式。它更偏向于架构层面，解决的是如何让 LLM 动态发现和调用外部服务的问题。

你可以把 DeepAgents 的skills/目录看作一个本地化、项目内的“工具服务器”，而 MCP 设想的是一个标准化、可远程访问的工具服务生态。对于单个项目，DeepAgents 的方式足够且更简单直接；如果你需要构建一个让多个客户端（如不同的 AI 应用）都能调用的中心化工具服务，那么研究 MCP 会更有价值。

3. 核心实践二：用 LangGraph 构建可控的工作流与状态机

当你的 Agent 需要完成多步骤任务，并且步骤之间有依赖、循环或分支时，就该 LangGraph 上场了。DeepAgents 的workflows/目录就是 LangGraph 的用武之地。

3.1 LangChain 与 LangGraph 的分工

这是另一个常见困惑点（从热搜词 “langchain和langgraph的区别” 也能看出）。

• LangChain：核心价值在于“连接”和“组装”。它提供了LLM、Prompt、Memory、Chains（链）和Tools等基础组件，以及将它们快速组合成一条线性处理管线的能力。Agent在 LangChain 中是一种特殊的 Chain，它引入了“根据 LLM 输出决定下一步调用哪个 Tool”的循环。
• LangGraph：核心价值在于“编排”和“状态管理”。它允许你定义任意复杂的有向图工作流，节点可以是调用 LLM、执行工具、运行条件判断等，边定义了执行流向。它显式地管理一个全局的State，所有节点都读写这个状态，非常适合多 Agent 协作、复杂决策流程。

简单比喻：LangChain 像给你提供了乐高积木（组件）和拼装直线轨道的方法（Chain）。LangGraph 则给了你一张设计图和白板，让你可以拼出带岔路、环路和多个站台的复杂铁路系统（Graph），并且能清楚地追踪一辆火车（状态）在整个系统中的位置。

在 DeepAgents 中，agents/下的单个 Agent 可能用 LangChain 的create_react_agent等方式构建。而当需要协调多个这样的 Agent，或者为一个 Agent 设计包含“规划-执行-检查-重试”的复杂循环时，就会在workflows/下使用 LangGraph 来定义。

3.2 设计一个简单的工作流：以“研究报告生成”为例

假设我们要构建一个 Workflow：先让一个“规划师” Agent 分解任务，再让一个“研究员” Agent 搜集信息，最后让一个“写作者” Agent 汇总成报告。

在workflows/research_report.py中：

from typing import TypedDict, Annotated import operator from langgraph.graph import StateGraph, END from langgraph.graph.message import add_messages from langchain_core.messages import HumanMessage # 1. 定义状态（State） class ReportState(TypedDict): # 消息历史，用于记录对话 messages: Annotated[list, add_messages] # 规划步骤产生的任务列表 task_list: list[str] # 研究员收集到的信息 research_findings: list[str] # 最终报告 final_report: str # 2. 定义节点函数 def planner_node(state: ReportState): “””规划节点：分析用户请求，拆解成具体任务列表。””” # 这里会调用规划师 Agent planner_agent = get_planner_agent() # 假设这个函数返回一个配置好的 Agent task_list = planner_agent.invoke({“input”: state[“messages”][-1].content}) # 更新状态 return {“task_list”: task_list} def researcher_node(state: ReportState): “””研究节点：针对每个任务，调用搜索工具收集信息。””” research_findings = [] for task in state[“task_list”]: # 这里会调用研究员 Agent，它拥有搜索技能 researcher_agent = get_researcher_agent() finding = researcher_agent.invoke({“task”: task}) research_findings.append(finding) return {“research_findings”: research_findings} def writer_node(state: ReportState): “””写作节点：基于收集的信息，撰写最终报告。””” writer_agent = get_writer_agent() report = writer_agent.invoke({ “task_list”: state[“task_list”], “findings”: state[“research_findings”] }) return {“final_report”: report} # 3. 构建图 workflow = StateGraph(ReportState) # 添加节点 workflow.add_node(“planner”, planner_node) workflow.add_node(“researcher”, researcher_node) workflow.add_node(“writer”, writer_node) # 设置边（执行顺序） workflow.set_entry_point(“planner”) workflow.add_edge(“planner”, “researcher”) workflow.add_edge(“researcher”, “writer”) workflow.add_edge(“writer”, END) # 编译图 app = workflow.compile()

这个例子展示了 LangGraph 的核心模式：定义状态 -> 定义操作节点的函数 -> 用边连接节点形成流程图。State是整个工作流的共享内存，每个节点只关心自己读写哪部分状态。

3.3 处理循环与条件分支：实现“检查与重试”

更强大的功能是循环。比如，我们可以在“写作”节点后加一个“评审”节点，如果报告不合格，就跳回“研究员”节点重新搜集信息。

def reviewer_node(state: ReportState): “””评审节点：评估报告质量。””” # 调用一个评审 Agent 或简单的规则判断 is_qualified = review_report(state[“final_report”]) # 关键：返回一个 “next” 字段，指示下一步去哪个节点 if is_qualified: return {“next”: “end”} # 结束 else: # 可以更新任务列表，指明需要补充研究什么 new_tasks = generate_followup_tasks(state[“final_report”]) return {“next”: “researcher”, “task_list”: new_tasks} # 在构建图时，需要处理条件边 workflow.add_node(“reviewer”, reviewer_node) workflow.add_edge(“writer”, “reviewer”) # 条件边：根据 reviewer_node 返回状态中的 “next” 字段决定流向 workflow.add_conditional_edges( “reviewer”, # 这是一个路由函数，根据状态决定下一个节点 lambda state: state.get(“next”, “end”), { “researcher”: “researcher”, “end”: END } )

这就是 LangGraph 的威力：它让你能以代码清晰定义出那些用自然语言描述都显得复杂的 Agent 协作流程。State的设计 (State如何设计是热搜词) 是整个工作流设计的核心，你需要仔细规划哪些信息需要跨节点共享。

4. 从搭建到生产：工程化考量与避坑指南

跟着 DeepAgents 的示例跑通流程，只是第一步。要将其用于更严肃的场景，以下几个工程化考量点必须提前规划。

4.1 记忆（Memory）与上下文管理

LangChain 提供了多种记忆后端，如ConversationBufferMemory、ConversationSummaryMemory等。在 DeepAgents 项目中，通常会在创建 Agent 时注入 memory。

关键决策点：

• 记忆放在哪？是每个 Agent 独立记忆，还是整个 Workflow 共享一个记忆？对于多步工作流，通常将记忆作为State的一部分（如我们之前定义的messages字段），在整个流程中传递。
• 长上下文问题：如果对话或收集的信息很长，直接塞进 Prompt 会耗尽 Token 且效果下降。考虑：
  • 使用ConversationSummaryMemory定期总结历史。
  • 使用向量存储（RAG）将历史信息存入向量库，在需要时进行检索召回。这通常涉及memory/目录下的向量数据库集成代码。
• 记忆持久化：当 Agent 重启后，如何恢复之前的对话状态？这需要将记忆对象序列化存储到数据库或文件中。

4.2 错误处理与稳定性

Agent 在自动调用外部工具时，失败是常态。

• 工具层容错：如前所述，在每个 Skill 函数内部做好异常捕获，返回结构化错误信息。
• Agent 层重试：为 Agent 配置重试逻辑。LangChain 的某些 Agent 执行器支持max_iterations和handle_parsing_errors等参数。
• 工作流层监控：在 LangGraph 的工作流中，可以在关键节点后添加“检查节点”，验证上一步的输出是否合理，不合理则触发重试或人工干预流程。
• 日志记录：这是最重要的。确保 Agent 的每一步思考（LLM 调用）、每一次工具调用、每一次状态变更都有清晰的日志。这不仅是调试的需要，也是理解 Agent 行为、进行后续优化的基础。DeepAgents 项目可能已经集成了日志，但你需要确认其详细程度是否满足你的需求。

4.3 性能与成本优化

• 并发与异步：对于批量处理任务，研究 LangChain 或 LangGraph 的异步接口。避免在循环中同步调用，这会导致极慢的速度。
• 缓存：对相同的 Prompt 或工具调用结果进行缓存，可以显著降低 LLM API 调用成本和延迟。考虑使用LangChain的Cache组件。
• 模型选择：不是所有步骤都需要最强大、最贵的模型。在 Workflow 中，可以为“规划”、“创意”类节点使用大模型（如 GPT-4），为“格式化”、“简单分类”类节点使用小模型（如 GPT-3.5-Turbo）或本地模型，以平衡效果与成本。

4.4 测试与评估

如何知道你的 Agent 系统工作得好不好？

• 单元测试：为每个独立的 Skill 编写单元测试，确保其功能正确。
• 集成测试：针对完整的 Workflow，构建一批有标准答案的测试用例，定期运行，监控其输出质量和稳定性。
• 评估指标：根据任务类型定义评估指标，如任务完成率、步骤数、人工审核通过率等。这需要设计评估流程，可能结合人工和自动化。

5. 总结：DeepAgents 带来的思维转变

通过 DeepAgents 的实战，我们得到的远不止一个可运行的项目模板。它更重要的价值是提供了一种构建 AI Agent 应用的工程化思维：

1. 技能优先：将能力封装成独立的、可测试的、文档清晰的 Skills，这是构建复杂 Agent 的基石。
2. 状态驱动：用 LangGraph 的State来显式管理整个工作流的数据流，让复杂的多步逻辑变得可视化和可调试。
3. 关注分离：遵循清晰的项目结构，区分配置、技能、Agent、工作流和记忆，让代码随着功能增长而保持可维护性。
4. 迭代思维：不要指望一次性设计出完美的 Agent。从一个小而准的 Workflow 开始，通过日志观察其行为，不断调整 Prompt、优化 Skills、重构 State，逐步迭代出鲁棒的解决方案。

回到开头的问题，LangChain 和 LangGraph 本身并不难学，难的是如何将它们有机地组合起来，解决真实世界的问题。DeepAgents 这个“保姆级”项目，恰恰降低了这个“从知识到实践”的鸿沟。它告诉你，一个合格的 Agent 系统应该长什么样，以及如何从那里开始，构建属于你自己的、智能的自动化工作流。

下一步，我建议你不要停留在运行示例。尝试基于这个骨架，改造一个你日常工作中最重复、最枯燥的任务。比如，一个自动整理会议纪要并生成待办事项的 Agent，或者一个监控日志并自动生成日报的 Agent。在真实的需求驱动下，你会对 Skills 的设计、State 的规划和错误的处理有更深的理解。这才是学习 Agent 技术最有效的路径。