如果你正在尝试构建一个多智能体系统大概率会遇到这样的困境看了无数篇关于Agent、LangChain、LangGraph的概念文章感觉什么都懂但打开编辑器却不知道第一行代码该写什么。或者你按照某个教程跑通了一个“Hello World”级别的示例但一旦想加入业务逻辑、处理复杂状态流转或让多个Agent协作立刻就陷入配置地狱和无穷的Bug中。这背后的根本原因在于多智能体开发不是一个简单的API调用问题而是一套工程化框架的选择和架构思维的建立。最近备受关注的DeepAgents正是试图解决这个核心痛点的一个新兴框架。它并非要取代LangChain或LangGraph而是提供了一种更贴近生产实践的、声明式的智能体编排方式。本文将为你彻底厘清DeepAgents、LangChain、LangGraph三者之间的关系与定位并通过一个从零开始的实战项目带你体验用DeepAgents构建一个具备记忆和工具调用能力的多智能体系统的完整流程。我们的目标是让你不仅知道“是什么”更能掌握“为什么”和“怎么做”最终具备将多智能体技术落地到真实场景的能力。1. 多智能体开发的现状与DeepAgents的破局点在深入代码之前我们必须先理解当前多智能体开发领域的“地形图”。这决定了我们为何要关注DeepAgents。传统方式的瓶颈过去构建智能体系统通常有两种路径从零手写直接使用OpenAI或Anthropic的API自己管理对话历史、工具调用逻辑和状态机。这种方式灵活性极高但复杂度也极高需要处理大量底层细节如函数调用解析、状态持久化、错误处理等极易出错且难以维护。使用LangChain/LangGraphLangChain提供了丰富的组件Chains, Agents, ToolsLangGraph则在此基础上引入了基于图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. 环境准备与项目初始化我们将构建一个简单的“旅行规划顾问”多智能体系统。这个系统包含两个智能体目的地专家负责推荐旅行目的地和亮点。行程规划师负责根据目的地制定详细的每日行程。技术栈与版本要求Python 3.9pip 包管理工具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 githttps://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-dotenv4. 项目实战构建旅行规划多智能体系统我们将采用“配置驱动”的方式这是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: 5agents/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(contextinitial_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解读输出程序会依次执行目的地专家接收到你的初始输入生成推荐。推荐结果作为destination_result被传递给行程规划师同时附上你的额外要求。行程规划师综合这些信息生成一份详细的行程计划。你将在控制台看到类似以下的输出内容为AI生成示例开始执行旅行规划工作流... 【最终行程规划结果】 **目的地推荐来自目的地专家** 基于您7月、5天、喜欢自然风光和安静小镇、中等预算的需求为您推荐 1. **瑞士因特拉肯地区Interlaken**坐落在少女峰山脚下毗邻布里恩茨湖和图恩湖。夏季气候宜人可乘坐火车上山观光也可在湖边小镇漫步。预算中等偏高但体验绝佳。 2. **奥地利哈尔施塔特Hallstatt**被誉为“世界最美小镇”依山傍湖宁静如画。适合放松、徒步、摄影。预算中等。 **详细5日行程计划来自行程规划师** **旅行概要** 奥地利哈尔施塔特5日宁静自然之旅 **旅行者** 自然风光爱好者寻求放松 **季节** 7月夏季 **第一天抵达与适应** * **上午** 抵达萨尔茨堡或维也纳租车或乘坐火车前往哈尔施塔特约3-4小时车程。 * **下午** 入住预先预订的湖边民宿或家庭旅馆。在小镇中心随意漫步熟悉环境。 * **晚上** 在湖边餐厅享用一顿地道的奥地利晚餐品尝维也纳炸猪排或清炖牛肉。 * **住宿建议** 哈尔施塔特历史中心区的家庭旅馆或精品酒店。 **第二天湖光山色深度游** * **上午** 乘坐哈尔施塔特盐矿观光缆车上山参观世界上最古老的盐矿体验矿工滑梯。 * **下午** 乘船游览哈尔施塔特湖从湖面欣赏小镇全景。随后参观人骨教堂。 * **晚上** 自由活动可在民宿露台欣赏夜景。 * 后续几天行程省略...如何验证成功流程正确输出清晰地分为“目的地推荐”和“详细行程”两部分表明两个智能体按顺序工作了。内容相关推荐的目的地和行程符合用户输入的限制条件7月、5天、自然风光、小镇、中等预算。角色符合目的地专家的回答聚焦于推荐和亮点行程规划师的回答是结构化的日程表。6. 常见问题与排查思路在实践过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named ‘deepagents’DeepAgents未正确安装或不在当前Python环境。1. 运行 pip listgrep deepagents 检查。2. 确认虚拟环境已激活。AuthenticationError或Invalid API KeyAPI Key未设置或错误。1. 检查.env文件是否存在且格式正确。2. 运行echo $OPENAI_API_KEY(Linux/Mac) 或echo %OPENAI_API_KEY%(Windows) 查看环境变量。3. 在代码中打印os.getenv(‘OPENAI_API_KEY’)的前几位检查。1. 确保.env文件在项目根目录且内容为KEYvalue格式无多余空格引号。2. 重启终端或IDE使环境变量生效。3. 在提供商后台检查API Key是否有效、有余额。智能体配置加载失败YAML文件格式错误或路径不对。1. 检查YAML文件的缩进必须是空格。2. 检查config_path参数是否指向了包含agents和workflows文件夹的目录。3. 查看DeepAgents初始化时的日志或错误信息。1. 使用在线YAML校验器检查文件格式。2. 使用绝对路径或确保相对路径正确。3. 简化配置逐步排查。工作流执行中断没有输出最终结果某个智能体调用LLM失败或工作流步骤配置有误。1. 在main.py中增加更详细的异常捕获和打印。2. 尝试单独测试每个智能体的YAML配置是否能独立运行。3. 检查steps中的trigger和input模板变量名是否正确。1. 封装一个简单的测试函数单独调用destination_expert看是否正常响应。2. 确保input中的{{variable}}在initial_context中存在。输出内容不符合预期如角色混乱智能体的system_prompt定义不够清晰或冲突。仔细阅读每个智能体的system_prompt模拟LLM视角看指令是否明确无歧义。优化提示词工程。明确每个智能体的职责边界使用更强烈的引导词如“你必须只做...”、“禁止讨论...”。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(default3, 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“第{i1}天{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. 最佳实践与工程建议将多智能体系统用于实际项目时遵循以下实践能大幅提升成功率和可维护性配置与代码分离始终坚持用YAML/JSON定义智能体和工作流。这使非开发人员如产品经理也能理解系统架构并且便于版本管理和对比。清晰的智能体职责每个智能体应具有单一、明确的职责。避免创建“全能型”智能体这会导致提示词臃肿和效果下降。职责不清是协作混乱的主要根源。精心设计系统提示词提示词是智能体的“灵魂”。务必明确其角色、目标、边界和输出格式。使用“必须”、“禁止”、“只做”等强引导词来约束行为。迭代优化提示词是提升效果性价比最高的方式。实现工具Skill的复用性将工具设计成功能单一、接口清晰的函数。一个工具最好只做一件事。这样可以被多个不同的智能体复用。工作流设计遵循“高内聚、低耦合”工作流步骤之间的数据传递应清晰、最小化。避免一个步骤的输出结构过于复杂导致下一个步骤难以解析。可以使用中间数据格式化或清洗步骤。加入健壮性处理错误处理在工具函数和工作流步骤中必须包含异常捕获和友好的错误信息返回。超时与重试配置LLM调用和工具调用的超时时间并对可重试的错误如网络波动设置重试机制。验证与回退对关键步骤的输出进行验证例如检查是否包含必要字段如果不符合预期可以设计回退到备用智能体或默认流程。记录与监控在生产环境中详细记录每个智能体的输入、输出、工具调用记录和耗时。这对于调试、效果分析和成本核算至关重要。成本控制多智能体系统可能会频繁调用LLM成本不容忽视。通过设置合理的max_tokens、缓存重复查询的结果、对非关键步骤使用更经济的模型等方式进行优化。版本控制将智能体配置、工作流定义、工具代码一同纳入Git等版本控制系统。每次变更都应有明确的记录便于回滚和协作。9. 总结从Demo到生产通过本教程我们完成了一个DeepAgents多智能体系统的入门到实战。我们不仅搭建了一个能跑通的Demo更重要的是理解了其配置驱动和声明式编排的核心思想。关键收获DeepAgents通过抽象将多智能体系统的构建从“如何实现状态机”转变为“如何定义协作关系”这是其最大的价值。智能体Agent、技能Skill、工作流Workflow是三块核心积木清晰的划分是系统可维护的基础。实践路径是定义角色 - 装备技能 - 编排流程 - 运行测试 - 迭代优化。后续深入方向探索更复杂的工作流模式当前是简单的顺序流。DeepAgents应支持条件分支、并行执行、循环等复杂模式尝试实现一个需要根据用户反馈动态调整规划的工作流。集成更强大的工具将数据库查询、外部API机票、酒店、内部业务系统等接入为Skill打造真正实用的智能体。实现长期记忆Memory为智能体配置向量数据库使其能记住跨会话的用户偏好和历史交互提供个性化服务。加入评估与反馈机制设计自动化或人工的评估环节对智能体的输出进行评分并利用这些反馈持续优化提示词和流程。研究Agent间的通信优化当智能体数量增多时如何高效、准确地传递信息避免信息失真或冗余是一个重要的工程课题。多智能体系统是AI应用走向复杂和自主的必然路径。DeepAgents这类框架的出现标志着该领域正从“手工作坊”向“标准化生产”演进。掌握它意味着你掌握了构建下一代AI原生应用的重要生产力工具。