很多朋友在做 AI 应用时一开始都是从单个 Agent 聊起的比如让它写文案、做翻译、总结文档。但一旦涉及真实业务场景比如一场婚礼的策划需要协调场地、预算、宾客、创意、摄影等多个方面单个 Agent 就会手忙脚乱。这时候多智能体Multi-Agent的协作价值就体现出来了。本文将基于一个“中配”实战项目使用 LangChain LangGraph 构建多智能体婚礼策划系统并用 Streamlit 快速搭建一个可视化交互界面。这不是一个简单的 Demo而是一个具备清晰分工、状态流转、人机协作的完整工程案例。文章会覆盖LangChain 与 LangGraph 的关系、多智能体架构设计、四大策划 Agent 的完整实现、Streamlit 前端的对接、常见报错与排查思路、生产环境落地的工程建议。无论你是 AI 应用开发者还是想入门 LangChain 多智能体的学习者这篇文章都可以作为一份较为完整的实战参考。运行环境Python 3.10 以上均可代码在 Windows / macOS / Linux 下兼容。1. 项目背景婚礼策划为什么需要多智能体1.1 一个 Agent 的局限先来看一个常见场景。假设你让一个 Agent 帮用户策划婚礼你会让它做什么从外部看它内部其实只有一套系统提示词System Prompt和一组工具。它既要处理预算计算又要设计主题风格还要协调供应商时间甚至还要负责给宾客排座位。输出质量通常有三个问题上下文太长导致遗忘前面的决策被后面的工具调用覆盖掉用户问“刚才定的主题色是什么”Agent 已经想不起来。工具权限混乱预算 Agent 能调用供应商库创意 Agent 能修改预算表职责边界不清晰容易产生幻觉或误操作。无法并行思考真实策划场景中预算、场地、摄影、菜单需要并行调研和计算单个 Agent 只能串行完成速度慢且产出效率低。1.2 婚礼策划的本质是多人协作我们把真实婚礼策划师的工作方式拆开看会发现这从来不是一个人干的活。一个成熟的婚礼策划团队通常包含婚礼策划师总控全局制定主题和整体进度预算管理师分配预算控制每一项支出场地与供应商专员负责酒店、摄影、花艺、甜品、音乐等资源宾客关系专员统计人数、座位安排、接送和住宿安排。多智能体系统本质上就是把这个团队搬进代码里。每个 Agent 只负责一件事它们通过共享状态State进行信息传递由一个协调者Router 或 Supervisor决定下一步让谁执行最终汇总成一份完整的婚礼策划案。1.3 LangGraph比 LangChain 更适合多智能体编排LangChain 是当前非常流行的 LLM 应用开发框架它提供了模型封装、Prompt 管理、工具调用、RAG 等基础能力。而 LangGraph 是 LangChain 团队推出的低层级编排框架专门用于构建有状态、可循环、可控制的 Agent 图。两者关系可以用一句话概括LangChain 提供“零件”LangGraph 负责把“零件”组装成一条可以无限循环、有记忆、有条件跳转的生产线。在多智能体项目中我们需要的不只是“调用一次 LLM 返回结果”而是多个 Agent 之间可以多次跳转每个 Agent 都能读取全局状态支持条件判断例如预算不足时自动切换到“预算预警”逻辑支持人工确认节点比如最终方案输出前允许用户调整。这些能力如果自己手写状态机非常麻烦而 LangGraph 的StateGraph几乎是为此设计的。2. 系统架构设计2.1 整体架构图在正式开始编码前我们先梳理整体架构。系统主要包括 5 个模块用户输入Streamlit 页面 ↓ LangGraph 编排层 ├── 1. Router 意图分发节点 ├── 2. 需求分析 Agent需求拆解 ├── 3. 预算规划 Agent预算分配与预警 ├── 4. 资源推荐 Agent场地/摄影/花艺等 ├── 5. 创意策划 Agent主题、流程、细节 └── 6. 最终方案汇总节点 ↓ Streamlit 状态显示 / 结果输出2.2 状态设计LangGraph 多智能体协同的核心是定义好全局状态State。状态相当于各个 Agent 之间的共享便签本每个 Agent 都可以读取它并根据职责更新其中一部分字段。这里我们需要维护的数据包括字段类型说明user_inputstr用户原始输入requirementstr需求分析 Agent 输出的结构化需求budget_planstr预算规划 Agent 输出的预算分配resource_planstr资源推荐 Agent 输出的供应商与场地方案creative_planstr创意策划 Agent 输出的婚礼主题和流程final_planstr汇总后的完整方案messageslist对话历史记录current_rolestr当前正在执行的 Agent 角色通过这种状态设计各个 Agent 之间不需要“商量”只需要向 State 中写入自己的产出下一个 Agent 就能读到上一个模块的结果。2.3 任务流转逻辑多智能体不是简单的一堆 Agent 顺序执行。我们用 LangGraph 的任务流如下用户输入需求后Router 节点判断是否已完整收集关键信息如果缺少关键信息Router 直接返回要求用户补充信息完整后需求分析 Agent先执行输出结构化的婚礼需求随后预算规划 Agent根据需求做预算拆分接着资源推荐 Agent结合预算和需求推荐供应商与场地最后创意策划 Agent吸收前面所有信息生成完整的婚礼方案所有 Agent 完成后进入最终汇总节点输出 Markdown 格式策划案。在第 6 步结束后我们还设计了一个“人工确认”入口让用户在 Streamlit 界面上对提案进行修改或确认这体现了真实业务中的人机协同思想。3. 环境准备与依赖安装3.1 创建虚拟环境建议使用虚拟环境隔离项目依赖避免污染全局 Python 环境。python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate3.2 安装依赖本文使用 LangChain 0.3.x 版本进行演示并以langgraph作为编排核心streamlit作为界面层。pip install -U langchain langchain-openai langgraph streamlit python-dotenv如果国内网络环境不稳定可以加上国内镜像源比如pip install -U langchain langchain-openai langgraph streamlit python-dotenv -i https://pypi.tuna.tsinghua.edu.cn/simple3.3 配置环境变量在项目根目录创建.env文件OPENAI_API_KEY你的_KEY OPENAI_API_BASEhttps://api.openai.com/v1 # 如果使用代理/中转改成对应地址注意生产环境不要将密钥硬编码在代码中也不要上传到 Git 仓库。3.4 验证环境安装完成后可以运行下面的 Python 代码验证环境是否正常from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini, temperature0.7) resp llm.invoke(请回复环境正常) print(resp.content)如果输出了内容说明 LangChain 与模型 API 已经打通。4. LangChain 多智能体核心代码实现这一节是文章的重点。我们将按照模块逐一实现。4.1 定义全局状态和 LLM创建state.pyfrom typing import TypedDict, Annotated, List class WeddingState(TypedDict): user_input: str requirement: str budget_plan: str resource_plan: str creative_plan: str final_plan: str messages: Annotated[List[str], operator.add] current_role: str再创建llm.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() def get_llm(temperature: float 0.7): return ChatOpenAI( modelgpt-4o-mini, temperaturetemperature, api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE) )4.2 编写需求分析 Agent这个 Agent 负责将用户自由输入的自然语言需求转化为结构化的婚礼需求描述方便后续模块读取。创建agents/requirement_agent.pyfrom langchain_core.prompts import ChatPromptTemplate REQUIREMENT_PROMPT ChatPromptTemplate.from_messages([ (system, 你是一位资深的婚礼需求分析师。 你的任务是从用户的描述中提取关键信息并整理为结构化需求。 必须包含以下字段如果没有提到就标注需要确认 - 婚礼日期 - 宾客人数 - 婚礼风格偏好如中式、西式、户外、极简等 - 预算范围 - 特殊要求如宠物观礼、无障碍设施、宗教仪式等 - 地点偏好 ), (human, 用户需求{user_input}) ]) def create_requirement_agent(llm): chain REQUIREMENT_PROMPT | llm return chain4.3 编写预算规划 Agent预算规划 Agent 需要根据需求分析结果分配预算并标记每一项的上限。创建agents/budget_agent.pyBUDGET_PROMPT ChatPromptTemplate.from_messages([ (system, 你是一位婚礼预算管理师。请根据需求分析结果输出分项预算表。 格式要求 ### 总预算 ### 分项预算 | 项目 | 预算金额 | 说明 | | --- | --- | --- | 建议包含项目场地、餐饮、摄影摄像、婚礼策划、服装、花艺、甜品台、音乐、宾客礼品、应急备用金。 注意所有分项之和不要超过总预算若不够需提出优先级建议。 ), (human, 需求分析结果{requirement}) ]) def create_budget_agent(llm): chain BUDGET_PROMPT | llm return chain4.4 编写资源推荐 Agent资源推荐 Agent 不访问真实外部数据库它基于自己的“知识”和预算、需求生成假想的资源推荐清单。生产环境可以在这里挂载真实的供应商数据库工具Tool。创建agents/resource_agent.pyRESOURCE_PROMPT ChatPromptTemplate.from_messages([ (system, 你是一位婚礼资源整合专家。 请根据需求分析和预算规划推荐合适的资源方案包括 - 场地3个候选说明优势与适合场景 - 摄影团队2-3个候选 - 花艺布置2个方向 - 甜品或餐饮建议 - 应急备选方案 所有推荐必须符合预算范围超预算时要说明原因。 ), (human, 需求分析{requirement}\n预算规划{budget_plan}) ]) def create_resource_agent(llm): chain RESOURCE_PROMPT | llm return chain4.5 编写创意策划 Agent创意策划 Agent 承担“总导演”角色它综合前面所有模块信息写出一份有创意的完整婚礼策划案。创建agents/creative_agent.pyCREATIVE_PROMPT ChatPromptTemplate.from_messages([ (system, 你是一位顶级的婚礼策划师。请综合需求、预算、资源三方面信息输出一份完整的婚礼策划案。 策划案需包含 1. 婚礼主题与设计理念 2. 仪式流程时间线 3. 场地布置要点 4. 宾客体验亮点 5. 摄影与音乐氛围建议 6. 备选方案 7. 预算执行说明 请使用 Markdown 格式输出内容要具体、可落地避免空话套话。 ), (human, 需求分析{requirement}\n预算规划{budget_plan}\n资源推荐{resource_plan}) ]) def create_creative_agent(llm): chain CREATIVE_PROMPT | llm return chain4.6 组装 LangGraph 状态图现在我们进入最核心的部分使用StateGraph把这些 Agent 编排起来。创建graph.pyimport operator from typing import Annotated, TypedDict, List from langgraph.graph import StateGraph, END from langgraph.checkpoint.memory import MemorySaver # 允许 messages 累加 class WeddingState(TypedDict): user_input: str requirement: str budget_plan: str resource_plan: str creative_plan: str final_plan: str messages: Annotated[List[str], operator.add] async def requirement_node(state: WeddingState): from agents.requirement_agent import create_requirement_agent chain create_requirement_agent(get_llm()) result await chain.ainvoke({user_input: state[user_input]}) return {requirement: result.content, messages: [需求分析完成]} async def budget_node(state: WeddingState): from agents.budget_agent import create_budget_agent chain create_budget_agent(get_llm()) result await chain.ainvoke({ requirement: state.get(requirement, ) }) return {budget_plan: result.content, messages: [预算规划完成]} async def resource_node(state: WeddingState): from agents.resource_agent import create_resource_agent chain create_resource_agent(get_llm()) result await chain.ainvoke({ requirement: state.get(requirement, ), budget_plan: state.get(budget_plan, ) }) return {resource_plan: result.content, messages: [资源推荐完成]} async def creative_node(state: WeddingState): from agents.creative_agent import create_creative_agent chain create_creative_agent(get_llm()) result await chain.ainvoke({ requirement: state.get(requirement, ), budget_plan: state.get(budget_plan, ), resource_plan: state.get(resource_plan, ) }) return {creative_plan: result.content, messages: [创意策划完成]} async def final_node(state: WeddingState): final f ## 婚礼策划最终方案 ### 需求分析 {state.get(requirement,)} ### 预算规划 {state.get(budget_plan,)} ### 资源推荐 {state.get(resource_plan,)} ### 创意策划 {state.get(creative_plan,)} return {final_plan: final, messages: [最终方案生成]} def build_graph(): workflow StateGraph(WeddingState) workflow.add_node(requirement, requirement_node) workflow.add_node(budget, budget_node) workflow.add_node(resource, resource_node) workflow.add_node(creative, creative_node) workflow.add_node(final, final_node) workflow.set_entry_point(requirement) workflow.add_edge(requirement, budget) workflow.add_edge(budget, resource) workflow.add_edge(resource, creative) workflow.add_edge(creative, final) workflow.add_edge(final, END) # MemorySaver 用于保存状态与对话记录 memory MemorySaver() app workflow.compile(checkpointermemory) return app4.7 添加意图路由与人工确认节点如果用户输入的信息不完整直接进入需求分析 Agent 可能会产出大量“待确认”。我们可以在入口加入一个路由节点先判断是否进入正式策划流程还是需要向用户提问。创建graph_router.pyfrom langchain_core.prompts import ChatPromptTemplate ROUTER_PROMPT ChatPromptTemplate.from_messages([ (system, 你是婚礼策划系统的判断节点。请判断用户输入中是否包含以下关键信息 - 婚礼日期 - 宾客人数 - 预算范围 - 风格偏好 如果四项都有只回复 VALID否则回复 NEED_INFO并列出缺失项。 ), (human, 用户输入{user_input}) ]) def should_continue(state): result state.get(requirement, ) if 待确认 in result or 未知 in result: return need_user_feedback return budget实际项目中更加健壮的做法是让路由节点调用 LLM 判断然后返回VALID或NEED_INFO。这里我们简化处理将“待确认”关键词作为判断依据。为了让流程更完整我们在 StateGraph 中加入一个human_feedback节点用于暂停执行并等待 Streamlit 前端补充信息。5. 基于 Streamlit 构建交互前端5.1 页面整体布局Streamlit 是 Python 生态中非常便捷的 AI 应用 UI 框架。我们用它做三个页面区域侧边栏输入本次婚礼的用户需求主区域展示需求分析、预算、资源、创意四个 Agent 的处理过程状态区显示当前执行节点和中间产物。创建app.pyimport streamlit as st from graph import build_graph st.set_page_config(page_title多智能体婚礼策划师, layoutwide) st.title( 多智能体婚礼策划师) st.caption(基于 LangChain LangGraph Streamlit 的多智能体协作实战项目) # 初始化会话状态 if app not in st.session_state: st.session_state.app build_graph() if thread_id not in st.session_state: st.session_state.thread_id wedding-001 # 侧边栏输入 with st.sidebar: st.header(用户需求输入) user_input st.text_area( 请输入你的婚礼需求, value计划明年5月20日在杭州举办户外婚礼宾客约80人预算15万元喜欢极简风格希望有草坪仪式和晚宴。, height150 ) run_btn st.button(开始策划, typeprimary) # 主区域 if run_btn: config {configurable: {thread_id: st.session_state.thread_id}} final_state st.session_state.app.invoke( {user_input: user_input, messages: []}, configconfig ) st.session_state.final_state final_state if final_state in st.session_state: state st.session_state.final_state tabs st.tabs([需求分析, 预算规划, 资源推荐, 创意策划, 最终方案]) with tabs[0]: st.markdown(state.get(requirement, )) with tabs[1]: st.markdown(state.get(budget_plan, )) with tabs[2]: st.markdown(state.get(resource_plan, )) with tabs[3]: st.markdown(state.get(creative_plan, )) with tabs[4]: st.markdown(state.get(final_plan, ))运行应用streamlit run app.py浏览器会自动打开http://localhost:8501。5.2 增加执行过程展示为了更直观地展示多智能体之间的协作我们可以把每一步的状态更新“流式”展示出来。Streamlit 支持st.status容器适合展示多步执行过程。改造核心执行部分if run_btn: config {configurable: {thread_id: st.session_state.thread_id}} # 逐节点执行并展示进度 with st.status(多智能体协作中..., expandedTrue) as status: from graph import build_graph app st.session_state.app # 利用 invoke 的 stream_modeupdates 逐步获取节点输出 for step in app.stream( {user_input: user_input, messages: []}, configconfig, stream_modevalues ): # step 是完整的 state 快照 if step.get(requirement): st.write(✅ 需求分析完成) with st.expander(查看需求分析产物): st.markdown(step[requirement]) if step.get(budget_plan): st.write(✅ 预算规划完成) with st.expander(查看预算规划产物): st.markdown(step[budget_plan]) if step.get(resource_plan): st.write(✅ 资源推荐完成) with st.expander(查看资源推荐产物): st.markdown(step[resource_plan]) if step.get(creative_plan): st.write(✅ 创意策划完成) with st.expander(查看创意策划产物): st.markdown(step[creative_plan]) status.update(label多智能体协作完成!, statecomplete)这样用户可以在页面上清晰地看到“需求分析 → 预算规划 → 资源推荐 → 创意策划”依次完成的过程体验上更像真实的多智能体协作系统。6. 运行与验证6.1 完整运行流程在项目根目录执行streamlit run app.py打开浏览器后在侧边栏输入计划明年5月20日在杭州举办户外婚礼宾客约80人预算15万元喜欢极简风格希望有草坪仪式和晚宴。点击“开始策划”页面主区域会依次输出需求分析 Agent输出的结构化工单预算规划 Agent输出的分项预算表资源推荐 Agent输出的场地、摄影、花艺候选清单创意策划 Agent输出的完整婚礼流程和主题方案最终汇总方案。6.2 预期输出示例截取创意策划 Agent 的输出大致如下### 1. 婚礼主题与设计理念 主题推荐「清风与白纱」 以极简风格为主线色彩上以白色、原木色、浅绿色为主呼应户外草坪的自然气息... ### 2. 仪式流程时间线 - 15:00 宾客入场草坪音乐暖场 - 15:30 主持人开场新娘入场 - 16:00 交换戒指与誓言环节 - 16:30 合影与自由交流 - 18:00 晚宴开始实际输出会根据模型、温度参数和输入需求的不同而有所变化但整体结构应该保持一致。7. 常见问题与排查思路在 LangChain 多智能体和 Streamlit 实战中最常见的报错集中在依赖版本、API 调用、状态读取和页面缓存四类。下面整理成表格方便快速检索。问题现象常见原因解决思路ModuleNotFoundError: No module named langgraph未安装 langgraph 或版本过低执行pip install -U langgraph确认安装在当前虚拟环境OpenAIError: The api_key client option must be set没有加载 .env 环境变量在入口文件最前面调用from dotenv import load_dotenv; load_dotenv()TypeError: NoneType object is not subscriptable读取 state 时字段不存在使用state.get(字段, )进行安全读取避免直接下标访问Streamlit 页面点击按钮无反应未正确管理st.session_state确认app.graph是否已缓存在 session_state 中RecursionError: maximum recursion depth exceededLangGraph 边配置成循环且无出口检查 add_edge 是否指向 END或条件边是否正确返回ValueError: Must specify at least one LLMChatOpenAI 初始化参数错误检查 api_key、base_url、model 参数是否正确传入输出中大量出现“待确认”用户输入关键信息不足路由判断不完善在 Router 节点增加结构化信息校验或增加 human_feedback 节点补充一个容易被忽略的问题LangGraph 的多智能体是多轮复用的。如果在 Streamlit 中反复点击“开始策划”同一个thread_id会保存历史状态导致下一次执行可能读取到上一次中间结果。解决方案是为每次新策划生成新的 thread_idimport uuid st.session_state.thread_id str(uuid.uuid4())或者在提交前清空 keyfor key in [requirement, budget_plan, resource_plan, creative_plan, final_plan]: if key in st.session_state: del st.session_state[key]8. 进阶优化与生产落地建议这一节梳理一下如果要把这个项目落地到真实业务或参加竞赛你需要额外关注哪些点。8.1 接入真实工具把资源推荐升级为 RAG 查询当前资源推荐 Agent 只是基于模型知识“编”供应商方案。真实项目中应该接入公司的供应商数据库或知识库此时有两个思路1给 Agent 注册 Tool用tool装饰器实现供应商查询函数然后将 Tool 注入 Agent。from langchain_core.tools import tool tool def search_venue(city: str, budget: float, guests: int) - str: 根据城市、预算和宾客人数查询合适场地 # 这里实际调用数据库或 API return 杭州·西溪艺术酒店户外草坪可容纳100人套餐价6万元含基础布置。2把供应商资料向量化挂载到 RAG 检索器。资源推荐 Agent 先检索知识库再结合检索结果生成方案。这种方式更适合供应商信息经常变化、需要实时更新的场景。8.2 使用 LangGraph 的 Checkpointer 实现多轮对话记忆前面的代码已经使用了MemorySaver它让多智能体系统在多次调用中保留状态。生产环境建议替换为持久化存储比如SqliteSaver、PostgresSaver或 Redis避免服务重启后丢失对话上下文。8.3 加入人工审核节点婚礼策划是决策成本较高的业务。我们不能让 AI 直接替用户做决定更稳妥的方式是每个 Agent 产出方案后允许用户在 Streamlit 页面确认或修改修改结果写回 State后续 Agent 读取新值最终方案输出前增加“人工确认”按钮用户点击确认后才进入最终生成节点。LangGraph 的interrupt_before参数可以实现“暂停在某个节点前”的效果app workflow.compile( checkpointermemory, interrupt_before[human_feedback] )当执行到human_feedback前系统会暂停等待用户输入再调用invoke继续执行。8.4 关注 Token 成本与响应延迟多智能体系统调用次数远高于单 Agent。一个包含 4 个 Agent 的策划流程至少会产生 4 次 LLM 调用加上路由判断和汇总节点往往超过 6 次。建议使用gpt-4o-mini或更便宜的模型处理中间分析任务只有最终创意策划使用强模型比如gpt-4o或claude-sonnet对 Prompt 中的历史消息做“截断”避免太多历史上下文挤占 Token增加结果缓存相同输入需求直接返回历史策划案。8.5 从 LangChain 迁移到 LangGraph 的注意事项不少读者是从 LangChain 的AgentExecutor转过来的。这里需要提醒几个关键差异LangChain Agent 是“工具循环”适合单 Agent 多工具场景LangGraph 是“图状态机”适合多 Agent 多角色编排。LangGraph 的节点函数签名是state - dict返回的 dict 会自动合并到全局状态不要尝试返回整个 state。使用add_edge和add_conditional_edges时要理清是否会产生死循环尤其是条件边必须保证所有分支最终都能到达 END。LangGraph 的调试比 LangChain 困难建议为每个节点添加状态日志字段如messages中追加节点执行记录方便定位问题。9. 总结这篇文章以“婚礼策划”为业务背景完整实现了基于 LangChain、LangGraph 和 Streamlit 的中配多智能体系统。核心内容包括多智能体架构中状态共享与角色分工的设计思路LangGraph 中StateGraph、节点、边、状态流转的核心用法需求分析、预算规划、资源推荐、创意策划四个 Agent 的 Prompt 与代码实现Streamlit 前端如何对接多智能体执行过程并展示各模块中间产物常见报错与生产落地方案的排查清单。下一步你可以尝试在现有框架上添加更多 Agent比如“宾客座位安排 Agent”“天气预警 Agent”“音乐歌单生成 Agent”并将资源推荐模块替换为真实的数据库查询或 RAG 检索进一步提升系统的实用价值。动手实践永远是学习 AI 应用开发的最好方式。把本文代码跑通之后试着改一改每个 Agent 的 Prompt你会发现多智能体系统的行为会发生很有趣的变化这正是 LangChain 生态的魅力所在。