企业官网建设流程全解析

第一次看到“agency-agents”这个项目名时，我以为是哪个外包公司把自己包装成了系统名。但把这两个词拆开看，agency 是代理，agents 还是代理，那“代理组成的代理”到底在做什么？上手跑了一版之后才明白，这个项目的定位比名字自己描述的还要重要——它不是某一个具体功能模块，而是多智能体协作系统里真正承上启下的“指挥中枢”：对外承接任务目标，对内调度多个各司其职的智能体，最终把一堆模型调用、任务环节、质量校验拼装成一条稳定产出的流水线。说直白点，你不用它也能做 AI 应用，但你一旦需要让多个大模型角色在一起干活、按流程交付，就绕不开这类东西。

这篇内容适合正在做 AI 应用开发的人、准备把大模型接入业务系统的团队，也适合单纯想搞懂“多智能体架构到底怎么落地”的学习者。我会从概念拆解、架构设计、代码实现到问题排查完整过一遍，最后给出我自己跑了几轮之后的选型和避坑经验，尽量让看完的人能直接照着搭出一套能用的最小系统。

1. 项目核心拆解：agency-agents 到底解决什么问题

1.1 先搞清楚一个 Agent 和一组 Agent 的区别

单 Agent 大家已经很熟了：给它一个 System Prompt，设定角色，再喂任务，它就扮演一个角色从头干到尾。问题是真实业务很少是“一个角色从头干到尾”能搞定的。比如做一个市场调研报告，既要查资料、又要整理数据、还要写分析、最后还得校对格式，让同一个模型既当研究员又当写手，结果往往是上下文被撑爆、输出风格漂移、改一处崩三处。

agency-agents 这类项目的核心思路，就是把这些相互冲突的职责拆开，由不同的 Agent 各干一段，再由一个协调者把它们串起来。这就是它名字的来源：每一个 Agent 是在某个环节里干活的“员工”，而 agency 是统筹这些员工的中介组织。它解决的三个最实际的问题：

• 角色隔离：写代码的 Agent 和分析需求的 Agent 各用各的 Prompt，互不干扰，不会因为上半轮聊了需求，下半轮写代码时突然开始输出分析结论。
• 上下文可控：每个 Agent 只接收它需要的那部分信息，不让无关内容把窗口塞满，Token 消耗更可控。
• 结果可校验：不同 Agent 之间产出互相检查，等于给模型输出上了一道人工质检。

1.2 它和单次调用的本质区别在哪

很多人第一次接触这个项目时会问：我不做这些中间层，直接在一个流程里分几次调用大模型不行吗？当然行。但分几次调用只是把代码顺序执行了一遍，上游的输出没有结构化、下游拿到什么也不会校验、失败之后没有重试机制。而 agency-agents 哪怕是一个最简版本，也会把每个 Agent 的输入输出定义成明确的接口契约，再经由协调器做路由、校验、回溯。

我用一个生活化的类比帮非技术背景的人理解：单次调用像是你开着一辆车去送货，所有货物一次全塞后备箱，路线自己走，到地方自己卸。多智能体架构则像一个配送站：货物到站先分拣（Planner），然后不同的快递员分别送不同片区（Worker），每趟回来还要扫码确认妥投（Reviewer）。前面那种方式适合小件，后面这种才能撑起大件吞吐。

1.3 为什么说它是“大模型应用热词里最被低估的一层”

说它被低估，是因为大多数讨论都集中在上层应用或者底层模型参数上，中间这一层很容易被一笔带过。但实际做着做着你会发现，上层功能千变万化，底层模型各家能力也接近，真正决定系统稳不稳、好不好扩的，恰恰是中间这个 agent 管理层。它承担了这些年 AI 工程化落地最头疼的三件事：任务编排、状态管理和成本控制。你问任何一个做过多智能体系统的人，最后都会告诉你：模型选型不是瓶颈，编排才是。

2. 架构设计与角色编排方案

2.1 角色分工设计：不让一个 Agent 干两件需要相反能力的事

我最早搭这套东西时犯过一个典型错误：让一个 Agent 同时做“生成”和“检查”。结果它一边写需求文档一边自己纠错，反而把对的内容也改错了。后来改成专职分工，效果立刻好转。一套标准的 agency-agents 架构，角色可以按功能分成四类：

• 调度者（Planner/Orchestrator）：负责拆解任务、决定调哪几个 Worker、把中间结果传给谁。
• 执行者（Worker）：真正干活的角色，按领域划分，比如代码工人、文案工人、数据分析工人。
• 质检者（Critic/Reviewer）：专门挑刺，检查 Worker 的输出是否符合要求、有没有明显错误。
• 汇总者（Reporter/Summarizer）：把多份输出整合成最终交付物。

这四类角色不是每套系统都要全部上，但哪怕你只精简到调度加执行两个角色，也要把职责边界划清。我的经验是：设计阶段宁可多定义几个角色，最后再合并，也不要先铺一个万能 Agent 以后再拆。因为合并容易，拆分很难——一旦 Agent 的输出已经互相依赖，再想斩断关系就要动整体接口了。

2.2 编排模式：串行、并行、还是混合

角色定好了，接下来就是编排方式。agency-agents 里常用的三种模式，对应不同业务场景：

我自己的习惯是“先并行做脏活，再串行做精活”。数据收集、初稿生成这类容错率高的活儿尽量并行，review、合并、终审这类质量敏感的环节一定串行。这样既保证速度，又不至于把质量线放松。

2.3 没有调度层会怎样

这个我在测试环境里验过，不装调度层、只留一堆 Agent 互相调，效果非常混乱。最常见的问题是死循环：A 问 B，B 觉得信息不够又问 A，A 又给 B 补一段，两个 Agent 轮流传话，上下文越积越长，成本越来越高，最后谁也没产出。调度层就是这里的裁判，它明确什么时候该调谁、等多久、超过多少轮直接断。所以哪怕一开始写得粗糙，也一定要留一个“能拍板”的角色。

3. 实操落地：搭建一套最小可用的 agency-agents 系统

3.1 技术选型：买现成的框架还是自己写一个

接到这个项目名时，我首先考虑的就是选型。市面上已有的多智能体编排框架确实能省事，有开箱即用的角色编排协议、内置模型接入和任务队列。如果团队的目标是快速验证、又有一定工程能力跟得上，用它确实能省几周时间。

但这类框架也有很明显的问题：抽象层厚，内部执行逻辑像一个黑盒。一旦你想在某个环节插入私有逻辑，比如特有的审核规则、自定义的重试策略，改起来非常费劲。另一个问题是换模型厂商非常痛苦，很多框架的请求协议和上游厂商深度耦合。

我的建议是：做概念验证（POC）用现成框架，做生产系统自己包一层。我最终的选择是广告一个轻量级的编排内核，把和模型厂商相关的部分做成可替换接口。核心依赖只有两个：一个是 LLM 客户端封装（处理请求、密钥、超时），另一个是任务队列（实现简单的重试和状态跟踪）。其余全部用基础代码实现，不碰重量级框架。

3.2 核心代码骨架：角色、任务、上下文的抽象

下面这版代码是我跑通的最小骨架，核心思想极其简单：每个 Agent 只负责根据输入产生输出，调度器负责路由和流转。能用很薄的抽象实现就先不堆复杂的概念。

# 一个极简的 Agent 抽象：定义角色、系统提示词和模型 class Agent: def __init__(self, role: str, system_prompt: str, model: str): self.role = role self.system_prompt = system_prompt self.model = model def run(self, user_message: str) -> str: return call_llm( system=self.system_prompt, user=user_message, model=self.model, ) # 调度器：控制 Agent 之间的流程和传参 class Orchestrator: def __init__(self): self.agents = {} def register(self, agent: Agent): self.agents[agent.role] = agent def run_pipeline(self, steps, initial_input): context = initial_input for step in steps: role, user_msg = step result = self.agents[role].run(user_msg) # 关键：把上一步的输出结构化成下一步的输入 context += f"\n[{role}] 输出：{result}" return context

这段代码最重要的有三个地方：第一，所有角色共用同一个 Agent 类，只是换了提示词和模型，逻辑极其简法，扩展新角色只需要注册一个实例；第二，context 以累加方式向下传递，天然形成一个可追溯的对话链条；第三，调度器是纯 Python 流程控制，中间加一个条件判断或者重试逻辑都特别方便。我自己跑通这个骨架之后，再看那些重框架里的概念，脑子里都是同一套东西，只是包装多了些。

3.3 任务分解与上下文传递的实操要点

任务怎么拆，是决定最终效果的分水岭。哪怕角色设计对了，拆分粒度不对，照样跑不通。我自己总结了一套很实用的拆解原则：一个任务单元最好是 200 到 500 字能说清楚的目标，超过这个量就往下拆一级。

比如“写一篇产品宣传文案”这个任务，拆法可以是这样：

1. 调研 Agent：收集产品的三个核心卖点和目标用户特征。
2. 写手 Agent：根据卖点和用户特征生成初稿。
3. 审核 Agent：检查文案是否有夸大表述、有没有漏掉必须出现的产品型号。
4. 优化 Agent：根据审核意见修改，并输出最终稿。

每一级输出的结果，都要在上下文里用明确的标记隔开。我踩过的坑是：如果把 Agent 的输出直接拼接进一个大 prompt 而不做分段，模型很容易混淆哪些内容是任务要求、哪些是历史产出。解决办法是在拼接时加上角色前缀（就像上面代码里的[role]标记），再配一句“请只根据上一环节的输出执行任务”，这样上下文传递的准确性高很多。

3.4 模型选配：不同角色真的需要不同模型吗

这里有一个成本优化的小技巧。不一定每个 Agent 都配最强的模型，完全可以做“分级模型策略”：规划、终审这些逻辑密度高的角色分配强模型；资料收集、初步整理这些按模板执行的环节分配性价比高的弱模型。我在实际系统中就是这样配的，成本直接降了一截，而输出质量几乎没有变化。

但要注意一点：如果某个 Agent 的输出喂给下游后，下游经常反馈格式不对，先不要急着升级模型，先查是不是 prompt 里的输出格式要求写得不够死。调整 prompt 比换模型便宜得多。绝大多数格式混乱问题都是 prompt 里没说清“只允许输出 JSON，不要解释”，而不是模型能力不够。

4. 典型故障清单与排查实录

4.1 六个最容易踩的坑和对应的修复思路

多智能体系统跑起来之后，故障不会少，但大部分都有规律可循。下面是我在项目跟进过程中反复遇到并解决的问题，统一整理成一张速查表：

4.2 排查示范：一个反复出现的案例

这次遇到的案例非常典型：A 角色生成的产品方案，传给 B 角色做审核。B 角色经常回复“方案缺少预算细节”，但方案在 A 的输出里明显有预算那一项。起初以为是模型能力问题，换更强的模型也一样。

后来把 B 角色的完整输入打印出来才看到：调度器把 A 角色的输出转成了普通文本，但转的过程中丢失了表格结构，预算信息整块没传过去。问题根本不在模型，而在中间解析环节。从那以后，我要求所有 Agent 之间的传递数据必须以结构化 JSON 或带明确标记的 Markdown 格式传，不再转成纯文本，这个故障就彻底消失了。

排查多智能体问题有一个总原则：永远先查数据流转，再查模型质量。因为这个系统里 80% 的“模型变笨了”其实都是数据没送到位、或者前一步发生了隐晦的格式缺失。

4.3 观测与追踪手段

别依赖日志文本去找问题，效率太低了。我给自己的系统加了一个极轻量的调用记录表，核心字段就三个：角色名、输入摘要、输出摘要。跑完一条流程后，只用扫一眼这个表就能看出是哪一环断了，不用再去翻几百行的原始日志。

如果你有图表类的观测工具，可以在上面加一条“每次执行的完整链路时间线”，时间线上标注每个 Agent 起止时间。一旦发现某个角色耗时异常，直接锁定该环节的输入输出做字段层面的测试。这套“先全局、后局部”的排查路径，帮我解决过至少五次疑难故障。

5. 场景价值与部署决策指南

5.1 什么场景下值得用，什么场景下不值得用

agency-agents 不是所有 AI 应用的必需品。我工作中见过不少强行上多智能体的案例，最后都因为维护成本反而不如直接写死逻辑。合理的判断标准就一条：任务是否真的需要多角色协作。如果单次调用能解决，就不要拆；如果任务需要多个不同能力模型配合完成、有明确的中间产物可能需要人工介入，再考虑上。

值得使用的典型场景包括：内容生产流水线（调研、写稿、配图、审核）、软件项目辅助开发（需求分析、代码生成、代码走查、文档整理）、复杂数据分析（数据采集、清洗、建模、报告生成）。这些场景共同点很明显：环节多、角色能力不同、产出有先后依赖。

不值得做的场景也明显：一次性问答、简单格式转换、模板化输出。这些场景上多智能体，只会多出无意义的模型调用和延迟。判断时给自己提一个灵魂问题：去掉“角色”这个概念，用普通函数能不能实现？如果能，就别折腾。

5.2 从验证到生产的落地顺序

如果项目已经决定要上多智能体，我建议按三个阶段推进，不要一步到位。

第一阶段：跑通核心链路，只选三个角色（调度、执行、汇总），用简单的数据集目测质量。 第二阶段：加入质检和重试机制，跑有量化指标的任务，把成功率、Token 消耗、平均耗时统计出来。 第三阶段：再扩充角色数量和业务场景，此时底座已经稳定，加角色只是注册一个类实例的事。

这个顺序的核心逻辑是先稳定骨架再填充肌肉。很多人上来就铺十几个 Agent，看起来热闹，实际上链路一长，问题根本定位不了。骨架稳定以后，一次在一个环节加一个新角色，出了问题也知道只查那个环节。

5.3 横切关注点：成本、安全、可维护性

最后再补充几个横切关注点，这些不只在某个环节出现，而是贯穿全局。

成本控制方面，除了前面提的分级模型，还可以给每个角色单独设单次调用的预算上限，超预算就自动走简备逻辑。我的系统里最常见的一笔浪费源头是“重试不设次数上限”，出错之后无限重试，成本直接失控。后来统一加上最大重试次数和退避策略，预算立刻稳住。

安全性方面，每个 Agent 的输入输出都要做一层过滤。特别是不怀好意的用户指令，很容易伪装成剧情背景穿过多级传导，最终落到高危操作上。多智能体系统因为链路长，远比单次调用更容易发生“注入穿透”，这个风险常被低估。我要求在调度器层统一做指令与业务内容分隔，下游 Agent 只能读取业务内容片段，读不到原始用户输入。

可维护性方面，每个角色的 prompt 一定要拆到独立配置里，不要散落在各段代码中。我见过一次改模型行为时，为了改一个提示词，要翻七个文件的情况。把它们集中到一个目录、一份配置表里，维护成本骤降。

6. 个人实跑体验与小建议

项目本身可研究的空间比预期大不少。最初我只是想快速搭一个演示用的小系统，结果越深入越发现角色编排、状态流转这些环节才是真正决定 AI 系统生产级别的分水岭。跑完几轮之后我最深的三点体悟：一是分工粒度靠试错，靠直觉定的拆法大概率第一次就要调整，别怕重构角色；二是数据流转比提示词重要，模型表现不佳时先想数据有没有完整送达，再去调词；三是调度器一定要设计成可观测的，给每个环节留好可追踪的记录口子，后面排查问题和做优化都靠它。

最后再分享一个特别实用的小技巧：Agent 的提示词里可以写明“如果你是面向一个完全没有相关背景的用户来解释”，这一点在下游 Agent 做汇总时尤其管用，能明显降低输出里默认读者都懂导致的“漏信息”问题。我从一个同事的实践里学到这个写法之后，用到自己的所有 Agent 里，信息完整度提高得很直接。这个系统后续可扩展的方向也很多，比如接入工具调用、增加人工审核闸门、把调度策略改成动态路由。但不管怎么扩展，核心的那套“角色隔离、流程可见、数据可控”的原则不会变，这也是我认为这个题目最值得学习和沉淀的价值所在。