基于LangGraph与DeepAgents的多智能体系统实战：从零构建协作式AI应用

最近在尝试构建一个多智能体系统时发现市面上关于 DeepAgents 的实战资料非常零散要么是简单的概念介绍要么是复杂的论文解读真正能跑起来、能落地的“手把手”教程少之又少。本文旨在填补这个空白为你提供一份从零到一的 DeepAgents 多智能体项目实战指南。我们将结合 LangChain 和 LangGraph 这两个强大的框架一步步构建一个具备协作能力的智能体系统。无论你是想入门多智能体领域的学生还是希望将智能体技术应用到实际项目中的开发者这篇文章都能让你避开我踩过的坑快速上手并理解其核心。1. 背景与核心概念为什么需要多智能体在深入代码之前我们先理清几个关键概念。这能帮助你理解我们正在构建什么以及为什么要用这些工具。1.1 什么是智能体Agent在人工智能领域一个“智能体”可以被理解为一个能够感知环境、进行决策并执行行动以实现特定目标的实体。它不再是一个简单的函数调用而是一个具备一定自主性的程序单元。例如一个专门查询天气的智能体、一个负责分析数据的智能体或者一个能够编写代码的智能体。1.2 从单智能体到多智能体系统MAS单个智能体的能力是有限的。当任务变得复杂时比如需要规划一次旅行涉及查询天气、预订机票、推荐酒店等多个步骤让一个智能体完成所有工作会显得笨重且容易出错。多智能体系统的思想就是将复杂任务分解由多个各司其职的智能体通过通信与协作共同完成。这更贴近人类社会的分工合作模式能显著提升系统的鲁棒性、效率和可扩展性。1.3 LangChain、LangGraph 与 DeepAgents 的角色LangChain一个用于开发由语言模型驱动的应用程序的框架。它提供了丰富的工具Tools、记忆Memory和链Chains是构建智能体的“工具箱”和“脚手架”。它让智能体能够调用外部API、访问数据库或进行计算。LangGraph建立在 LangChain 之上用于构建有状态的、多智能体的应用程序。它的核心是图Graph你可以将智能体定义为图中的节点Nodes将智能体之间的交互和流程控制定义为边Edges。LangGraph 非常适合编排具有复杂循环、分支和协作逻辑的多智能体工作流。DeepAgents这是一个相对较新的开源框架它进一步封装和增强了基于 LangChain/LangGraph 的多智能体构建体验。DeepAgents 提供了更高级的抽象例如更容易定义智能体角色、管理智能体间的通信协议、以及内置了一些常见的多智能体协作模式。你可以把它看作是“多智能体系统的高级样板间”。简单比喻LangChain 提供了砖块和水泥Tools, ChainsLangGraph 提供了建筑设计图和施工流程Graph, State而 DeepAgents 则提供了一套已经设计好户型、水电布局的精装房模板让你能更快地入住构建应用。2. 环境准备与版本说明在开始构建之前我们需要搭建好开发环境。以下配置是经过验证可运行的组合建议你尽量保持一致以减少环境问题。操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04) 均可。Python 版本Python 3.10 或 3.11。这是目前 LangChain 等生态兼容性最好的版本不推荐使用 Python 3.12 以上的最新版本可能存在未适配的依赖。IDE推荐使用 VSCode 或 PyCharm。2.1 创建虚拟环境并安装依赖强烈建议使用虚拟环境来隔离项目依赖。# 1. 创建项目目录并进入 mkdir deepagents-tutorial cd deepagents-tutorial # 2. 创建 Python 虚拟环境 (以 venv 为例) python -m venv venv # 3. 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 4. 升级 pip pip install --upgrade pip2.2 安装核心库我们将安装 LangChain、LangGraph、DeepAgents 以及 OpenAI 的 SDK作为本例的 LLM 后端。你也可以替换为其他兼容的模型如 Anthropic Claude、DeepSeek 等。# 安装核心框架 pip install langchain langgraph deepagents # 安装 OpenAI 官方库 (用于调用 GPT 模型) pip install openai # 安装一些辅助工具库如环境变量管理 pip install python-dotenv版本说明截至2024年底供参考langchain: 0.1.0 (注意LangChain 版本迭代快API 可能有变化本文基于 0.1.x 风格)langgraph: 0.0.40deepagents: 0.1.0openai: 1.0.0请通过pip list | findstr “langchain|langgraph|deepagents”(Windows) 或pip list | grep -E “langchain|langgraph|deepagents”(macOS/Linux) 检查安装版本。2.3 配置 API 密钥我们需要一个大型语言模型LLM来驱动智能体。这里以 OpenAI GPT 为例。你需要准备一个有效的 OpenAI API Key。在项目根目录创建.env文件。在.env文件中填入你的密钥# .env OPENAI_API_KEY你的-openai-api-key-here在代码中通过dotenv加载这个密钥。永远不要将密钥硬编码在代码中3. 核心概念与流程拆解在动手写代码前理解 LangGraph 和 DeepAgents 的核心运作机制至关重要。3.1 LangGraph 的核心状态State与图GraphLangGraph 应用围绕状态State展开。状态是一个字典或 Pydantic 模型它随着图的执行而更新。每个节点智能体或函数读取状态执行操作并返回一个更新后的状态字典。一个典型的智能体协作图包含以下部分节点Nodes执行具体任务的单元通常是一个函数或一个智能体。边Edges定义节点之间的流转逻辑。分为两种条件边Conditional Edges根据当前状态的值决定下一个执行哪个节点。这实现了if-else分支逻辑。普通边Normal Edges无条件地从一个节点指向下一个节点。入口点Entry Point图开始执行的第一个节点。结束点Finish图执行结束的标志。3.2 DeepAgents 的抽象角色Role与团队TeamDeepAgents 在 LangGraph 的基础上引入了更直观的“角色”和“团队”概念。角色Role定义一个智能体的身份、目标和能力。例如“研究员”角色擅长搜索和分析“作家”角色擅长归纳和写作。团队Team将多个角色组织在一起并定义他们之间的协作流程即 LangGraph 的图结构。DeepAgents 简化了图的构建过程。3.3 多智能体协作的基本流程一个典型的多智能体任务执行流程如下用户输入用户提出一个复杂请求例如“写一篇关于量子计算最新进展的博客文章”。任务规划与分发一个“主管”或“协调者”智能体分析请求将其分解为子任务如1. 搜索最新资料2. 分析资料要点3. 撰写文章草稿4. 润色文章。智能体执行各个专业智能体研究员、分析师、作家、编辑领取子任务并执行他们可以调用工具如网络搜索、代码执行。结果汇总与迭代执行结果返回给协调者协调者判断任务是否完成或是否需要其他智能体进一步处理例如文章需要修改。这个过程可能形成循环。最终输出所有子任务满足要求后向用户返回最终结果。4. 完整实战案例构建一个“技术博客写作”多智能体团队现在我们来实战构建一个由三个智能体组成的团队协作完成技术博客写作任务。团队包括研究员Researcher负责搜索网络信息。作家Writer负责根据资料撰写文章。编辑Editor负责对文章进行润色和校对。4.1 项目结构初始化创建以下项目结构deepagents-tutorial/ ├── .env # 存储 API 密钥 ├── requirements.txt # 依赖列表 (可选) ├── app.py # 主应用程序 └── agents/ # 智能体模块目录 ├── __init__.py ├── researcher.py ├── writer.py └── editor.py4.2 配置环境与基础设置在app.py中我们先进行基础配置。# app.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI # 1. 加载环境变量 load_dotenv() # 2. 初始化 LLM # 我们为不同的智能体使用同一个模型但你可以为不同角色分配不同模型 llm ChatOpenAI( modelgpt-4o-mini, # 也可以用 gpt-3.5-turbo 控制成本 temperature0.7, # 创造性对于写作可以稍高对于研究可以调低 api_keyos.getenv(OPENAI_API_KEY) ) print(LLM 和基础环境初始化完成。)4.3 创建研究员智能体Researcher研究员需要能搜索网络。我们将使用 LangChain 的TavilySearchResults工具。你需要先去 Tavily 注册获取一个免费的 API Key并添加到.env文件TAVILY_API_KEY你的key。# agents/researcher.py from langchain.agents import AgentExecutor, create_react_agent from langchain_core.prompts import PromptTemplate from langchain_community.tools.tavily_search import TavilySearchResults from app import llm # 导入主文件中的 llm import os # 1. 为研究员定义工具 search_tool TavilySearchResults( tavily_api_keyos.getenv(TAVILY_API_KEY), max_results3 # 每次搜索返回3条结果 ) tools [search_tool] # 2. 定义研究员专属的提示词Prompt RESEARCHER_PROMPT PromptTemplate.from_template( 你是一位专业的技术研究员。你的任务是针对用户提出的技术主题进行高效、准确的网络搜索并提炼出关键、可靠的信息。 请使用提供的搜索工具来获取信息。 在回复时请先陈述你搜索了哪些关键词然后以清晰、有条理的方式总结你找到的信息要点。 确保信息的时效性和相关性。 当前查询{input} 请开始你的研究 ) # 3. 创建智能体 researcher_agent create_react_agent( llmllm, toolstools, promptRESEARCHER_PROMPT ) # 4. 创建智能体执行器 researcher_agent_executor AgentExecutor( agentresearcher_agent, toolstools, verboseTrue, # 打印详细执行过程调试时非常有用 handle_parsing_errorsTrue # 优雅处理解析错误 ) # 5. 封装一个调用函数供 LangGraph 节点使用 def run_researcher_agent(state): 研究员节点函数。它接收状态执行研究并更新状态。 query state.get(query) or state.get(messages)[-1].content if state.get(messages) else No query provided. print(f\n 研究员开始工作查询主题{query} ) result researcher_agent_executor.invoke({input: query}) research_summary result.get(output, 研究未获得结果。) print(f 研究员工作完成 \n) # 将研究成果放入状态中供下一个智能体使用 # 我们使用一个名为 research_materials 的键来存储 return {research_materials: research_summary}4.4 创建作家智能体Writer作家智能体不需要特殊工具它根据研究员提供的材料进行写作。# agents/writer.py from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_core.messages import HumanMessage, SystemMessage from app import llm # 1. 定义作家系统提示词 writer_system_prompt 你是一位资深技术博客作家。你的风格清晰、易懂、逻辑性强善于将复杂的技术概念用生动的例子解释出来。 你的任务是根据研究员提供的技术资料撰写一篇技术博客文章的初稿。 文章需要包含 1. 一个吸引人的标题。 2. 简要的背景介绍。 3. 核心技术的原理或步骤讲解这是重点。 4. 简单的代码示例或比喻如果适用。 5. 总结与展望。 请确保文章结构完整段落分明字数在800字左右。直接输出文章正文不要加“标题”之类的额外说明。 # 2. 创建调用函数 def run_writer_agent(state): 作家节点函数。读取研究材料撰写文章草稿。 research state.get(research_materials) if not research: return {draft: 错误未收到研究材料无法撰写。} print(f\n 作家开始工作基于研究材料进行创作 ) # 构建对话 messages [ SystemMessage(contentwriter_system_prompt), HumanMessage(contentf请根据以下研究资料撰写一篇技术博客文章\n\n{research}) ] response llm.invoke(messages) draft response.content print(f 作家完成初稿 \n) return {draft: draft}4.5 创建编辑智能体Editor编辑智能体负责润色和校对文章草稿。# agents/editor.py from langchain_core.prompts import ChatPromptTemplate from app import llm # 1. 定义编辑系统提示词 editor_system_prompt 你是一位严格的技术编辑。你的任务是审查和润色技术文章草稿。 请重点关注以下方面 1. **语言流畅性**修正拗口的句子、语法错误和错别字。 2. **逻辑结构**检查文章段落衔接是否自然逻辑是否通顺。 3. **技术准确性**确保文章中的技术描述没有明显错误基于常识判断。 4. **可读性**让文章更易于理解可以建议添加小标题或列表。 5. **简洁性**删除冗余的废话。 请直接输出润色后的完整文章。在文章末尾用【编辑备注】开头简要列出你做的几项主要修改。 def run_editor_agent(state): 编辑节点函数。读取草稿进行润色。 draft state.get(draft) if not draft: return {final_output: 错误未收到文章草稿无法编辑。} print(f\n 编辑开始工作润色文章草稿 ) prompt ChatPromptTemplate.from_messages([ (system, editor_system_prompt), (human, 请润色以下文章草稿\n\n{draft}) ]) chain prompt | llm result chain.invoke({draft: draft}) final_output result.content print(f 编辑工作完成 \n) return {final_output: final_output}4.6 使用 LangGraph 编排团队协作流程现在我们将三个智能体组织成一个有序的工作流研究员 - 作家 - 编辑。# app.py (续) from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator from agents.researcher import run_researcher_agent from agents.writer import run_writer_agent from agents.editor import run_editor_agent # 1. 定义状态结构 # 使用 TypedDict 来明确状态中有什么 class BlogTeamState(TypedDict): 团队协作的状态流。 query: str # 用户最初的查询 research_materials: str # 研究员产出的资料 draft: str # 作家产出的草稿 final_output: str # 编辑产出的最终文章 # 2. 构建图 workflow StateGraph(BlogTeamState) # 3. 添加节点 # 节点名 节点函数 workflow.add_node(researcher, run_researcher_agent) workflow.add_node(writer, run_writer_agent) workflow.add_node(editor, run_editor_agent) # 4. 设置入口点 workflow.set_entry_point(researcher) # 5. 添加边定义执行顺序研究员 - 作家 - 编辑 - 结束 workflow.add_edge(researcher, writer) workflow.add_edge(writer, editor) workflow.add_edge(editor, END) # 6. 编译图得到可执行的应用 app workflow.compile()4.7 运行多智能体应用并测试最后我们编写主程序来运行这个团队。# app.py (续主执行部分) if __name__ __main__: print( 启动技术博客写作多智能体团队 ) user_query input(请输入你想要了解或撰写博客的技术主题例如LangGraph 的核心概念: ).strip() if not user_query: user_query 多智能体系统在软件开发中的应用 # 初始化状态 initial_state BlogTeamState(queryuser_query, research_materials, draft, final_output) print(f\n用户需求{user_query}) print( * 50) print(团队开始协作...\n) # 执行图 try: final_state app.invoke(initial_state) print(\n *50) print(✅ 团队协作完成最终输出如下\n) print(final_state[final_output]) print(\n *50) # 可选保存结果到文件 with open(fblog_output_{user_query[:20]}.txt, w, encodingutf-8) as f: f.write(final_state[final_output]) print(f结果已保存至当前目录下的文件。) except Exception as e: print(f\n❌ 执行过程中出现错误{e}) # 可以在这里添加更详细的错误处理逻辑4.8 运行与结果在终端激活虚拟环境后运行程序python app.py程序会提示你输入一个技术主题。例如输入“Python 中的异步编程 asyncio”。你会看到控制台依次打印研究员开始搜索并总结信息。作家根据资料撰写初稿。编辑对初稿进行润色。最终输出一篇经过研究、撰写、编辑三个环节的技术博客文章。5. 常见问题与排查思路在实践过程中你可能会遇到以下问题问题现象常见原因解决思路ModuleNotFoundError: No module named ‘langchain_community’依赖未正确安装或版本冲突。1. 确认虚拟环境已激活。2. 运行pip install langchain-community。3. 检查requirements.txt或重新安装pip install “langchain[all]”。AuthenticationError或Invalid API KeyAPI 密钥未设置或错误。1. 检查.env文件是否存在且密钥名称正确OPENAI_API_KEY,TAVILY_API_KEY。2. 确认密钥有效额度、是否过期。3. 重启终端或 IDE 以确保环境变量加载。智能体输出“我不知道”或胡言乱语提示词Prompt设计不佳或温度temperature过高。1. 仔细检查并优化系统提示词明确角色、任务和输出格式。2. 将temperature参数调低如从 0.7 调到 0.2以获得更确定性的输出。3. 在提示词中增加“如果不知道请明确说明”的约束。图执行卡住或进入死循环图中存在未正确连接的边或条件逻辑错误。1. 检查add_edge的节点名称是否拼写正确。2. 如果使用了条件边确保条件函数返回的字符串与已定义的节点名完全匹配。3. 启用verboseTrue观察每个节点的输入输出。搜索工具返回空或错误结果Tavily API 密钥问题或查询词不明确。1. 确认 Tavily API Key 已配置且账户有额度。2. 尝试在提示词中让智能体生成更具体、明确的关键词进行搜索。3. 考虑使用其他搜索工具如 Serper API、Google Search API。程序报错TypeError与状态字典相关状态State的结构定义与节点返回的键不匹配。1. 确保TypedDict中定义的键与每个节点函数返回的字典键一致。2. 使用Annotated和operator.add来安全地更新状态本文示例为简化未使用复杂场景推荐使用。3. 打印每个节点执行前后的状态进行调试。6. 最佳实践与工程建议当你掌握了基础构建方法后以下建议能帮助你构建更健壮、更实用的多智能体系统。6.1 设计清晰的状态结构状态是 LangGraph 的血液。在设计初期就明确定义状态字典的 schema。使用TypedDict或 PydanticBaseModel可以极大地提高代码可读性和可维护性并能在开发早期发现类型错误。from pydantic import BaseModel, Field from typing import List class ProjectState(BaseModel): 一个更复杂的状态示例 original_query: str research_findings: List[str] Field(default_factorylist) draft_content: str None critique_feedback: str None revised_content: str None is_approved: bool False6.2 实现智能的流程控制条件边简单的线性流程A-B-C往往不够。利用条件边可以实现评审、循环等复杂逻辑。例如增加一个“评审员”节点如果文章不合格则返回给作家重写。from langgraph.graph import StateGraph, END from langgraph.checkpoint import MemorySaver def should_revise(state: ProjectState) - str: 判断是否需要修订。 if state.critique_feedback and 需要重写 in state.critique_feedback: return rewrite # 跳转到 rewrite 节点 else: return approve # 跳转到 approve 节点 workflow StateGraph(ProjectState) workflow.add_node(“writer”, write_draft) workflow.add_node(“critic”, critique_draft) workflow.add_node(“rewriter”, rewrite_draft) workflow.add_node(“approver”, final_approval) workflow.set_entry_point(“writer”) workflow.add_edge(“writer”, “critic”) # 关键条件边 workflow.add_conditional_edges( “critic”, should_revise, # 条件判断函数 { “rewrite”: “rewriter”, # 如果返回 “rewrite”去 rewriter 节点 “approve”: “approver” # 如果返回 “approve”去 approver 节点 } ) workflow.add_edge(“rewriter”, “critic”) # 重写后再次交给评审形成循环 workflow.add_edge(“approver”, END)6.3 为智能体配备合适的工具智能体的能力取决于其工具。除了网络搜索常见的工具还包括计算器/代码执行器langchain_experimental.tools.PythonREPLTool文件读写自定义工具用于读取项目文档或保存结果。数据库查询封装 SQL 查询工具。专用 API调用企业内部或第三方 API。 为智能体选择工具时要遵循“最小权限”原则只赋予其完成任务所必需的权限。6.4 引入持久化记忆与检查点对于长对话或多轮任务需要让智能体记住之前的交互。LangGraph 的MemorySaver和checkpointer可以保存图执行的状态实现长期记忆和中断恢复。from langgraph.checkpoint import MemorySaver memory MemorySaver() app workflow.compile(checkpointermemory) # 第一次调用传入一个 thread_id config {“configurable”: {“thread_id”: “blog-session-1”}} result1 app.invoke({“query”: “什么是 Docker”}, config) # 系统会保存这次会话的状态 # 第二次调用使用相同的 thread_id智能体可以记住上下文 result2 app.invoke({“query”: “它和虚拟机有什么区别”}, config)6.5 生产环境考量错误处理与降级在每个智能体节点外包裹try…except确保单个智能体失败不会导致整个系统崩溃并能提供友好的错误信息或降级方案。超时控制为 LLM 调用和工具执行设置超时避免长时间无响应。日志与监控记录每个智能体的输入、输出、耗时和 token 使用量便于问题排查和成本分析。成本优化根据任务重要性选择不同成本的模型如 GPT-4 Turbo 用于核心推理GPT-3.5-Turbo 用于简单分类并设置 token 使用上限。7. 总结与学习路线通过本教程你已经完成了一个完整的 DeepAgents 多智能体项目实战。我们从零开始搭建了由研究员、作家、编辑组成的协作团队并使用 LangGraph 清晰地定义了他们的工作流程。这个流程是可扩展的模板你可以轻松地替换其中的智能体角色、工具和协作逻辑以应对不同的业务场景。核心掌握点环境搭建正确配置 Python 环境、安装依赖、管理 API 密钥。智能体构建使用 LangChain 的create_react_agent或自定义函数结合提示词和工具来创建具有特定能力的智能体。状态设计使用TypedDict或 Pydantic 模型来规划智能体间传递的信息。图编排使用StateGraph将智能体定义为节点用边普通边和条件边连接它们形成可控的工作流。运行与调试编译并调用图利用verbose模式观察执行过程排查问题。下一步学习路线深入 LangGraph研究官方文档中的State更高级的用法如Annotated注解、Checkpointer持久化、以及Prebuilt组件如ToolNode,ConditionalEntryPoint。探索更多工具将向量数据库如 Chroma, Pinecone作为智能体的记忆体实现 RAG检索增强生成能力。复杂流程设计尝试实现带有分支、循环、并行add_node后可接多个边的复杂决策流程。集成前端使用FastAPI或Gradio为你的多智能体系统构建一个简单的 Web 界面。关注 DeepAgents 发展DeepAgents 作为新兴框架关注其官方更新学习其提供的更高级的团队模板和通信原语。多智能体系统是构建复杂 AI 应用的有力范式。它不再追求一个“全能”的模型而是通过分工协作、取长补短的方式更可靠地解决复杂问题。希望这篇教程能成为你探索这一有趣领域的坚实起点。动手修改代码添加新的智能体设计不同的协作图是学习的最佳途径。如果在实践中遇到问题回顾“常见问题”章节并善用 LangChain 和 LangGraph 的官方文档与社区资源。