企业官网建设流程全解析

1. 多 Agent 编排到底在解决什么问题

1.1 从单 Agent 到多 Agent 的必然演进

先说结论：单 Agent 能做的事，天花板比大多数人想象的要低得多。我去年帮一个团队做智能客服系统，一开始就是单个 Agent 包打天下——理解用户意图、查知识库、调工单接口、生成回复，全塞在一个提示词里。前两周跑得挺好，到第三周就开始出问题：工具调用越来越不稳定，上下文越来越长，模型开始“忘记”自己该干什么。最典型的一个 bug 是，用户问“帮我查一下上个月的订单”，Agent 居然去调了退款接口。

这不是模型不行，而是单 Agent 的认知负荷过载了。一个 Agent 同时承担意图识别、任务规划、工具选择、结果校验、回复生成五个角色，就像让一个人同时当产品经理、程序员、测试和运维，短期能扛，长期必崩。

多 Agent 编排的核心思路就是分而治之：把一个大任务拆成若干子任务，每个子任务交给专门的 Agent 处理，Agent 之间通过明确的协议传递信息和状态。这跟微服务架构的思路是一脉相承的——单体应用拆成微服务，每个服务只干一件事，通过 API 通信。

1.2 编排和“堆 Agent”是两回事

很多人一听多 Agent，第一反应是“那我多开几个 Agent 不就行了”。我见过一个项目，开发者开了 8 个 Agent，结果比单 Agent 还慢还乱。问题出在没有编排。

编排（Orchestration）这个词来自工作流领域，核心含义是定义谁在什么时候做什么、做完之后交给谁。没有编排的多 Agent 就是一群无头苍蝇，各自为战，互相等待，甚至死锁。

一个合格的多 Agent 编排系统至少要解决四个问题：

• 任务分解：大任务怎么拆成子任务，拆到什么粒度
• 角色分配：每个子任务交给哪个 Agent，Agent 的能力边界在哪
• 状态传递：Agent 之间怎么传数据，传什么格式，传多少
• 流程控制：串行还是并行，失败了怎么重试，超时了怎么降级

这四个问题不解决，Agent 越多越乱。下面这张表是我总结的单 Agent 和多 Agent 的适用边界，你可以对照自己的场景判断：

1.3 为什么现在谈多 Agent 编排正当时

两年前谈多 Agent 编排，大家会觉得是屠龙之术——模型能力不够，工具生态不成熟，编排框架几乎没有。现在情况完全变了。

模型侧，主流大模型在函数调用、结构化输出、长上下文上的能力已经足够支撑复杂编排。工具侧，各种 Agent 框架和编排库层出不穷，LangGraph 就是其中比较有代表性的一个。工程侧，可观测性工具、链路追踪、状态管理这些配套也慢慢跟上了。

更重要的是，业务场景开始真正需要多 Agent。比如自动化代码审查，需要理解代码、检查规范、生成建议、验证建议四个环节，每个环节的提示词和工具集都不一样，硬塞进一个 Agent 效果很差。再比如深度研究助手，需要搜索、阅读、总结、交叉验证、生成报告，这本身就是一条流水线。

所以现在学多 Agent 编排，不是赶时髦，而是场景倒逼。你迟早会遇到单 Agent 搞不定的任务，到时候再学就晚了。

2. 编排框架选型：LangGraph 凭什么值得学

2.1 主流编排方案的横向对比

在动手之前，先搞清楚市面上有哪些编排方案，各自适合什么场景。我把常见的几类列出来：

我个人的建议是：流程简单用 LCEL，流程复杂用 LangGraph，需要多 Agent 讨论用 AutoGen，规模再大就自研。对于大多数想入门多 Agent 编排的开发者，LangGraph 是最佳起点，因为它把“图”这个抽象做得足够通用，既能表达简单流水线，也能表达复杂的状态机。

2.2 LangGraph 的核心抽象：状态、节点、边

LangGraph 的心智模型非常简单，就三个概念：

• State（状态）：一个共享的数据结构，所有节点都能读写。通常是个字典或 TypedDict。
• Node（节点）：一个函数，接收 State，返回 State 的更新。每个节点就是一个 Agent 或一个处理步骤。
• Edge（边）：定义节点之间的流转关系。可以是固定的（A 之后必走 B），也可以是条件的（根据 State 决定走 B 还是 C）。

这三样东西组合起来，就能表达任意复杂的流程。我画个简单的类比：State 是共享内存，Node 是函数，Edge 是调用关系。如果你写过状态机或者工作流引擎，这个概念一秒钟就懂了。

LangGraph 相比 LCEL 最大的优势是支持循环。LCEL 是 DAG（有向无环图），不能回头。但很多 Agent 场景需要循环，比如“生成代码 → 测试 → 失败 → 重新生成”，这就是一个环。LangGraph 天然支持这种结构。

2.3 环境准备：Python 安装与依赖管理

动手之前先把环境搞干净。我见过太多人因为环境问题卡在第一步，这里给一套我常用的流程。

Python 版本建议 3.10 以上，因为 LangGraph 用了一些新语法特性。安装 Python 本身不复杂，官网下载安装包一路下一步就行，Windows 记得勾选“Add Python to PATH”。装完之后验证：

python --version pip --version

依赖管理我强烈建议用虚拟环境，不要往全局环境里装。用 venv 就行：

python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate

激活之后装依赖：

pip install langgraph langchain-openai langchain-core

如果你需要用到 numpy 做数据处理，或者 cv2 做图像处理，也一并装上：

pip install numpy opencv-python

注意：opencv-python 在某些 Linux 环境下需要额外的系统依赖，装不上先看报错信息，通常是缺 libGL。Ubuntu 下apt install libgl1就能解决。

2.4 一个最小可运行示例

光说不练假把式。下面是一个最小的 LangGraph 示例，两个节点串行执行：

from typing import TypedDict from langgraph.graph import StateGraph, END class State(TypedDict): input: str step1_result: str step2_result: str def node_a(state: State) -> State: return {"step1_result": f"处理了: {state['input']}"} def node_b(state: State) -> State: return {"step2_result": f"二次处理: {state['step1_result']}"} graph = StateGraph(State) graph.add_node("a", node_a) graph.add_node("b", node_b) graph.set_entry_point("a") graph.add_edge("a", "b") graph.add_edge("b", END) app = graph.compile() result = app.invoke({"input": "hello"}) print(result)

跑通这个示例，你就理解了 LangGraph 的基本套路：定义 State、写节点函数、连边、编译、调用。后面所有的复杂编排都是在这个骨架上加东西。

3. 多 Agent 编排的核心设计模式

3.1 主管模式：一个大脑指挥多个手脚

这是最常用也最容易理解的模式。一个 Supervisor Agent 负责理解任务、分解任务、分派给 Worker Agent，Worker 干完活把结果交回来，Supervisor 决定下一步。

这个模式的好处是控制流清晰，所有决策集中在一个地方，调试的时候只需要看 Supervisor 的日志。坏处是 Supervisor 容易成为瓶颈，任务一多就忙不过来。

适用场景：任务分解逻辑明确、Worker 职责单一的场合。比如一个内容生产流水线，Supervisor 负责拆解“写一篇技术文章”这个任务，分给“资料搜集 Agent”“大纲 Agent”“正文 Agent”“校对 Agent”。

实现上，Supervisor 通常是一个带函数调用能力的 LLM 节点，它根据当前 State 决定下一个该谁干。LangGraph 里用条件边来实现：

def supervisor(state: State) -> str: # 根据 state 判断下一步 if not state.get("research_done"): return "researcher" elif not state.get("draft_done"): return "writer" else: return "reviewer" graph.add_conditional_edges("supervisor", supervisor, { "researcher": "researcher", "writer": "writer", "reviewer": "reviewer", })

3.2 流水线模式：各司其职，顺序推进

流水线模式把任务拆成固定顺序的几个阶段，每个阶段一个 Agent，前一个的输出是后一个的输入。这是最接近传统工作流的模式，也最容易理解和实现。

好处是可预测性强，每个阶段的输入输出格式固定，测试起来方便。坏处是灵活性差，中间某个阶段出问题，整个流程就卡住了。

适用场景：流程固定、阶段边界清晰的任务。比如文档处理流水线：解析 → 分块 → 嵌入 → 检索 → 生成。再比如代码审查流水线：拉取代码 → 静态检查 → 逻辑审查 → 生成报告。

流水线模式在 LangGraph 里就是简单的 add_edge 串联，不需要条件边。但要注意错误处理，每个节点都要考虑失败的情况，不能让异常直接冒泡把整个图搞崩。

3.3 辩论模式：多个 Agent 互相挑战

这个模式比较有意思。多个 Agent 针对同一个问题给出各自的答案，然后互相评论、挑战、修正，最后收敛到一个共识。适合需要多角度思考的场景，比如方案评审、风险评估。

实现上通常是两个或三个 Agent 轮流发言，用一个“裁判”Agent 判断是否达成共识。LangGraph 里用循环边实现：

def should_continue(state: State) -> str: if state["round"] >= 3 or state["consensus"]: return "end" return "debate" graph.add_conditional_edges("judge", should_continue, { "debate": "debater_a", "end": END, })

这个模式最大的坑是成本。每轮辩论都要调用多次 LLM，轮数一多 token 消耗惊人。我的经验是设置硬性轮数上限，同时给裁判 Agent 一个明确的“达成共识”判断标准，避免无限循环。

3.4 层级模式：大团队套小团队

当任务规模大到一定程度，扁平的结构就不够用了。层级模式把 Agent 组织成树状，顶层 Supervisor 管几个中层 Supervisor，每个中层 Supervisor 管一组 Worker。

这个模式适合超大规模任务，比如“分析一家公司的财报”，可以拆成“财务数据提取”“行业对比”“风险分析”三个子团队，每个子团队内部再细分。

代价是复杂度爆炸。层级越深，状态传递越麻烦，调试越困难。我的建议是层级不要超过三层，超过三层说明你的任务拆分有问题，应该考虑拆成多个独立的图。

4. 状态管理与 Agent 间通信的实操细节

4.1 State 设计：共享什么，隔离什么

State 设计是多 Agent 编排里最容易翻车的地方。设计得好，Agent 之间配合流畅；设计得差，要么信息不够用，要么状态污染。

我的经验法则是：共享必要信息，隔离中间过程。具体来说：

• 所有 Agent 都需要的全局信息放 State，比如用户原始输入、任务目标、全局配置
• 单个 Agent 的中间产物不要直接塞进 State，而是存到外部（文件、数据库），State 里只放引用
• State 的字段要少而精，超过 10 个字段就要考虑拆分了

LangGraph 的 State 支持 reducer，可以定义字段的合并策略。比如多个 Agent 同时往一个列表里追加内容：

from typing import Annotated from operator import add class State(TypedDict): messages: Annotated[list, add] current_task: str

这里的Annotated[list, add]表示这个字段的更新方式是追加而不是覆盖。这个细节很关键，不设置的话后一个 Agent 会把前一个的结果覆盖掉。

4.2 消息传递：结构化还是自然语言

Agent 之间传消息，有两种风格：结构化（JSON、字典）和自然语言（纯文本）。两种我都用过，各有优劣。

结构化消息的好处是解析稳定，下游 Agent 不用猜格式。坏处是表达能力受限，复杂信息塞不进固定 schema。自然语言消息的好处是灵活，坏处是下游解析容易出错。

我的实践是混合使用：控制信息用结构化，内容信息用自然语言。比如：

{ "task_id": "t001", "status": "success", "content": "这是 Agent A 生成的正文内容，可能很长...", "metadata": {"tokens": 1234, "duration": 2.3} }

这样下游 Agent 既能稳定拿到状态，又能灵活处理内容。

4.3 记忆管理：短期、长期、共享

Agent 的记忆分三层：

• 短期记忆：当前任务内的上下文，存在 State 里，任务结束就丢
• 长期记忆：跨任务的知识，存在向量数据库或文件里
• 共享记忆：多个 Agent 都能访问的公共区域，比如一个共享的草稿文档

短期记忆最简单，State 里放就行。长期记忆需要接向量库，LangGraph 支持 checkpointer 机制，可以把 State 持久化到 SQLite 或 Postgres。共享记忆比较麻烦，需要处理并发读写，我的做法是用一个专门的“记忆 Agent”来管理，其他 Agent 通过它读写。

注意：长期记忆不是越多越好。我见过一个项目把所有历史对话都塞进向量库，结果检索出来的全是噪音。记忆要有选择地存，只存那些对未来任务有价值的结论性信息。

4.4 并发控制：什么时候该并行

多 Agent 不一定非要串行。有些任务可以并行，比如“同时搜索三个不同的数据源”，并行能大幅缩短总耗时。

LangGraph 支持并行节点，只要多个节点从同一个节点出发，且没有相互依赖，就会自动并行执行。但并行有几个坑：

• 状态冲突：多个节点同时写同一个 State 字段，结果不确定。解决方法是给字段加 reducer，或者让并行节点写不同的字段。
• 资源竞争：并行调用 LLM 会瞬间打满 API 配额，需要加限流。
• 错误传播：一个并行分支失败，其他分支怎么办？要么全部回滚，要么部分成功。这个要在设计阶段就想清楚。

我的建议是默认串行，确认无依赖再并行。并行带来的复杂度提升，往往超过它节省的时间。

5. 常见问题排查与避坑实录

5.1 Agent 陷入死循环怎么办

这是多 Agent 编排最常见的问题。两个 Agent 互相等待，或者一个 Agent 反复调用同一个工具，流程永远走不到 END。

排查思路分三步：

1. 看日志：确认是哪个节点在重复执行，重复的触发条件是什么
2. 查条件边：条件函数的判断逻辑是不是有漏洞，比如某个状态永远为 False
3. 加护栏：给循环加最大轮数限制，超过就强制跳出

LangGraph 里可以给 State 加一个计数器：

class State(TypedDict): loop_count: int def should_continue(state: State) -> str: if state["loop_count"] > 10: return "end" return "continue"

提示：护栏不是万能的，它只是防止流程卡死，真正的问题还是要从条件逻辑上解决。我踩过的坑是条件函数里用了!=而不是==，导致判断永远为真。

5.2 状态污染导致下游 Agent 行为异常

状态污染的表现是：某个 Agent 突然开始做不属于它职责的事，或者输出格式完全不对。原因通常是上游 Agent 往 State 里写了不该写的东西。

比如上游 Agent 把“思考过程”也写进了 State，下游 Agent 看到一堆无关内容，就被带偏了。解决方法是严格定义每个字段的写入者，在代码层面做约束。

我的做法是给 State 字段加注释，标明谁写谁读：

class State(TypedDict): # 写入: supervisor, 读取: all task_goal: str # 写入: researcher, 读取: writer research_result: str # 写入: writer, 读取: reviewer draft: str

这样团队协作的时候，谁该写哪个字段一目了然。

5.3 Token 消耗失控的排查与优化

多 Agent 系统的 token 消耗通常是单 Agent 的 3 到 10 倍，因为每个 Agent 都要带上下文，还要互相传消息。失控的典型表现是账单突然暴涨。

优化手段有几个：

• 精简 State：只传必要信息，大文本存外部
• 压缩历史：老消息做摘要，不要原样传递
• 缓存结果：相同输入直接返回缓存，不重复调用
• 选对模型：简单任务用小模型，复杂任务才用大模型

我做过一个对比测试，同样的任务，优化前消耗 12 万 token，优化后降到 3 万，效果基本没差别。关键就是别把整个对话历史无脑传给每个 Agent。

5.4 常见问题速查表

5.5 调试技巧：链路追踪怎么做

多 Agent 系统的调试比单 Agent 难得多，因为一次请求会经过多个节点，每个节点都可能出问题。没有链路追踪，你根本不知道是哪一步出的错。

我的做法是给每个节点加统一的日志装饰器，记录输入、输出、耗时、token 消耗：

import time import functools def trace_node(func): @functools.wraps(func) def wrapper(state): start = time.time() print(f"[{func.__name__}] 输入: {state}") result = func(state) print(f"[{func.__name__}] 输出: {result}, 耗时: {time.time()-start:.2f}s") return result return wrapper

生产环境建议接 LangSmith 或者自建追踪系统，把每次调用的链路可视化。这个投入是值得的，能省下大量排查时间。

6. 从 Demo 到生产：多 Agent 系统的工程化

6.1 安全边界：Agent 能做什么，不能做什么

Agent 一旦接入真实工具，就有了实际操作能力。这时候安全边界必须划清楚。我见过一个 Agent 因为提示词注入，把数据库里的数据全删了，教训惨痛。

几条硬性规则：

• 工具白名单：只给 Agent 开放必要的工具，不要图省事全开
• 参数校验：所有工具调用的参数都要校验，不能直接透传
• 权限隔离：不同 Agent 用不同的凭证，最小权限原则
• 操作审计：所有工具调用都记日志，可追溯

注意：提示词注入是多 Agent 系统的高危风险。用户输入的内容如果直接进了 Agent 的提示词，就可能被利用。防御方法是把用户输入和系统提示词严格隔离，用结构化格式传递。

6.2 性能优化：让多 Agent 跑得更快

多 Agent 系统的性能瓶颈通常在两个地方：LLM 调用和状态传递。

LLM 调用优化：能并行的并行，能缓存的缓存，能用小模型的不用大模型。我做过统计，一个典型的多 Agent 流程里，60% 的 LLM 调用是可以用小模型替代的，成本能降一半以上。

状态传递优化：State 不要太大，大对象存外部。LangGraph 的 checkpointer 会序列化整个 State，State 越大，序列化越慢。我见过一个项目 State 里塞了几十 MB 的文本，每次节点切换都要序列化一遍，慢得离谱。

6.3 可观测性：生产环境必须有的监控

Demo 跑通和生产可用之间，差的就是可观测性。生产环境至少要监控这几个指标：

• 成功率：每次请求是否成功完成
• 耗时分布：P50、P95、P99 各是多少
• Token 消耗：按任务、按 Agent 统计
• 工具调用成功率：哪个工具最容易失败
• 异常分布：哪类错误最多

这些指标接上告警，出问题第一时间知道。我吃过亏，一个 Agent 静默失败了一周才发现，用户投诉了一堆。

6.4 版本管理与灰度发布

Agent 系统的提示词、工具、编排逻辑都会变，每次变更都可能影响效果。所以版本管理很重要。

我的做法是：

• 提示词单独存文件，用 git 管理
• 编排逻辑用配置文件描述，不改代码就能调整
• 新版本先灰度 10% 流量，观察指标再全量

这样出问题能快速回滚，不至于全量翻车。

7. 一个完整的实战案例：技术文章生成流水线

7.1 需求拆解与 Agent 划分

说了这么多理论，来个完整的实战案例。需求是：输入一个技术主题，自动生成一篇 3000 字的技术文章。

拆解一下，这个任务可以分成四个阶段：

1. 资料搜集：搜索相关资料，提取关键信息
2. 大纲生成：根据资料生成文章大纲
3. 正文撰写：按大纲逐节写正文
4. 校对润色：检查逻辑、修正错误、润色语言

对应四个 Agent：Researcher、Outliner、Writer、Reviewer。用流水线模式串联，Reviewer 发现问题可以打回 Writer 重写，形成一个带循环的流水线。

7.2 核心代码骨架

from typing import TypedDict, Annotated from operator import add from langgraph.graph import StateGraph, END class ArticleState(TypedDict): topic: str research: str outline: str draft: str review_feedback: str revision_count: int def researcher(state: ArticleState) -> ArticleState: # 调用搜索工具，整理资料 return {"research": "..."} def outliner(state: ArticleState) -> ArticleState: # 根据资料生成大纲 return {"outline": "..."} def writer(state: ArticleState) -> ArticleState: # 根据大纲写正文，如果有反馈则修订 return {"draft": "...", "revision_count": state.get("revision_count", 0) + 1} def reviewer(state: ArticleState) -> ArticleState: # 审查正文，给出反馈 return {"review_feedback": "..."} def should_revise(state: ArticleState) -> str: if state["revision_count"] >= 3: return "end" if "通过" in state["review_feedback"]: return "end" return "revise" graph = StateGraph(ArticleState) graph.add_node("researcher", researcher) graph.add_node("outliner", outliner) graph.add_node("writer", writer) graph.add_node("reviewer", reviewer) graph.set_entry_point("researcher") graph.add_edge("researcher", "outliner") graph.add_edge("outliner", "writer") graph.add_edge("writer", "reviewer") graph.add_conditional_edges("reviewer", should_revise, { "revise": "writer", "end": END, }) app = graph.compile()

这个骨架跑通之后，每个节点的具体实现可以逐步替换成真实的 LLM 调用和工具调用。

7.3 关键节点的提示词设计

多 Agent 系统里，每个 Agent 的提示词就是它的“岗位说明书”。写得好，Agent 各司其职；写得差，Agent 越界乱来。

Researcher 的提示词要点：明确搜索范围、要求提取事实而非观点、输出结构化。

Outliner 的提示词要点：给定资料和主题，输出三级大纲，每节标注预计字数。

Writer 的提示词要点：严格按大纲写，不要自由发挥，如果有修订反馈要针对性修改。

Reviewer 的提示词要点：从逻辑、事实、语言三个维度审查，给出具体修改建议，明确说“通过”或“不通过”。

提示：Reviewer 的提示词里一定要有明确的通过标准，否则它会一直挑毛病，导致无限修订。我的做法是列出三条硬性标准，满足即通过。

7.4 效果评估与迭代

系统跑起来之后，怎么判断好不好？我通常从三个维度评估：

• 完成率：多少比例的请求能正常走完全流程
• 质量分：人工抽检，给生成的文章打分
• 成本：平均每篇文章消耗多少 token、多少时间

第一版跑下来，完成率大概 70%，主要卡在 Reviewer 太严格。调整提示词后升到 90%。质量分从 3.2 升到 4.1（5 分制）。成本方面，平均每篇 8 万 token，还有优化空间。

迭代的方向很明确：优化 Reviewer 的判断逻辑，给 Writer 加缓存避免重复生成，把 Researcher 的搜索并行化。

8. 多 Agent 编排的学习路线与进阶方向

8.1 从入门到熟练的三阶段

如果你刚开始学多 Agent 编排，我建议按这个路线走：

第一阶段：跑通 Demo。把 LangGraph 官方示例跑一遍，理解 State、Node、Edge 三个概念。这个阶段不要追求复杂，能跑通就行。

第二阶段：复现经典模式。把主管模式、流水线模式、辩论模式各实现一遍，理解每种模式的适用场景和坑点。这个阶段要多写代码，光看没用。

第三阶段：做真实项目。找一个自己工作或生活里的真实需求，用多 Agent 编排实现。真实项目的复杂度会让你真正理解前面学的所有东西。

8.2 值得深入的方向

跑通基础之后，有几个方向值得深入：

• Agent 记忆：怎么设计长期记忆，怎么检索，怎么遗忘
• Agent 安全：提示词注入防御、权限控制、操作审计
• 多模态编排：Agent 处理图像、音频、视频
• 成本优化：模型路由、缓存策略、批处理
• 可观测性：链路追踪、指标监控、异常告警

每个方向都够研究很久。我的建议是先深挖一个方向，再横向扩展，不要什么都浅尝辄止。

8.3 一些个人体会

最后分享几点我在实际项目里的体会。

第一，不要为了多 Agent 而多 Agent。能用单 Agent 解决的，别上多 Agent。多 Agent 带来的复杂度是实打实的，收益不明显就别上。

第二，编排逻辑比 Agent 本身更重要。我见过太多项目把精力花在调提示词上，结果编排逻辑一塌糊涂。提示词是术，编排是道。

第三，可观测性要一开始就做。别等到出问题才想起来加日志，那时候已经晚了。链路追踪、指标监控这些东西，越早接入越好。

第四，成本意识要贯穿始终。多 Agent 系统的 token 消耗很容易失控，每次设计都要问自己：这一步真的需要调用 LLM 吗？能不能用规则替代？能不能缓存？

第五，保持简单。我踩过的最大的坑就是过度设计。一开始就想着支持各种复杂场景，结果代码写了一堆，实际用到的没几个。先做最简单的版本，跑通了再逐步加功能。

多 Agent 编排这个领域还在快速演进，今天的 best practice 明天可能就过时了。但底层的思路——分而治之、状态管理、流程控制——这些是不变的。把这些搞扎实，工具怎么变都不慌。