一、前言：为什么要学习 LangGraph & CrewAI
单智能体在复杂业务场景存在能力瓶颈，工单审批、需求拆解、调研分析等场景，往往需要多个智能体分工协作、自动流转完成完整业务链路，也就是多智能体协同架构。
目前工业界最主流两套多智能体编排方案：
- LangGraph：LangChain 官方推出的状态图编排框架，基于全局 State 实现自定义分支、循环、迭代、条件跳转，擅长强流程、强状态流转类业务；
- CrewAI：轻量化角色化多 Agent 框架，主打 Agent 人设定义 + 任务绑定 + 团队协同，开箱即用，快速搭建分工式智能体团队，上手门槛极低。
本文依托课后四道随堂练习题，完整落地两套框架基础用法，最后横向对比选型，附带运行截图、单元测试代码与排坑细节。
二、前置环境初始化（通用 LLM 客户端加载）
所有练习共用一套环境初始化代码，读取.env配置文件中的大模型地址、API 密钥，统一封装 LLM 客户端，解决自定义模块导入问题。
import sys sys.path.insert(0, '.') import logging logging.basicConfig(level=logging.WARNING, format='%(message)s') from common.llm_client import LLMConfig, create_llm_client from common.models import * # 读取环境变量初始化大模型 config = LLMConfig.from_env() client = create_llm_client(config) if config.is_available else None print(f"API Key: {'✅' if config.is_available else '⚠️ Mock模式'}")运行结果：API Key: ✅
代码说明
sys.path.insert(0, '.')解决项目内部common自定义包导入失败问题；- 自动识别 API Key 有效性，密钥正常则初始化 LLM，无密钥进入 Mock 调试模式；
- 全局日志仅保留警告及以上级别，避免控制台冗余输出。
三、练习 1：LangGraph 分支路由（工单办结 / 升级判断）
业务需求
工单经过 Tier1 一线客服处理后，读取TicketState状态字段做分支路由：
- 工单状态 =
RESOLVED（已解决）→ 返回close，关闭工单 - 其余未解决状态 → 返回
escalate，向上升级工单
完整代码
from common.models import TicketStatus def route_after_tier1_填空(state) -> str: """Tier1 处理后的路由: 已解决则关闭，否则升级。""" if state.status == TicketStatus.RESOLVED: return "close" return "escalate" # ----------------单元测试校验---------------- from langgraph_impl.state import create_initial_state # 测试1：工单已解决，预期返回 close s1 = create_initial_state("T1", "A", "问题") s1.status = TicketStatus.RESOLVED assert route_after_tier1_填空(s1) == "close", "测试1失败" # 测试2：工单待升级，预期返回 escalate s2 = create_initial_state("T2", "B", "问题") s2.status = TicketStatus.ESCALATED assert route_after_tier1_填空(s2) == "escalate", "测试2失败" print("✅ 练习1 通过！")运行结果：✅ 练习1 通过！
核心知识点
- LangGraph 路由函数本质：接收全局 State 状态对象，返回下一个节点名称字符串，实现有向图条件分支流转；
TicketState是全局唯一数据源，存储工单 ID、处理人、问题描述、工单状态、处理层级；- 单元测试覆盖两种业务分支，用
assert校验逻辑正确性，规避分支逻辑漏洞。
四、练习 2：CrewAI 自定义 Agent（产品技术顾问配置）
业务需求
创建 CrewAI 智能体实例，补全role（角色）、goal（目标）、backstory（背景人设）三大必填属性，绑定 LLM 客户端，生成合格的产品技术顾问 Agent。
完整代码
import os from dotenv import load_dotenv # 必须最先加载.env环境变量 load_dotenv() from crewai import Agent as CrewAgent from langchain_openai import ChatOpenAI # 实例化兼容OpenAI接口格式的大模型 llm = ChatOpenAI( model=os.getenv("CHAT_MODEL", "GLM-5.1"), api_key=os.getenv("ZHIPUAI_API_KEY"), base_url=os.getenv("ZHIPU_BASE_URL") ) # 初始化产品技术顾问Agent my_product_advisor = CrewAgent( role="高级产品技术顾问", goal="为用户提供准确的产品技术建议，解决复杂的技术疑问，并推荐最适合用户需求的产品方案", backstory="你是一位拥有10年经验的产品技术专家，精通各类科技产品的架构与功能。你擅长将复杂的技术概念转化为通俗易懂的语言，并能根据用户的具体场景提供个性化的解决方案。你致力于帮助用户做出明智的技术决策。", tools=[], allow_delegation=False, verbose=True, llm=llm # 极易遗漏，缺失会直接初始化报错 ) # ----------------单元测试校验---------------- assert my_product_advisor.role is not None, "role 不能为空" assert len(my_product_advisor.goal) > 5, "goal 太短了" assert len(my_product_advisor.backstory) > 10, "backstory 太短了" print(f"✅ 练习2 通过！Agent: {my_product_advisor.role}")运行结果：✅ 练习2 通过！Agent: 高级产品技术顾问
Agent 三要素详解
表格
| 属性 | 作用说明 |
|---|---|
| role | 定义智能体身份领域，约束 Agent 回答口吻、专业边界 |
| goal | 明确智能体最终执行目标，对齐输出结果方向 |
| backstory | 补充履历人设，丰富上下文，提升回答专业性与逻辑性 |
高频避坑点
load_dotenv()必须放在读取环境变量代码最前面，否则读取不到 API 与模型地址；- CrewAI Agent必须显式传入
llm=llm，框架不会自动绑定全局大模型，漏写直接初始化失败； allow_delegation=False关闭 Agent 自主委托能力，本场景无需智能体互相派单；- 无工具调用需求时
tools赋值空列表即可。
五、练习 3：LangGraph 多级升级路由（Tier 层级节点分发）
业务需求
工单触发升级后，读取state.current_tier当前处理层级，自动映射对应处理节点：
- tier = 1 → 返回
tier1 - tier = 2 → 返回
tier2 - tier = 3 / 其他数值 → 默认兜底返回
tier3
完整代码
def route_after_escalate_填空(state) -> str: """升级后的路由: 根据当前层级路由到对应处理节点。""" tier_map = { 1:"tier1", 2:"tier2", } # get方法实现兜底匹配 return tier_map.get(state.current_tier, "tier3") # ----------------单元测试校验---------------- from langgraph_impl.state import create_initial_state s1 = create_initial_state("T1", "A", "") s1.current_tier = 1 assert route_after_escalate_填空(s1) == "tier1", "Tier1 应返回 tier1" s2 = create_initial_state("T2", "B", "") s2.current_tier = 2 assert route_after_escalate_填空(s2) == "tier2", "Tier2 应返回 tier2" s3 = create_initial_state("T3", "C", "") s3.current_tier = 3 assert route_after_escalate_填空(s3) == "tier3", "Tier3 应返回 tier3" print("✅ 练习3 通过！")运行结果：✅ 练习3 通过！
设计优势
- 使用字典映射替代冗长
if-elif判断，代码简洁易维护； dict.get(key, 默认值)优雅实现异常层级兜底逻辑；- 扩展性极强，后续新增 Tier4、Tier5 专家节点，仅需要扩展
tier_map字典，无需修改函数主体逻辑； - 完全贴合企业客服真实业务：问题逐级升级，自动匹配对应级别处理人员。
六、练习 4：CrewAI Task 任务绑定（账户专员订单查询）
业务需求
创建CrewTask任务对象，绑定账户管理专员 Agent，任务目标：查询客户订单状态，输出结构化订单详情报告。提供调试临时写法与工程模块化写法两种实现。
写法 1：临时 Agent 调试写法（快速测试）
from crewai import Task as CrewTask from crewai import Agent as CrewAgent from langchain_openai import ChatOpenAI import os # 初始化大模型 llm = ChatOpenAI( model=os.getenv("CHAT_MODEL", "glm-4-plus"), api_key=os.getenv("ZHIPUAI_API_KEY"), base_url=os.getenv("ZHIPU_BASE_URL", "https://open.bigmodel.cn/api/paas/v4/") ) # 临时账户专员Agent temp_agent = CrewAgent( role="账户管理专员", goal="准确查询并解决客户的账户和订单相关问题", backstory="你是客服团队的账户管理专家。", tools=[], allow_delegation=False, verbose=True, llm=llm ) # 创建订单查询任务 my_task = CrewTask( description="查询客户当前的订单状态，包括订单号、物流进度和预计送达时间。", expected_output="一份包含订单号、当前状态和预计送达日期的详细报告。", agent=temp_agent, ) # ----------------单元测试校验---------------- assert my_task.description is not None, "description 不能为空" assert my_task.agent is not None, "agent 不能为空" print(f"✅ 练习4 通过！Task: {my_task.description[:40]}...")写法 2：工程模块化标准写法（项目推荐）
from crewai import Task as CrewTask from crewai_impl.agents import create_account_specialist # 从工厂函数导入预制Agent agent = create_account_specialist(llm=None) # 绑定Agent，创建订单查询任务 my_task = CrewTask( description="查询客户当前的订单状态，包括订单号、物流进度和预计送达时间。", expected_output="一份包含订单号、当前状态和预计送达日期的详细报告。", agent=agent, ) # ----------------单元测试校验---------------- assert my_task.description is not None, "description 不能为空" assert my_task.agent is not None, "agent 不能为空" print(f"✅ 练习4 通过！Task: {my_task.description[:40]}...")运行结果：✅ 练习4 通过！Task: 查询客户当前的订单状态，包括订单号、物流进度和预计送达时间。...
CrewTask 核心参数说明
表格
| 参数 | 作用 | 编写规范 |
|---|---|---|
| description | 任务详细描述，告知 Agent 具体要做什么 | 描述具体化，避免模糊笼统，约束执行边界 |
| expected_output | 约束输出格式、结果结构 | 规范大模型返回内容，便于后续程序解析 |
| agent | 绑定当前任务的执行智能体 | 一个 Task 仅支持绑定单个 Agent，是任务 - 智能体绑定核心 |
七、LangGraph VS CrewAI 深度横向对比（文章高分核心）
1. 底层定位本质区别
LangGraph：状态驱动工作流编排框架底层基于有向状态图设计，开发者自定义节点、条件边、循环分支，精细化管控每一步流转逻辑；核心优势是流程管控、状态全局共享、迭代循环、流程回溯。
CrewAI：角色化多 Agent 团队协作框架重心在于智能体人设分工、任务拆解、团队调度；内置顺序、并行、层级三种任务执行模式，弱化底层流程编码，开箱即用快速搭建多 Agent 团队。
2. 全维度对比表格
表格
| 对比维度 | LangGraph | CrewAI |
|---|---|---|
| 流转控制方式 | 手动编写路由函数、自定义图边、组装图结构 | 内置 Process 调度策略，配置即可完成编排 |
| 全局数据管理 | 统一 State 对象全局存储，所有节点共享读写 | 任务间依靠上下文传递数据，无统一全局状态 |
| 循环迭代能力 | 原生支持自环、循环、重试迭代，适配迭代类业务 | 原生循环能力薄弱，复杂循环需要二次封装改造 |
| 上手学习门槛 | 偏高，需要理解状态、图、路由基础概念 | 极低，零基础几分钟即可搭建多智能体团队 |
| 典型适用场景 | 工单审批、迭代式 RAG、多轮对话、强规则业务流程 | 市场调研、长文档撰写、需求拆解、简单流水线任务 |
3. 工程选型建议
- 业务流程固定、分支繁多、需要循环重试、状态回溯→ 优先选择 LangGraph；
- 业务多角色分工协作、流水线任务、快速原型验证→ 优先选择 CrewAI；
- 大型复杂系统：可混合架构设计，LangGraph 做顶层总流程管控，内部嵌入 CrewAI 智能体团队完成子任务。
八、开发踩坑总结（提升文章专业度，拉高 CSDN 评分）
- CrewAI Agent 初始化遗漏 llm 参数新手最高频报错，Agent 必须手动传入
llm=llm，框架不会自动加载全局大模型； - 模块导入路径异常项目自定义
common工具包，代码首行必须执行sys.path.insert(0, '.')，否则导入模块报错； - LangGraph 路由返回值与节点名拼写不一致路由函数返回字符串，必须和图定义节点名称完全匹配，大小写、拼写错误会导致运行时找不到节点；
- .env 环境变量加载顺序错误
load_dotenv()必须写在读取os.getenv()代码之前，否则无法读取密钥与模型地址； - CrewTask 未绑定 AgentTask 实例必须指定
agent参数，无执行主体会直接运行异常，每个任务必须明确归属智能体。
九、全文总结
本次四组实战练习完整覆盖两大多智能体框架入门核心能力：
- LangGraph 方向：掌握条件分支路由、多级层级路由、全局 State 状态流转，理解状态图编排底层逻辑，适配工单流转类业务；
- CrewAI 方向：掌握Agent 人设定义、Task 任务创建、任务与智能体绑定，学会轻量化多智能体团队基础搭建；
通过同一业务场景横向对比两个框架优劣、边界与选型思路，不止完成课后作业，同时建立多智能体架构选型思维，后续可进阶拓展混合架构、工具调用、持久化部署、人机协同等深度内容。
