企业官网建设流程全解析

1. 从"agency-agents"这个名字说起：一个被低估的架构命题

第一次看到agency-agents这个命名，我的直觉是：这大概率不是一个普通的工具库，而是一个关于"代理机构"或"代理层"的抽象设计。拆开来看，agency指向的是"代理、中介、机构"这层语义，agents则是复数形式的"代理者、执行体"。合在一起，它描述的是一种多代理协作的组织形态——不是单个 agent 单打独斗，而是一群 agent 在一个"机构"框架下各司其职、互相配合。

这个命名方式本身就透露了设计者的意图：它要解决的不是"如何造一个聪明的 agent"，而是"如何让一群 agent 像一家公司一样运转"。这两件事的难度完全不在一个量级上。单个 agent 的核心是提示词工程和工具调用，而多 agent 协作的核心是角色划分、任务分发、状态同步、冲突消解——本质上是一套组织管理问题。

我在实际接触这类架构时踩过最大的一个坑，就是一开始把它当成"多个 agent 并行跑"来理解。并行只是表象，真正难的是串行依赖下的上下文传递。比如一个 agent 负责调研、一个负责写作、一个负责审核，如果调研 agent 的输出格式和写作 agent 的输入预期对不上，整个链条就断了。agency-agents这类项目要处理的，恰恰是这些"接口对齐"的脏活累活。

这篇文章适合谁看？如果你正在做多 agent 系统、想理解代理协作的架构设计、或者单纯对"agency-agents"这个方向好奇，那接下来的内容会从命名逻辑、核心机制、实操搭建、踩坑排查几个角度把它讲透。我会尽量用从业者之间聊天的口吻，把那些文档里不会写的经验摊开来讲。

2. 拆解"代理机构"的核心机制：角色、路由与状态

2.1 为什么是"机构"而不是"团队"

agency这个词选得很讲究。团队（team）强调的是成员之间的平等协作，而机构（agency）强调的是委托-代理关系。在 agency 模型里，通常存在一个"委托方"（可能是用户，也可能是上层调度器）和一个"代理方"（执行具体任务的 agent 群体）。这种关系天然带有层级和职责边界。

我理解这个设计的价值在于：它把"谁来决定做什么"和"具体怎么做"分开了。委托方只关心目标和结果，代理方负责拆解和执行。这种分离带来的好处是，当任务复杂度上升时，你不需要让每个 agent 都理解全局，只需要让调度层理解全局即可。这跟现实中一家公司运作的逻辑一模一样——老板不需要知道每个员工的具体操作，只需要知道目标能不能达成。

从工程实现角度看，这种分层意味着系统里至少有两类组件：调度器（orchestrator）和执行器（executor）。调度器负责解析任务、分配角色、汇总结果；执行器负责在各自领域内完成具体工作。agency-agents如果是一个完整框架，这两层必然是它的骨架。

2.2 角色路由：任务怎么找到对的 agent

多 agent 系统里最容易被低估的环节就是路由。你有一堆 agent，每个擅长不同的事，来了一个任务，怎么决定交给谁？常见做法有三种：

• 静态映射：任务类型直接对应固定 agent，简单但僵硬，任务稍微变个形就匹配不上。
• 关键词匹配：根据任务描述里的关键词选 agent，实现快，但容易误判，尤其是任务描述模糊的时候。
• 语义路由：用向量相似度或轻量模型判断任务意图，再选 agent，准确率高但引入额外开销。

我在实际项目里最常用的是混合策略：先用关键词做粗筛，缩小候选范围，再用语义相似度做精排。这样既控制了延迟，又保证了准确率。举个具体例子，假设你有"数据清洗 agent""图表生成 agent""报告撰写 agent"三个执行体，来了一个任务叫"把这份销售数据整理一下并出个图"，关键词粗筛会同时命中"数据"和"图"，候选集是前两个，语义精排再根据整体意图判断主任务是清洗还是可视化。

提示：路由层一定要留"兜底 agent"。当所有匹配分数都低于阈值时，交给一个通用 agent 处理，而不是直接报错。这个细节能极大提升系统的鲁棒性。

2.3 状态同步：多 agent 协作里最脏的活

如果说路由是"派活"，那状态同步就是"对账"。多个 agent 协作时，每个 agent 都有自己的上下文和中间产物，怎么保证它们看到的是同一份"事实"？

我的经验是：不要试图让所有 agent 共享全部状态。共享全部状态会导致上下文爆炸，而且一个 agent 的中间错误会污染所有人。正确做法是维护一个共享黑板（blackboard），只放经过确认的关键信息，比如任务目标、已完成的里程碑、最终产物。每个 agent 的私有中间状态自己管，需要交换时通过黑板显式写入。

这里有个实操细节：黑板上的每条信息都要带来源标记和时间戳。当两个 agent 对同一件事给出不同结论时，你能快速定位是谁在什么时候写的，方便排查。我见过太多项目因为黑板上信息互相覆盖，最后连"这个结论是谁下的"都查不出来。

3. 从零搭一个 agency-agents 骨架：选型与落地

3.1 技术选型的三个决策点

动手之前，有三个选型问题必须先想清楚，否则后面会反复返工。

第一个决策：agent 之间怎么通信？常见方案有函数调用、消息队列、HTTP 接口。函数调用最简单，适合同进程内的轻量协作；消息队列适合异步、解耦的场景，但引入运维复杂度；HTTP 接口适合跨服务、跨语言的场景，但延迟高。我的建议是：原型阶段用函数调用，生产阶段按需升级。别一上来就上消息队列，那是给自己找麻烦。

第二个决策：状态存哪里？内存、Redis、数据库都行。内存最快但重启即丢，Redis 适合需要跨进程共享的中间状态，数据库适合需要持久化的最终产物。我通常的组合是：运行态用内存，共享态用 Redis，归档态用数据库。

第三个决策：调度是同步还是异步？同步调度逻辑简单，但一个 agent 卡住整个链条就停了；异步调度吞吐高，但错误处理和顺序保证复杂。对于大多数场景，我推荐同步为主、异步为辅——主流程同步保证可预测性，耗时操作（比如调用外部服务）异步化。

3.2 一个最小可运行的骨架

下面这个骨架是我在多个项目里反复打磨出来的，去掉了业务逻辑，只保留 agency-agents 的核心结构。用 Python 写，因为它的表达力足够清晰。

class Blackboard: """共享黑板：只存经过确认的关键信息""" def __init__(self): self._data = {} def write(self, key, value, source, timestamp): self._data[key] = { "value": value, "source": source, "timestamp": timestamp } def read(self, key): return self._data.get(key) class Agent: """执行器基类：每个 agent 只关心自己的领域""" def __init__(self, name, capability): self.name = name self.capability = capability def can_handle(self, task): # 子类实现具体的匹配逻辑 raise NotImplementedError def execute(self, task, blackboard): raise NotImplementedError class Orchestrator: """调度器：负责路由、分发、汇总""" def __init__(self, agents): self.agents = agents self.blackboard = Blackboard() def route(self, task): candidates = [a for a in self.agents if a.can_handle(task)] if not candidates: return self._fallback_agent() # 简单起见取第一个，实际项目里这里做精排 return candidates[0] def run(self, task): agent = self.route(task) result = agent.execute(task, self.blackboard) self.blackboard.write("last_result", result, agent.name, "now") return result

这个骨架的关键设计点在于：Agent 只暴露can_handle和execute两个方法。前者用于路由判断，后者用于实际执行。这种极简接口让新增 agent 的成本极低——你只需要实现这两个方法，不用改调度器。

3.3 路由策略的具体实现

上面的route方法我故意写得很简陋，因为路由策略值得单独展开。实际项目里我会这样实现：

def route(self, task): # 第一层：关键词粗筛 keyword_hits = [] for agent in self.agents: score = self._keyword_score(task, agent.capability) if score > 0: keyword_hits.append((agent, score)) if not keyword_hits: return self._fallback_agent() # 第二层：语义精排 if len(keyword_hits) > 1: keyword_hits.sort( key=lambda x: self._semantic_score(task, x[0]), reverse=True ) return keyword_hits[0][0]

_keyword_score做的是词面匹配，_semantic_score做的是向量相似度。两层过滤的好处是：第一层把候选集从几十个降到几个，第二层只在这几个上做昂贵的语义计算，整体延迟可控。

注意：语义精排用的向量模型不要选太大的。我试过用大模型做路由，准确率确实高，但每次路由要几百毫秒，整个系统的响应速度被拖垮。后来换成小模型，准确率只降了几个百分点，延迟降了一个数量级。

4. 实测中暴露的四个典型问题与排查链路

4.1 问题一：agent 之间"踢皮球"

现象：任务在多个 agent 之间反复流转，谁也不真正执行，最后超时。

排查链路：我先在调度器里加了日志，记录每次路由的输入和输出。发现任务 A 被路由到 agent1，agent1 判断"这不是我的活"返回给调度器，调度器又路由到 agent2，agent2 也拒绝，如此循环。

根因：can_handle的判断逻辑太严格，每个 agent 都只认自己最擅长的任务，稍微偏一点就拒绝。而调度器的路由又没有"排除已尝试 agent"的机制。

修复方案：两处改动。一是放宽can_handle的判断，从"精确匹配"改成"相关即可"；二是在调度器里维护一个tried_agents集合，路由时排除已经尝试过的 agent，避免死循环。

def run(self, task): tried = set() while True: agent = self.route(task, exclude=tried) if agent is None: raise RuntimeError("无可用 agent") tried.add(agent.name) result = agent.execute(task, self.blackboard) if result is not None: return result

4.2 问题二：黑板上信息互相覆盖

现象：最终产物里混入了中间过程的脏数据，结果不可信。

排查链路：我打印了黑板的完整写入历史，发现多个 agent 用了相同的 key 写数据，后写的覆盖了先写的。比如 agent1 写result是中间结果，agent2 写result是最终结果，但 agent3 又写了一次result把 agent2 的覆盖了。

根因：黑板 key 的命名没有规范，大家随手起名，撞车了。

修复方案：强制 key 命名规范，格式为{agent_name}:{purpose}。同时给黑板加一个"只允许同源覆盖"的约束——如果新写入的 source 和已有记录的 source 不同，且 key 不是"追加型"，就拒绝写入并告警。

def write(self, key, value, source, timestamp): if key in self._data and self._data[key]["source"] != source: if not key.endswith(":append"): raise ValueError(f"key {key} 已被 {self._data[key]['source']} 占用") self._data[key] = {"value": value, "source": source, "timestamp": timestamp}

4.3 问题三：某个 agent 拖慢整体

现象：整个流程的耗时几乎等于最慢那个 agent 的耗时，其他 agent 都在等。

排查链路：我给每个 agent 的execute加了计时，发现某个 agent 平均耗时是其他的十倍。进一步看，它在做一次外部 API 调用，而那个 API 偶尔会慢到几秒。

根因：同步调度下，一个慢 agent 会阻塞整条链。

修复方案：对耗时操作加超时和降级。超时时间设为该 agent 历史 P95 耗时的 1.5 倍，超时后返回一个降级结果（比如"该步骤跳过"），让流程继续。同时把这类 agent 标记为"可异步"，在调度器里对它们做并行化处理。

4.4 问题四：新增 agent 后老功能回归

现象：加了一个新 agent，结果原本正常的任务开始走错路由。

排查链路：对比新旧路由日志，发现新 agent 的can_handle写得太宽泛，把原本属于老 agent 的任务也抢走了。

根因：新 agent 的能力描述和已有 agent 重叠，而路由策略是"取第一个匹配"，新 agent 注册顺序靠前就抢走了。

修复方案：路由从"取第一个"改成"取分数最高的"，并且给每个 agent 的能力描述加"专精度"权重。专精度高的 agent 在重叠区域优先。这个改动之后，新增 agent 只要描述准确，就不会误抢。

5. 让 agency-agents 真正好用的几个进阶思路

5.1 给 agent 加"记忆"而不是"上下文"

很多人做多 agent 系统时，喜欢把完整对话历史塞给每个 agent，觉得这样它们"知道得多"。实测下来这是灾难——上下文越长，agent 越容易迷失重点，而且 token 成本飙升。

我的做法是给每个 agent 配一个结构化记忆，只存三类信息：它自己做过什么、它从黑板读到过什么、它的能力边界是什么。这三类信息用固定格式存，每次调用时按需注入，而不是全量塞。这样 agent 的"视野"是干净的，决策也更稳定。

5.2 用"契约"约束 agent 之间的接口

多 agent 系统最容易崩的地方是接口。agent1 输出一个 JSON，agent2 期望的是另一种结构，运行时才报错。我的经验是：在开发阶段就把接口契约定死，用 schema 校验每个 agent 的输入输出。Python 里可以用 pydantic，定义好每个 agent 的InputSchema和OutputSchema，运行时自动校验。这样接口不匹配的问题在开发阶段就暴露了，不会留到线上。

from pydantic import BaseModel class ResearchOutput(BaseModel): topic: str findings: list[str] confidence: float class WritingInput(BaseModel): topic: str findings: list[str]

5.3 监控：别等出问题才看日志

agency-agents 这类系统，出问题时往往不是单点故障，而是多个 agent 的连锁反应。所以监控要覆盖三个层面：单个 agent 的成功率与耗时、路由的命中分布、黑板的写入冲突次数。这三个指标一旦有异常，基本能定位到问题区域。

我习惯在调度器里埋一个轻量的指标收集器，每次路由和执行都记一笔，定期汇总。不需要上重型监控系统，一个内存计数器加定期打印就够了。关键是要有，而不是等线上炸了才去翻日志。

提示：路由命中分布这个指标特别有用。如果某个 agent 的命中率突然从 30% 掉到 5%，说明要么它的能力描述过时了，要么有新的 agent 在抢它的活。这两种情况都值得立刻查。

5.4 什么时候不该用多 agent

最后说个反直觉的：不是所有任务都适合拆成多 agent。我见过一些项目，明明一个 agent 加几个工具就能搞定的事，非要拆成五个 agent 协作，结果复杂度上去了，效果反而更差。

判断标准很简单：如果任务能被清晰地拆成几个独立且串行的子任务，每个子任务有明确的输入输出，那多 agent 是合适的。如果任务本身是高度耦合的、需要频繁来回交互的，那单 agent 加工具调用往往更高效。agency-agents的价值在于处理"组织级"的复杂度，而不是为了多 agent 而多 agent。

我在实际项目里的体会是，从单 agent 起步，当它开始"什么都干但什么都干不精"的时候，再考虑拆成 agency 结构。这个时机点通常是：单 agent 的提示词超过两千字，或者它需要同时处理三种以上不同类型的子任务。到了这个阶段，拆分带来的收益才会大于复杂度成本。