LangGraph多智能体系统实战：从原理到构建AI协作应用

最近在尝试构建一个复杂的AI应用时，你是否遇到过这样的困境：单个大语言模型（LLM）智能体在面对需要多步骤推理、调用多个工具或处理多个专业领域的任务时，显得力不从心？要么是上下文窗口迅速被填满，要么是工具调用决策混乱，最终导致任务失败或结果质量低下。这正是多智能体（Multi-Agent）系统要解决的核心问题。

本文将为你带来一份从零到一的AI Agent智能体保姆级实战教程。我们将以当前最流行的LangChain和LangGraph框架为核心，结合OpenClaw等工具，手把手教你搭建一个可运行、可扩展的多智能体协作系统。无论你是想入门AI应用开发，还是希望将现有单智能体项目升级为更强大的多智能体架构，这篇文章都将提供完整的代码示例、清晰的架构解析和避坑指南。

1. 背景与核心概念：为什么需要多智能体？

在深入代码之前，我们首先要理解多智能体系统（Multi-Agent System, MAS）的价值和核心思想。

1.1 什么是AI智能体（Agent）？

简单来说，一个AI智能体是一个能够感知环境、进行决策并执行动作以实现特定目标的系统。在LLM应用开发中，智能体通常指一个由大语言模型驱动的程序，它可以根据用户输入、上下文信息和可用工具（如搜索、计算、数据库查询）来决定下一步做什么。传统的ReAct（Reasoning + Acting）模式就是单智能体的典型代表。

然而，随着任务复杂度的提升，单智能体架构暴露出诸多局限性：

1. 工具过载 ：当智能体拥有数十个甚至上百个工具时，LLM在决定调用哪个工具时容易做出错误决策。
2. 上下文爆炸 ：长对话历史、中间思考步骤、工具调用结果全部塞进上下文，很快会触及模型token限制。
3. 缺乏专业化 ：一个“通才”智能体很难同时在代码生成、数学计算、文本总结等多个领域都表现出色。

1.2 多智能体系统的优势

多智能体系统通过将复杂任务分解，交由多个专业化、模块化的智能体协作完成，从而有效应对上述挑战。其核心优势在于：

• 模块化 ：每个智能体职责单一，易于开发、测试、维护和替换。
• 专业化 ：可以训练或提示（Prompt）不同的智能体成为特定领域的专家（如“代码专家”、“数据分析师”、“文案写手”），提升整体任务完成质量。
• 可控性 ：开发者可以显式地设计智能体之间的通信协议和控制流，而不是完全依赖LLM的函数调用，使系统行为更可预测、更可靠。

1.3 核心框架：LangChain 与 LangGraph

• LangChain ：一个用于开发由LLM驱动的应用程序的框架。它提供了连接LLM、数据源（如向量数据库）和工具（如搜索引擎、API）的标准化接口，是构建智能体的基石。
• LangGraph ：构建在LangChain之上的库，专门用于创建有状态、多步骤的应用程序，其核心抽象是 图（Graph） 。在LangGraph中，智能体被建模为图的 节点（Node） ，节点之间的交互和状态流转被定义为 边（Edge） 。这使其成为构建复杂多智能体工作流的理想选择。

两者关系 ：你可以把LangChain看作是提供了“砖块”（模型、工具、记忆等），而LangGraph提供了将这些“砖块”组装成复杂“建筑”（工作流）的蓝图和脚手架。本文的实战将主要基于LangGraph来编排多智能体。

1.4 什么是OpenClaw？

OpenClaw（开源爪）是一个由火山引擎开源的AI智能体开发框架与平台。它提供了一套完整的工具链和技能（Skill）市场，旨在降低AI智能体开发的门槛。在本文的语境中，我们可以将OpenClaw视为一个 强大的工具和技能库 ，其提供的技能（如网页搜索、文件处理、代码执行等）可以被我们的LangGraph多智能体系统所调用。后续实战中，我们会演示如何将其集成。

2. 环境准备与依赖安装

工欲善其事，必先利其器。开始编码前，请确保你的开发环境已就绪。

2.1 基础环境要求

• Python : 3.8 或更高版本。推荐使用 3.9+ 以获得更好的兼容性。
• 包管理工具 : pip 或 conda 。
• 代码编辑器 : VS Code, PyCharm 等任选。
• LLM API Key : 你需要一个支持工具调用（Function Calling）的LLM服务API Key，例如：
  • OpenAI API Key (推荐，兼容性最好)
  • 通义千问 、 DeepSeek 、 智谱AI 等国内主流模型的API Key。

2.2 创建虚拟环境与安装依赖

强烈建议使用虚拟环境来管理项目依赖，避免包冲突。

# 1. 创建并进入项目目录
mkdir multi-agent-tutorial && cd multi-agent-tutorial

# 2. 创建Python虚拟环境 (以venv为例)
python -m venv venv

# 3. 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 4. 安装核心依赖
pip install langchain langchain-openai langgraph

# 5. 安装可选依赖（用于示例中的工具）
pip install duckduckgo-search  # 用于网络搜索
# pip install openclaw-sdk  # 如果使用OpenClaw SDK，请根据其官方文档安装

2.3 设置API密钥

在项目根目录创建一个 .env 文件来安全地存储你的API密钥，并使用 python-dotenv 加载。

pip install python-dotenv

.env 文件内容：

OPENAI_API_KEY=sk-your-openai-api-key-here
# 其他模型的API_KEY，如需要
# DASHSCOPE_API_KEY=your-dashscope-key
# ZHIPUAI_API_KEY=your-zhipuai-key

在代码中加载环境变量：

# config.py
import os
from dotenv import load_dotenv

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
# 确保密钥已设置
if not OPENAI_API_KEY:
    raise ValueError("请在 .env 文件中设置 OPENAI_API_KEY")

3. LangGraph核心概念与多智能体架构拆解

在动手搭建之前，我们必须深入理解LangGraph的几个核心概念，这是构建任何工作流的基础。

3.1 状态（State）

状态是LangGraph工作流的“记忆”。它是一个字典（或Pydantic模型），在图的各个节点间传递和更新。对于多智能体系统，状态通常包含所有智能体需要共享的信息，最常见的是消息列表。

from typing import Annotated, List
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
    """定义多智能体系统的共享状态"""
    # 消息历史，所有智能体都读写这个列表
    messages: Annotated[List, add_messages]
    # 其他共享信息，例如当前任务描述、中间结果等
    task: str
    final_answer: str

add_messages 是一个归约函数，它能智能地将新旧消息列表合并，是处理对话历史的推荐方式。

3.2 节点（Node）与边（Edge）

• 节点 ：代表工作流中的一个步骤或一个计算单元。在 多智能体系统 中， 每个智能体通常被实现为一个节点 。节点函数接收当前状态，执行操作（如调用LLM、运行工具），并返回更新后的状态。
• 边 ：定义了节点之间的流转逻辑。分为两种：
  • 条件边（Conditional Edge） ：根据节点返回的结果或状态中的某个值，动态决定下一个要执行的节点。这是实现智能体间“移交”（Handoff）的关键。
  • 普通边（Fixed Edge） ：始终指向同一个下一个节点。

3.3 图（Graph）与编译

将定义好的节点和边组装起来，就形成了一个 StateGraph 。调用 compile() 方