企业官网建设流程全解析

1. 从"agency-agents"这个标题说起：一个多智能体协作框架的完整拆解

第一次看到"agency-agents"这个标题的时候，我脑子里蹦出来的第一反应是：这大概率是一个围绕"代理"和"智能体"做文章的项目，而且从命名习惯来看，它想强调的不是单个agent的能力，而是"agency"——也就是代理机构、协作组织这一层含义。换句话说，这个项目的核心命题应该是：当多个智能体需要像一家公司里的员工那样协同工作时，我们该怎么设计它们的组织架构、通信机制和任务分配逻辑。

这个判断不是拍脑袋来的。过去两年我在实际项目里反复折腾过单agent和multi-agent两套方案，踩过的坑足够写一本小册子。单agent的问题很明显：一个模型既要理解需求、又要规划步骤、还要执行工具调用、最后还得自我检查，上下文一长就开始"精神分裂"，前面定的规则后面自己就忘了。而multi-agent虽然听起来美好，但真正落地时会遇到一堆工程问题——agent之间怎么通信、任务怎么拆、冲突怎么仲裁、成本怎么控制。所以当我看到"agency-agents"这个命名时，我基本能确定它想解决的就是后面这一堆问题。

这篇文章我打算把这个项目从头到尾拆一遍。不管你是刚听说multi-agent概念想找个框架上手的新手，还是已经用过多智能体方案但被各种坑折磨过的老手，我都尽量把设计思路、核心机制、实操步骤和避坑经验讲透。我会用大量类比和实际代码片段来说明问题，确保你看完能自己动手搭一个能跑起来的多智能体协作系统。

2. 多智能体协作到底难在哪：先搞清楚问题再谈方案

2.1 单agent的天花板在哪里

在聊"agency-agents"这类框架之前，得先把单agent的局限性说清楚，不然你无法理解为什么需要搞这么复杂的一套东西。

我最早做的一个项目是让一个agent帮用户处理日常事务：查资料、整理文档、发邮件、排日程。刚开始跑demo的时候感觉挺惊艳，但一旦任务链条拉长到七八步，问题就全冒出来了。最典型的是上下文污染——前面查资料时塞进去的一大堆网页内容，会干扰后面写邮件时的语气判断；再比如角色混淆——同一个模型既要当严谨的研究员，又要当随和的助理，切换起来经常串味。

还有一个更隐蔽的问题是错误累积。单agent执行多步任务时，每一步的小偏差会像滚雪球一样放大。第一步理解需求偏了10%，到第五步可能就完全跑偏了。而且因为只有一个执行者，它很难发现自己错了——你让一个人自己检查自己的作业，效果通常不怎么样。

这里有个经验：单agent适合处理"线性、短链条、低耦合"的任务，比如单轮问答、单次文档总结、单次代码生成。一旦任务需要多角色、多阶段、多工具配合，就该考虑多智能体了。

2.2 多智能体不是"多开几个agent"这么简单

很多人对multi-agent的理解停留在"我开三个agent，一个写代码、一个review、一个测试"这个层面。这个理解没错，但太浅了。真正难的是它们之间的协作协议。

我打个比方：单agent像一个人开小店，什么都自己干；多智能体像开一家公司，你得有组织架构（谁向谁汇报）、有沟通机制（开会还是发邮件）、有决策流程（谁拍板）、有冲突解决机制（两个人意见不合怎么办）。"agency-agents"这个标题里的"agency"其实就是在暗示这一层——它要解决的是"代理机构"级别的组织问题，而不是简单的agent堆叠。

具体来说，多智能体协作要解决四个核心问题：

• 任务分解：一个大任务怎么拆成子任务，拆到什么粒度合适
• 角色定义：每个agent负责什么，边界在哪里，权限有多大
• 通信机制：agent之间怎么传递信息，是共享内存还是消息队列
• 协调与仲裁：多个agent产出冲突时听谁的，怎么防止死循环

这四个问题每一个都有坑，而且它们之间相互影响。比如任务拆得太细，通信开销就爆炸；角色定义太死，遇到边界情况就卡住；通信机制设计不好，agent之间会互相"刷屏"浪费token。

2.3 为什么"agency"这个视角很重要

我特别想强调"agency"这个词。它不只是"代理"的意思，更强调"代理机构"——一个有组织、有分工、有流程的实体。这个视角的转变很关键。

如果你把multi-agent当成"多个独立的agent"，你会倾向于让每个agent都尽量强大、尽量全能。但如果你把它当成"一家代理机构"，你就会自然地想到：应该有一个管理层agent负责统筹，有若干执行层agent负责具体工作，可能还有质检层agent负责把关。这种组织化的思路，比单纯堆agent要高效得多。

"agency-agents"这个项目名，我理解它想传达的就是这种"组织化协作"的理念。接下来我会按照这个思路，把它的核心设计拆开来讲。

3. 核心架构拆解：一个多智能体系统应该长什么样

3.1 分层架构：管理层、执行层、质检层

基于我自己的实践和对这类框架的理解，一个成熟的多智能体系统通常会采用分层架构。这不是为了好看，而是因为不同层级的agent对能力的要求完全不同。

管理层agent（也叫Orchestrator或Coordinator）负责理解用户意图、制定整体计划、分配任务、汇总结果。它不需要很强的执行能力，但需要很强的规划和判断能力。我通常会用能力最强的模型来担任这个角色，因为它的决策质量直接决定整个系统的上限。

执行层agent负责具体干活，比如搜索、写代码、调API、生成文档。它们需要的是专精能力，而不是全能。我一般会给每个执行agent配一套专属的工具集，让它专注于自己的领域。

质检层agent负责检查执行结果是否符合要求。这个角色经常被忽略，但我觉得它至关重要。质检agent的价值在于它能提供"第二双眼睛"，发现执行agent自己发现不了的问题。

用代码结构来表示大概是这样：

class AgencySystem: def __init__(self): self.manager = ManagerAgent(model="strong-model") self.workers = { "researcher": WorkerAgent(tools=[search, fetch]), "coder": WorkerAgent(tools=[code_exec, file_io]), "writer": WorkerAgent(tools=[text_gen]) } self.reviewer = ReviewerAgent(model="strong-model") def run(self, task): plan = self.manager.plan(task) results = {} for step in plan.steps: worker = self.workers[step.role] results[step.id] = worker.execute(step) review = self.reviewer.check(results) if not review.passed: return self.run_with_feedback(task, review.feedback) return self.manager.synthesize(results)

这个结构看起来简单，但每个环节都有讲究。比如管理层怎么"plan"，是用固定模板还是让模型自由发挥？执行层的结果怎么传递给下一层，是原始输出还是结构化数据？质检不通过时怎么重试，重试几次？这些细节决定了系统是能跑还是能跑好。

3.2 通信机制：共享状态 vs 消息传递

agent之间怎么通信，这是架构设计里最容易出问题的地方。我见过两种主流方案，各有优劣。

共享状态方案是让所有agent读写同一个全局状态对象。好处是简单直接，任何agent都能看到完整上下文。坏处是容易造成"上下文爆炸"——当状态对象越来越大时，每个agent的输入都会变得很长，既费token又容易让模型分心。

消息传递方案是agent之间通过消息队列通信，每个agent只看到发给自己的消息。好处是上下文干净、职责清晰。坏处是需要设计消息格式和路由规则，复杂度更高。

我自己的经验是：小规模系统（3-5个agent）用共享状态就够了，大规模系统（10个以上）必须用消息传递。中间规模可以混合——核心状态共享，细节信息通过消息传递。

"agency-agents"这类框架通常会提供两种模式的抽象，让你根据场景选择。我建议新手从共享状态开始，因为调试起来直观；等系统复杂了再迁移到消息传递。

3.3 任务分解策略：静态模板 vs 动态规划

任务怎么拆，这是另一个核心问题。我见过两种极端做法。

静态模板是预先定义好任务类型和对应的分解方式。比如"写一篇报告"就固定拆成"查资料→列大纲→写正文→校对"四步。好处是稳定可控，坏处是遇到新任务类型就抓瞎。

动态规划是让管理层agent根据具体任务实时决定怎么拆。好处是灵活，坏处是不稳定，同一个任务两次运行可能拆出完全不同的结构。

我的建议是混合策略：对高频任务用静态模板保证稳定性，对低频或复杂任务用动态规划保证灵活性。具体实现上，可以维护一个"任务模式库"，管理层agent先匹配模式库，匹配不到再走动态规划。

实操心得：动态规划时一定要给管理层agent设置"最大分解深度"和"最大子任务数"，否则它可能把一个简单任务拆成几十个子任务，既慢又贵。我一般设深度不超过3层，子任务总数不超过10个。

4. 实操搭建：从零跑通一个多智能体协作流程

4.1 环境准备与依赖选择

假设我们要基于"agency-agents"的思路搭一个能跑的系统，第一步是环境准备。这里我不绑定任何具体的商业服务，只讲通用的技术选型逻辑。

你需要准备的东西包括：

• 一个模型调用层：负责统一封装不同模型的调用接口，方便切换和降级
• 一个工具注册机制：让agent能动态发现和调用工具
• 一个状态管理模块：负责维护全局状态和消息历史
• 一个日志与追踪模块：记录每个agent的输入输出，方便调试

我用Python举例，目录结构大概这样：

agency_agents/ ├── core/ │ ├── agent.py # agent基类 │ ├── manager.py # 管理层agent │ ├── worker.py # 执行层agent │ └── reviewer.py # 质检层agent ├── comm/ │ ├── state.py # 共享状态 │ └── message.py # 消息传递 ├── tools/ │ ├── registry.py # 工具注册 │ └── builtin.py # 内置工具 └── main.py # 入口

这个结构的好处是职责清晰，每部分都能独立测试。我特别建议把工具注册单独抽出来，因为工具是agent能力的延伸，管理好工具就等于管理好agent的能力边界。

4.2 定义agent基类与角色规范

所有agent都应该继承同一个基类，这样能保证接口一致。基类里要定义的核心方法包括：接收任务、执行任务、返回结果、报告状态。

class BaseAgent: def __init__(self, name, role, model, tools=None): self.name = name self.role = role self.model = model self.tools = tools or [] self.history = [] def build_prompt(self, task, context): # 把角色描述、任务、上下文组装成prompt return f""" 你是{self.role}。 当前任务：{task} 可用工具：{[t.name for t in self.tools]} 上下文：{context} 请给出你的输出。 """ def execute(self, task, context): prompt = self.build_prompt(task, context) response = self.model.generate(prompt) self.history.append({"task": task, "response": response}) return response

这里有个关键点：角色描述要写得足够具体。我见过很多人写角色描述就一句话"你是一个研究员"，这样模型根本不知道自己该干什么。好的角色描述应该包含：职责范围、输出格式、注意事项、边界条件。比如：

你是一个资料研究员。你的职责是根据给定的问题，检索相关资料并整理成结构化摘要。 输出格式要求： 1. 先列出3-5个关键发现 2. 每个发现附上来源 3. 最后给出你的置信度评估（高/中/低） 注意事项： - 不要编造信息，找不到就说找不到 - 不要做超出研究范围的判断 - 如果问题模糊，先提出澄清问题

这种详细的角色描述，能让agent的表现稳定很多。

4.3 管理层agent的任务规划实现

管理层agent是整个系统的大脑，它的核心工作是"把用户的一句话变成可执行的计划"。我通常会让它输出结构化的JSON，而不是自由文本，这样后续处理更方便。

class ManagerAgent(BaseAgent): def plan(self, user_request): prompt = f""" 用户请求：{user_request} 请把这个请求拆解成可执行的步骤，输出JSON格式： {{ "goal": "整体目标", "steps": [ {{"id": 1, "role": "researcher", "task": "具体任务描述", "depends_on": []}}, {{"id": 2, "role": "writer", "task": "具体任务描述", "depends_on": [1]}} ] }} 要求： - 步骤数不超过8个 - 每个步骤必须指定role - depends_on表示依赖的前置步骤 """ response = self.model.generate(prompt) return self.parse_json(response)

这里depends_on字段很关键，它定义了任务之间的依赖关系，决定了执行顺序。没有依赖的步骤可以并行执行，有依赖的必须串行。这个设计能显著提升效率。

踩坑提醒：模型输出的JSON经常有格式问题，比如多一个逗号、少一个引号。一定要写健壮的解析逻辑，解析失败时要么重试要么降级到文本解析。我一般会重试2次，还失败就让管理层agent用自然语言重新描述计划。

4.4 执行层agent的工具调用与结果回传

执行层agent的核心是"调用工具完成任务"。工具调用的实现方式取决于你用的模型，有的模型原生支持function calling，有的需要你自己解析文本。

class WorkerAgent(BaseAgent): def execute(self, task, context): # 先让模型决定用哪个工具 tool_decision = self.decide_tool(task, context) if tool_decision: tool = self.find_tool(tool_decision["name"]) result = tool.run(**tool_decision["args"]) # 把工具结果喂回模型做总结 summary = self.summarize(task, result) return {"raw": result, "summary": summary} else: # 不需要工具，直接生成 return {"summary": self.model.generate(task)}

这里有个设计选择：工具结果是直接返回还是让模型总结后再返回。我的经验是，对于结构化数据（比如搜索结果列表），让模型总结一下更好，因为下游agent更容易理解；对于已经是自然语言的结果（比如生成的文档），直接返回就行，再总结反而丢信息。

4.5 质检层agent的检查逻辑

质检层agent的价值在于"独立判断"。它不能和执行agent共享上下文，否则就失去了独立性。我通常会让质检agent只看"任务要求"和"执行结果"，不看执行过程。

class ReviewerAgent(BaseAgent): def check(self, task, result): prompt = f""" 任务要求：{task} 执行结果：{result} 请检查： 1. 结果是否完整回答了任务要求？ 2. 是否有明显的事实错误或逻辑漏洞？ 3. 格式是否符合要求？ 输出JSON： {{"passed": true/false, "issues": ["问题1", "问题2"], "suggestions": ["建议1"]}} """ response = self.model.generate(prompt) return self.parse_json(response)

质检不通过时，系统应该把issues和suggestions反馈给执行agent，让它重做。这里要设置最大重试次数，我一般设2次，超过就上报给管理层agent决定是降级处理还是放弃。

5. 常见问题与排查技巧实录

5.1 agent陷入死循环怎么办

这是多智能体系统最常见的问题。典型表现是：执行agent产出结果→质检不通过→执行agent重做→质检还是不通过→无限循环。

排查思路分三步：

第一步，看质检标准是否过严。有时候质检agent会提出一些吹毛求疵的问题，导致执行agent永远无法满足。解决方法是给质检标准设置优先级，只检查关键项，非关键项作为建议而非阻塞条件。

第二步，看执行agent是否理解反馈。有时候质检的反馈太抽象，执行agent不知道怎么改。解决方法是在反馈里加入具体示例，告诉它"应该改成什么样"。

第三步，看任务本身是否可完成。有些任务在当前能力下就是做不到的，这时候应该让管理层agent介入，要么降低要求，要么拆成更小的任务。

我的做法是给每个任务设置"最大重试次数"和"最大总耗时"，任一超限就触发降级流程。降级流程可以是返回部分结果、返回错误说明、或者转人工处理。

5.2 token消耗失控怎么优化

多智能体系统的token消耗通常是单agent的3-10倍，如果不加控制，成本会很难看。我总结了几个优化手段：

其中模型分级是我最推荐的。管理层和质检层用强模型保证质量，执行层里简单的任务用轻量模型，复杂的才用强模型。实测下来能省一半以上的成本，质量下降却很有限。

5.3 结果不一致怎么排查

同一个任务跑两次结果不一样，这在多智能体系统里很常见，因为模型本身有随机性。但如果差异过大，就说明系统有问题。

排查清单：

• 检查温度参数：执行层agent的温度应该设低一点（0.1-0.3），保证稳定性；管理层可以稍高（0.5-0.7），保留灵活性
• 检查任务分解：如果两次分解出的步骤差异很大，说明管理层agent的规划不稳定，需要加约束
• 检查工具调用：工具返回结果是否稳定，有没有依赖外部不确定因素
• 检查上下文：两次运行的上下文是否一致，有没有残留状态

我一般会跑3次同样的任务，对比结果差异。如果差异在可接受范围内（比如措辞不同但核心一致），就正常；如果核心结论都不同，就得深入排查。

5.4 常见问题速查表

6. 进阶玩法：让多智能体系统更聪明

6.1 引入记忆机制

基础版的多智能体系统是"无状态"的，每次任务都从零开始。但实际场景里，很多任务是有关联的。比如用户先让你查资料，过一会儿又让你基于之前的资料写报告，这时候就需要记忆。

记忆机制分两层：短期记忆是当前会话的上下文，长期记忆是跨会话的知识沉淀。短期记忆用消息历史实现就行，长期记忆需要向量数据库或者结构化存储。

我的做法是给每个agent配一个"记忆检索"工具，让它能主动查询历史信息。这样既保持了上下文的干净，又能在需要时获取历史知识。

6.2 动态角色调整

固定角色有个问题：遇到边界任务时，没有agent能接。比如一个任务既需要研究又需要写作，但研究agent和写作agent都不愿意接。

解决方法是引入"动态角色"机制：管理层agent在分配任务时，可以临时创建一个新角色，或者让某个agent临时扩展职责。这需要在角色定义时留出扩展空间，比如给每个agent一个"其他职责"字段。

6.3 人机协作接口

完全自动化的多智能体系统在复杂场景下往往不够可靠，引入人工介入点能大幅提升实用性。我通常会在三个地方设置人工确认点：

• 计划确认：管理层agent制定计划后，让用户确认再执行
• 关键决策：遇到需要判断的节点，暂停等待用户输入
• 最终审核：结果产出后，让用户做最后把关

这些确认点可以通过回调函数实现，不阻塞主流程，但能在关键节点引入人类智慧。

7. 我踩过的那些坑：几条血泪经验

做多智能体系统这两年，踩的坑比我预想的多得多。挑几个最有代表性的说说。

第一个坑是过度设计。我一开始就想搞一个"全能框架"，支持任意数量的agent、任意复杂的拓扑结构。结果代码写了一堆，实际能跑的场景没几个。后来我砍掉了80%的功能，只保留最核心的"管理层+执行层+质检层"三层结构，反而好用多了。教训是：从最小可用系统开始，按需扩展，不要一上来就追求通用。

第二个坑是忽视可观测性。早期系统出问题时，我根本不知道是哪个agent、哪一步出的错，只能靠猜。后来我加了一套完整的日志系统，记录每个agent的输入、输出、耗时、token消耗，排查效率提升了十倍。教训是：可观测性不是可选项，是必选项，而且要在第一版就加上。

第三个坑是盲目信任模型输出。我早期让执行agent直接返回结果，不做任何校验，结果经常出现格式错误、内容缺失。后来我加了严格的输出校验和重试机制，稳定性大幅提升。教训是：永远不要假设模型会按你期望的格式输出，一定要校验。

第四个坑是忽略成本控制。有一次跑一个批量任务，没注意token消耗，一晚上烧掉了一个月的预算。后来我加了实时成本监控和上限告警，再也没出过这种事。教训是：成本控制要前置，不能等出事了才补救。

第五个坑是角色定义太模糊。我早期给agent的角色描述就一句话，结果agent经常越界，做了一堆不该它做的事。后来我把角色描述写成了"职责+边界+输出格式+注意事项"四段式，问题基本消失了。教训是：角色定义越具体，agent表现越稳定。

这些坑说到底都指向一个核心原则：多智能体系统的复杂度是单agent的数倍，所以每个环节都要比单agent更严谨。你不能指望用"差不多"的态度做出"靠谱"的系统。

8. 关于这个方向的一些个人判断

写到这里，我想分享几个我对多智能体方向的个人判断，不一定对，但都是我实际做项目得出的体会。

第一，多智能体不会取代单agent，而是互补。简单任务用单agent又快又省，复杂任务才需要多智能体。不要为了用多智能体而用多智能体，那是本末倒置。

第二，框架的价值在于"约束"而非"自由"。好的多智能体框架不是让agent想干什么就干什么，而是通过角色定义、通信协议、质检机制来约束agent的行为。约束越清晰，系统越可靠。

第三，评估体系比框架本身更重要。你怎么知道你的多智能体系统好不好？得有评估指标——任务完成率、平均耗时、token消耗、人工介入率。没有评估，优化就是盲人摸象。

第四，人机协作是长期形态。完全自动化的多智能体系统在可预见的未来都很难做到100%可靠，人机协作才是务实的选择。设计系统时要把"人"当成系统的一部分，而不是外部的干预者。

最后分享一个我常用的小技巧：在开发阶段，给每个agent加一个"debug模式"，让它输出自己的思考过程。这个模式在生产环境关掉，但在调试时能帮你看清agent到底在想什么。很多问题看一眼思考过程就明白了，比看结果猜原因高效得多。

这个方向还在快速演进，我上面讲的很多东西可能过几个月就有更好的方案。但底层的那些原则——分层、约束、可观测、成本控制——我觉得短期内不会变。把这些打扎实了，具体用什么框架、什么模型，都是可以替换的细节。