DeepAgents实战：基于配置驱动的多智能体系统开发指南

如果你正在尝试构建一个多智能体系统，大概率会遇到这样的困境：看了无数篇关于Agent、LangChain、LangGraph的概念文章，感觉什么都懂，但打开编辑器却不知道第一行代码该写什么。或者，你按照某个教程跑通了一个“Hello World”级别的示例，但一旦想加入业务逻辑、处理复杂状态流转或让多个Agent协作，立刻就陷入配置地狱和无穷的Bug中。

这背后的根本原因在于，多智能体开发不是一个简单的API调用问题，而是一套工程化框架的选择和架构思维的建立。最近备受关注的DeepAgents，正是试图解决这个核心痛点的一个新兴框架。它并非要取代LangChain或LangGraph，而是提供了一种更贴近生产实践的、声明式的智能体编排方式。

本文将为你彻底厘清DeepAgents、LangChain、LangGraph三者之间的关系与定位，并通过一个从零开始的实战项目，带你体验用DeepAgents构建一个具备记忆和工具调用能力的多智能体系统的完整流程。我们的目标是：让你不仅知道“是什么”，更能掌握“为什么”和“怎么做”，最终具备将多智能体技术落地到真实场景的能力。

1. 多智能体开发的现状与DeepAgents的破局点

在深入代码之前，我们必须先理解当前多智能体开发领域的“地形图”。这决定了我们为何要关注DeepAgents。

传统方式的瓶颈：过去，构建智能体系统通常有两种路径：

1. 从零手写：直接使用OpenAI或Anthropic的API，自己管理对话历史、工具调用逻辑和状态机。这种方式灵活性极高，但复杂度也极高，需要处理大量底层细节，如函数调用解析、状态持久化、错误处理等，极易出错且难以维护。
2. 使用LangChain/LangGraph：LangChain提供了丰富的组件（Chains, Agents, Tools），LangGraph则在此基础上引入了基于图（Graph）的、有状态（State）的工作流编排。它们极大地提升了开发效率，但其设计哲学更偏向于“提供乐高积木”，开发者需要自己设计和组装整个系统架构。对于复杂多智能体协作，你需要精心设计每个节点的状态转移，调试起来并不轻松。

DeepAgents的定位：DeepAgents选择了一条不同的路。它将自己定位为一个“面向生产环境的多智能体框架”。其核心思想是声明式编程和配置驱动。你可以通过YAML或JSON等配置文件，清晰地定义智能体的角色、能力（工具）、工作流以及它们之间的协作关系，而框架负责执行和调度。这带来了几个关键优势：

• 关注点分离：开发者更专注于定义“做什么”（业务逻辑和协作规则），而非“怎么做”（状态管理和流程控制）。
• 可维护性高：配置即文档，整个系统的架构一目了然。
• 易于扩展：新增一个智能体或工具，通常只需修改配置和添加少量代码。
• 内置最佳实践：框架层面集成了记忆管理、工具调用、错误重试等常见模式。

简单来说，LangChain/LangGraph是强大的工具箱和引擎，而DeepAgents更像是一套基于这套引擎的、开箱即用的高级汽车组装方案。它降低了多智能体系统，特别是协作型智能体系统的开发门槛。

2. 核心概念辨析：Agent、Skill、LangChain与LangGraph

在开始实战前，精准理解几个关键概念，能避免后续的混淆。

• Agent（智能体）：一个具有特定目标、能感知环境、使用工具并做出决策的自治程序。在我们的上下文中，一个Agent通常对应一个LLM（大语言模型）实例，配备了一系列可用的函数（Tools）和一段定义其行为的系统提示词（System Prompt）。
• Skill（技能）：在DeepAgents的语境下，Skill通常指一个Agent能够执行的具体能力或工具。例如，“查询天气”、“发送邮件”、“分析数据”都可以是一个Skill。一个Agent可以拥有多个Skills。
• LangChain：一个用于开发由LLM驱动的应用程序的框架。它提供了模块化的组件，如模型封装（LLMs）、提示词模板（Prompt Templates）、记忆（Memory）、链（Chains）和代理（Agents）。它是构建智能体应用的基石。
• LangGraph：建立在LangChain之上的一个库，用于构建有状态的、多环节的工作流。它用“图”（Graph）的概念来建模应用，其中节点代表执行步骤（可以是调用LLM、运行工具等），边代表步骤之间的流转条件。它特别适合构建复杂的、需要循环或分支判断的智能体应用。
• DeepAgents：一个基于LangChain/LangGraph（或其他底层运行时）的高级多智能体编排框架。它通过配置化的方式，让开发者能够更便捷地定义和管理多个智能体及其协作关系，简化了多智能体系统的构建过程。

关系类比： 想象你要建一个机器人餐厅。

• LangChain提供了建造机器人的所有零部件（电机、传感器、处理器）和基本组装方法。
• LangGraph提供了设计机器人内部工作流程的蓝图，比如“接到订单 -> 移动到厨房 -> 取菜 -> 送到餐桌”这个循环流程。
• DeepAgents则直接给了你一个餐厅管理方案，你可以通过配置文件声明：“我需要一个厨师机器人（具备炒菜、烘焙Skill），一个服务员机器人（具备点单、送餐Skill），并规定厨师做完菜后通知服务员”。

3. 环境准备与项目初始化

我们将构建一个简单的“旅行规划顾问”多智能体系统。这个系统包含两个智能体：

1. 目的地专家：负责推荐旅行目的地和亮点。
2. 行程规划师：负责根据目的地，制定详细的每日行程。

技术栈与版本要求：

• Python 3.9+
• pip 包管理工具
• OpenAI API Key（或其他DeepAgents支持的LLM API Key，如Anthropic、DeepSeek等）

步骤1：创建项目目录并安装DeepAgents首先，创建一个干净的项目环境是避免依赖冲突的最佳实践。

# 创建项目目录并进入 mkdir deepagents-travel-planner && cd deepagents-travel-planner # 创建虚拟环境（推荐） python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 安装DeepAgents框架 # 注意：截至本文撰写时，DeepAgents可能仍在快速迭代，请以官方文档为准。 # 通常可以通过pip从GitHub或PyPI安装 pip install “deepagents[all]” # 假设all包含常用依赖 # 或者，如果尚未发布到PyPI，可能需要从GitHub安装 # pip install git+https://github.com/your-repo/deepagents.git # 安装必要的LangChain组件 pip install langchain langchain-openai langchain-community

步骤2：获取并设置API Key你需要一个LLM提供商的API Key。这里以OpenAI为例。

# 在Linux/Mac上，可以将Key添加到环境变量 export OPENAI_API_KEY=‘你的-sk-...密钥’ # 在Windows PowerShell中 $env:OPENAI_API_KEY=‘你的-sk-...密钥’ # 更推荐的做法是使用`.env`文件管理敏感信息

创建一个名为.env的文件在项目根目录：

# .env OPENAI_API_KEY=你的-sk-...密钥

然后，在Python代码中使用python-dotenv加载。

pip install python-dotenv

4. 项目实战：构建旅行规划多智能体系统

我们将采用“配置驱动”的方式，这是DeepAgents的核心哲学。

步骤1：定义智能体配置文件在项目根目录创建一个agents文件夹，并在其中创建两个YAML文件，分别定义我们的两个智能体。

agents/destination_expert.yaml:

# agents/destination_expert.yaml name: “destination_expert” description: “一个精通全球旅行目的地的专家，擅长根据用户偏好推荐地点。” role: “旅行目的地顾问” model: provider: “openai” # 指定模型提供商 name: “gpt-4o” # 指定模型名称 config: temperature: 0.7 max_tokens: 1000 # 系统提示词，定义智能体的核心行为和边界 system_prompt: | 你是一位资深的全球旅行目的地专家。你的知识库涵盖各国的城市、自然风光、文化体验、美食和最佳旅行季节。 你的任务是： 1. 根据用户提供的偏好（如“喜欢海滩”、“预算有限”、“家庭出游”、“冒险活动”），推荐最合适的2-3个目的地。 2. 对每个推荐的目的地，简要说明其核心亮点、最佳旅行时间以及大概的预算水平（低/中/高）。 3. 只回答与旅行目的地推荐相关的问题。如果用户询问行程细节、酒店预订等，请礼貌地告知他们，后续会有“行程规划师”智能体来协助。 请用友好、热情且专业的口吻回答。 # 初始技能列表，这个智能体目前主要依靠LLM的内在知识，暂无自定义工具。 skills: [] # 可以在这里定义记忆配置，例如保留最近5轮对话 memory: type: “conversation_buffer” config: buffer_size: 5

agents/itinerary_planner.yaml:

# agents/itinerary_planner.yaml name: “itinerary_planner” description: “一个专业的行程规划师，能将目的地转化为详细的每日活动安排。” role: “行程规划师” model: provider: “openai” name: “gpt-4o” config: temperature: 0.5 # 行程需要更确定性，温度稍低 max_tokens: 1500 system_prompt: | 你是一位细致入微的旅行行程规划师。你的专长是将一个旅行目的地，转化为一份结构清晰、时间安排合理的多日行程计划。 你的任务是： 1. 接收来自“目的地专家”或用户直接提供的旅行目的地信息。 2. 询问或确认旅行的总天数、出发日期（或季节）、旅行者类型（如情侣、家庭、背包客）以及特别兴趣（如美食、历史、徒步）。 3. 生成一份详细的每日行程表，包含上午、下午、晚上的活动建议，并推荐餐饮和住宿选择（仅限类型和区域，不指定具体酒店）。 4. 行程应合理考虑交通时间、景点开放时间，并融入当地特色体验。 5. 输出格式需整洁，易于阅读。 skills: # 这里可以定义该智能体专属的工具，例如调用外部API查询景点开放时间。 # 本例中我们先不添加，后续可以扩展。 - name: “dummy_skill” description: “一个示例技能，用于演示如何添加工具。” # ... 具体的工具定义会涉及更多代码，此处暂略 memory: type: “conversation_buffer” config: buffer_size: 10 # 行程规划需要更多上下文

步骤2：定义工作流配置文件智能体定义好了，我们需要定义它们如何协作。在项目根目录创建workflows文件夹。

workflows/travel_planning_workflow.yaml:

# workflows/travel_planning_workflow.yaml name: “travel_planning_workflow” description: “旅行规划协作工作流：先由目的地专家推荐地点，再由行程规划师制定行程。” agents: - ref: “destination_expert” # 引用之前定义的智能体 - ref: “itinerary_planner” # 定义工作流的执行步骤 steps: - name: “consult_destination” agent: “destination_expert” # 指定执行此步骤的智能体 trigger: “workflow_start” # 工作流开始的触发器 input: “{{user_input}}” # 将用户的初始输入传递给这个智能体 output_to: “destination_result” # 将此步骤的输出存储到变量 - name: “plan_itinerary” agent: “itinerary_planner” trigger: “after:consult_destination” # 在上一个步骤完成后触发 # 将上一步的输出和可能的额外用户输入组合，传递给规划师 input: | 以下是目的地专家推荐的方案： {{destination_result}} 请基于以上推荐，为我制定一份详细的行程计划。 我的额外要求是：{{user_additional_request}} output_to: “final_itinerary”

这个工作流定义了两个顺序执行的步骤，并定义了数据（destination_result）如何在智能体间传递。

步骤3：编写主程序代码现在，我们需要编写Python代码来加载这些配置并运行工作流。在项目根目录创建main.py。

# main.py import asyncio import os from dotenv import load_dotenv from deepagents import DeepAgents from deepagents.workflow import Workflow # 1. 加载环境变量（包含API Key） load_dotenv() async def main(): # 2. 初始化DeepAgents框架 # 框架会自动搜索当前目录下的 `agents/` 和 `workflows/` 文件夹来加载配置 da = await DeepAgents.create(config_path=“.”) # 指定配置所在根目录 # 3. 获取我们定义的工作流 workflow: Workflow = da.get_workflow(“travel_planning_workflow”) # 4. 准备用户输入 user_input = “我想在7月份进行一次为期5天的旅行，喜欢自然风光和安静的小镇，预算中等。” user_additional_request = “希望行程不要太赶，每天主要活动不超过3个。” # 5. 创建工作流运行的初始上下文（状态） initial_context = { “user_input”: user_input, “user_additional_request”: user_additional_request, } # 6. 执行工作流 print(“开始执行旅行规划工作流...\n”) try: result = await workflow.run(context=initial_context) # 7. 输出最终结果 print(“=” * 50) print(“【最终行程规划结果】”) print(“=” * 50) print(result.get(“final_itinerary”, “未生成行程。”)) except Exception as e: print(f“工作流执行出错: {e}”) if __name__ == “__main__”: asyncio.run(main())

5. 运行与效果验证

步骤1：运行程序确保你的虚拟环境已激活，且.env文件中的API Key已正确设置。

python main.py

步骤2：解读输出程序会依次执行：

1. 目的地专家接收到你的初始输入，生成推荐。
2. 推荐结果作为destination_result被传递给行程规划师，同时附上你的额外要求。
3. 行程规划师综合这些信息，生成一份详细的行程计划。

你将在控制台看到类似以下的输出（内容为AI生成示例）：

开始执行旅行规划工作流... ================================================== 【最终行程规划结果】 ================================================== **目的地推荐（来自目的地专家）：** 基于您7月、5天、喜欢自然风光和安静小镇、中等预算的需求，为您推荐： 1. **瑞士因特拉肯地区（Interlaken）**：坐落在少女峰山脚下，毗邻布里恩茨湖和图恩湖。夏季气候宜人，可乘坐火车上山观光，也可在湖边小镇漫步。预算中等偏高，但体验绝佳。 2. **奥地利哈尔施塔特（Hallstatt）**：被誉为“世界最美小镇”，依山傍湖，宁静如画。适合放松、徒步、摄影。预算中等。 **详细5日行程计划（来自行程规划师）：** **旅行概要：** 奥地利哈尔施塔特5日宁静自然之旅 **旅行者：** 自然风光爱好者，寻求放松 **季节：** 7月夏季 **第一天：抵达与适应** * **上午：** 抵达萨尔茨堡或维也纳，租车或乘坐火车前往哈尔施塔特（约3-4小时车程）。 * **下午：** 入住预先预订的湖边民宿或家庭旅馆。在小镇中心随意漫步，熟悉环境。 * **晚上：** 在湖边餐厅享用一顿地道的奥地利晚餐，品尝维也纳炸猪排或清炖牛肉。 * **住宿建议：** 哈尔施塔特历史中心区的家庭旅馆或精品酒店。 **第二天：湖光山色深度游** * **上午：** 乘坐哈尔施塔特盐矿观光缆车上山，参观世界上最古老的盐矿，体验矿工滑梯。 * **下午：** 乘船游览哈尔施塔特湖，从湖面欣赏小镇全景。随后参观人骨教堂。 * **晚上：** 自由活动，可在民宿露台欣赏夜景。 * （后续几天行程省略...）

如何验证成功？

1. 流程正确：输出清晰地分为“目的地推荐”和“详细行程”两部分，表明两个智能体按顺序工作了。
2. 内容相关：推荐的目的地和行程符合用户输入的限制条件（7月、5天、自然风光、小镇、中等预算）。
3. 角色符合：目的地专家的回答聚焦于推荐和亮点，行程规划师的回答是结构化的日程表。

6. 常见问题与排查思路

在实践过程中，你可能会遇到以下问题：

7. 进阶：为智能体添加自定义Skill（工具）

上面的例子中，智能体仅使用了LLM的内在知识。真正的威力在于为智能体装备“工具”。让我们为itinerary_planner添加一个真实的技能：查询某城市未来几天的天气。

步骤1：创建工具函数在项目根目录创建一个tools文件夹，并新建weather_tool.py。

# tools/weather_tool.py import requests from typing import Optional from pydantic import BaseModel, Field # 定义工具的输入参数模型 class WeatherQueryInput(BaseModel): city: str = Field(description=“需要查询天气的城市名，例如‘北京’、‘New York’。”) days: Optional[int] = Field(default=3, description=“需要预报的天数，默认为3天。”) def get_weather_forecast(city: str, days: int = 3) -> str: “”” 获取指定城市未来几天的天气预报（模拟函数）。 在实际项目中，这里应调用如OpenWeatherMap、和风天气等API。 “”” # 这里是模拟数据。真实情况需要： # 1. 注册天气API服务 # 2. 获取API Key # 3. 构造请求并处理响应 print(f“[工具调用] 正在查询{city}未来{days}天的天气...”) # 模拟API返回 mock_data = { “北京”: [“晴，25-32°C”, “多云，26-33°C”, “雷阵雨，24-30°C”], “上海”: [“阴，27-34°C”, “小雨，26-32°C”, “多云，26-33°C”], “哈尔施塔特”: [“晴朗，18-25°C”, “局部多云，17-24°C”, “晴间多云，19-26°C”], } forecast = mock_data.get(city, [“暂无数据”] * days) result = f“{city}未来{days}天天气预报：\n” + “\n”.join([f“第{i+1}天：{f}” for i, f in enumerate(forecast[:days])]) return result # 这是暴露给DeepAgents/LangChain的工具对象 # 需要符合LangChain Tool的接口规范 weather_tool = { “name”: “get_weather_forecast”, “description”: “获取某个城市未来几天的天气预报信息，用于行程规划参考。”, “args_schema”: WeatherQueryInput, # 指定参数模型 “function”: get_weather_forecast, # 绑定的函数 }

步骤2：修改智能体配置以加载工具更新agents/itinerary_planner.yaml，将自定义工具添加进去。

# agents/itinerary_planner.yaml (更新skills部分) name: “itinerary_planner” # ... 其他部分保持不变 ... skills: # 引用外部定义的工具 - name: “get_weather_forecast” # 工具名称，需与代码中一致 type: “custom_tool” # 声明是自定义工具 module_path: “tools.weather_tool” # 工具模块的导入路径 tool_attribute: “weather_tool” # 模块中暴露的工具变量名 # 也可以选择内联定义简单的工具，这里我们使用外部模块。 # ... memory等其他配置保持不变 ...

步骤3：更新系统提示词以引导使用工具为了让智能体知道在何时使用新工具，需要更新其system_prompt。

# agents/itinerary_planner.yaml (更新system_prompt部分) system_prompt: | 你是一位细致入微的旅行行程规划师。你的专长是将一个旅行目的地，转化为一份结构清晰、时间安排合理的多日行程计划。 你的任务是： 1. 接收来自“目的地专家”或用户直接提供的旅行目的地信息。 2. 询问或确认旅行的总天数、出发日期（或季节）、旅行者类型（如情侣、家庭、背包客）以及特别兴趣（如美食、历史、徒步）。 3. **在制定行程前，你可以使用 `get_weather_forecast` 工具查询目的地的天气预报，以便给出更合理的活动建议（例如，雨天安排室内活动）。** 4. 生成一份详细的每日行程表，包含上午、下午、晚上的活动建议，并推荐餐饮和住宿选择（仅限类型和区域，不指定具体酒店）。 5. 行程应合理考虑交通时间、景点开放时间，并融入当地特色体验。 6. 输出格式需整洁，易于阅读。 **工具说明：** - `get_weather_forecast`: 输入城市名和天数，返回该城市的天气预报。请在你认为需要查询天气时主动使用它。

步骤4：测试再次运行python main.py。现在，行程规划师在制定计划时，可能会先调用天气查询工具。你会在控制台看到[工具调用] 正在查询哈尔施塔特未来3天的天气...的日志，并且生成的行程可能会根据天气情况做出调整（例如，如果预报有雨，可能会建议第二天参观盐矿或博物馆等室内活动）。

8. 最佳实践与工程建议

将多智能体系统用于实际项目时，遵循以下实践能大幅提升成功率和可维护性：

1. 配置与代码分离：始终坚持用YAML/JSON定义智能体和工作流。这使非开发人员（如产品经理）也能理解系统架构，并且便于版本管理和对比。
2. 清晰的智能体职责：每个智能体应具有单一、明确的职责。避免创建“全能型”智能体，这会导致提示词臃肿和效果下降。职责不清是协作混乱的主要根源。
3. 精心设计系统提示词：提示词是智能体的“灵魂”。务必明确其角色、目标、边界和输出格式。使用“必须”、“禁止”、“只做”等强引导词来约束行为。迭代优化提示词是提升效果性价比最高的方式。
4. 实现工具（Skill）的复用性：将工具设计成功能单一、接口清晰的函数。一个工具最好只做一件事。这样可以被多个不同的智能体复用。
5. 工作流设计遵循“高内聚、低耦合”：工作流步骤之间的数据传递应清晰、最小化。避免一个步骤的输出结构过于复杂，导致下一个步骤难以解析。可以使用中间数据格式化或清洗步骤。
6. 加入健壮性处理：
   • 错误处理：在工具函数和工作流步骤中，必须包含异常捕获和友好的错误信息返回。
   • 超时与重试：配置LLM调用和工具调用的超时时间，并对可重试的错误（如网络波动）设置重试机制。
   • 验证与回退：对关键步骤的输出进行验证（例如，检查是否包含必要字段），如果不符合预期，可以设计回退到备用智能体或默认流程。
7. 记录与监控：在生产环境中，详细记录每个智能体的输入、输出、工具调用记录和耗时。这对于调试、效果分析和成本核算至关重要。
8. 成本控制：多智能体系统可能会频繁调用LLM，成本不容忽视。通过设置合理的max_tokens、缓存重复查询的结果、对非关键步骤使用更经济的模型等方式进行优化。
9. 版本控制：将智能体配置、工作流定义、工具代码一同纳入Git等版本控制系统。每次变更都应有明确的记录，便于回滚和协作。

9. 总结：从Demo到生产

通过本教程，我们完成了一个DeepAgents多智能体系统的入门到实战。我们不仅搭建了一个能跑通的Demo，更重要的是理解了其配置驱动和声明式编排的核心思想。

关键收获：

• DeepAgents通过抽象，将多智能体系统的构建从“如何实现状态机”转变为“如何定义协作关系”，这是其最大的价值。
• 智能体（Agent）、技能（Skill）、工作流（Workflow）是三块核心积木，清晰的划分是系统可维护的基础。
• 实践路径是：定义角色 -> 装备技能 -> 编排流程 -> 运行测试 -> 迭代优化。

后续深入方向：

1. 探索更复杂的工作流模式：当前是简单的顺序流。DeepAgents应支持条件分支、并行执行、循环等复杂模式，尝试实现一个需要根据用户反馈动态调整规划的工作流。
2. 集成更强大的工具：将数据库查询、外部API（机票、酒店）、内部业务系统等接入为Skill，打造真正实用的智能体。
3. 实现长期记忆（Memory）：为智能体配置向量数据库，使其能记住跨会话的用户偏好和历史交互，提供个性化服务。
4. 加入评估与反馈机制：设计自动化或人工的评估环节，对智能体的输出进行评分，并利用这些反馈持续优化提示词和流程。
5. 研究Agent间的通信优化：当智能体数量增多时，如何高效、准确地传递信息，避免信息失真或冗余，是一个重要的工程课题。

多智能体系统是AI应用走向复杂和自主的必然路径。DeepAgents这类框架的出现，标志着该领域正从“手工作坊”向“标准化生产”演进。掌握它，意味着你掌握了构建下一代AI原生应用的重要生产力工具。