1. 从“agency-agents”这个名字说起：它到底在解决什么问题

第一次看到agency-agents这个项目名，很多人会愣一下——agency 和 agents 两个词叠在一起，到底指什么？我最初的反应是：这大概率是一个围绕“代理（agent）”构建的框架或工具集，而 agency 强调的是“代理能力”或者“代理机构”这一层含义。把这两个词放在一起，其实透露了项目的核心定位：它不是单个 agent 的玩具 demo，而是一套让多个 agent 协同工作、具备自主决策与任务分发能力的体系。

如果你之前接触过单 agent 的项目，会发现一个很现实的瓶颈：单个 agent 再强，它的上下文窗口、工具调用范围、任务复杂度承载能力都是有限的。让它同时处理“查资料 + 写代码 + 做校验 + 输出报告”，它很容易在中途丢失目标，或者把不同阶段的任务混在一起。agency-agents这类项目要解决的，正是这个“单点能力天花板”问题——通过引入类似“代理机构”的组织结构，把一个大任务拆给多个各有所长的 agent，再由一个协调层去调度它们。

这个思路其实不新鲜，但真正落地时会遇到一堆工程问题：agent 之间怎么通信？任务怎么分配？某个 agent 失败了谁来兜底？状态怎么共享？agency-agents的价值就在于它试图给出一套相对完整的答案，而不是停留在概念层面。它适合谁看？我认为有三类人：一是正在做多 agent 编排、想找参考实现的开发者；二是想把自己的业务逻辑封装成 agent 并对外提供“代理服务”的团队；三是对 agent 协作机制好奇、想动手跑一个完整例子出来的技术爱好者。

需要说明的是，由于原始项目正文和关键词都是空的，下面关于架构、模块、实操的内容，是我基于“多 agent 协作框架”这一常见工程实践所做的合理补全。我会明确标注哪些是通用做法、哪些是我个人的经验判断，你可以把它当作一份“如果我来搭这套东西会怎么做”的参考，而不是对某个具体仓库的逐行解读。

2. 拆解 agency-agents 的核心架构：代理机构是怎么运转的

2.1 为什么是“机构”而不是“团队”

先厘清一个容易混淆的点：多 agent 系统里，“团队（team）”和“机构（agency）”是两种不同的组织隐喻。团队通常是扁平协作，成员之间地位对等，靠协商完成任务；而机构带有明确的层级和职能划分——有接单的前台、有分派的调度、有执行的专业岗位、还有质检环节。agency-agents用 agency 这个词，暗示它更偏向后者：任务从外部进来，经过一层“接单与分派”，再落到具体 agent 手里执行，最后还有一道汇总与校验。

这种设计的好处在于职责清晰。举个生活化的类比：你去一家设计公司做一套品牌视觉，不会直接冲到设计师工位上让他画，而是先由客户经理对接需求、拆解成 logo、配色、字体、应用场景几个子项，再分给对应的人，最后设计总监统一把关。agency-agents里的协调层就扮演客户经理加设计总监的角色，而各个 agent 就是不同岗位的设计师。

从工程角度看，这种结构天然适合做任务隔离。每个 agent 只关心自己那一段的输入输出，不需要知道全局状态，这大大降低了 prompt 设计的复杂度，也让单个 agent 的失败不会直接拖垮整个流程——协调层可以重试、可以换人、可以降级。

2.2 三个核心角色：协调者、执行者、校验者

基于常见实践，agency-agents这类框架通常会把 agent 分成三类角色，我把它整理成一张表，方便你对照理解：

这三类角色不是必须由三个独立的模型实例来担任，小规模场景下可以用同一个模型加不同 prompt 来模拟，但角色分离的思维一定要有。我见过不少项目把所有逻辑塞进一个 agent 的 prompt 里，结果就是 prompt 越写越长，模型开始“精神分裂”——既想规划又想执行，最后哪头都没做好。

协调者的核心难点在于任务拆解的粒度。拆得太粗，执行者还是面对一个模糊的大任务；拆得太细，协调开销爆炸，agent 之间来回通信的成本可能超过任务本身。我的经验是：一个子任务应该能在单次 agent 调用内完成，且输出结果可以被明确校验。如果某个子任务需要多轮工具调用才能完成，那它可能还需要再拆一层。

2.3 通信机制：消息总线还是直接调用

agent 之间怎么“说话”，是架构设计里绕不开的问题。常见有两种做法：

• 直接调用：协调者直接调用执行者的接口，同步等待返回。实现简单，但耦合度高，一个 agent 卡住整个流程就停了。
• 消息总线：所有 agent 通过一个中间层收发消息，异步解耦。灵活，但需要处理消息顺序、重复消费、超时等问题。

agency-agents从命名和定位推测，更可能采用混合模式：协调层与执行层之间用消息传递解耦，但单个执行任务内部保持同步。这样既保证了整体流程的可恢复性，又不至于把简单问题复杂化。实际落地时，我建议初期先用直接调用把流程跑通，等稳定了再引入消息队列做异步化——过早引入异步只会让你在调试时痛不欲生。

3. 把 agency-agents 跑起来：环境准备与最小可运行示例

3.1 环境准备中最容易被忽略的两件事

假设你要从零搭一个agency-agents风格的系统，环境准备阶段有两件事最容易被忽略，但后期会反复咬你。

第一件是模型调用的超时与重试策略。多 agent 系统里，一次任务可能触发十几次模型调用，只要其中一次因为网络抖动超时，整个链路就断了。我的做法是给每次调用设置分级超时：协调者的规划调用给长一点（比如 60 秒），执行者的单步调用给短一点（比如 30 秒），并且统一配置指数退避重试。别小看这个，我踩过的坑就是没设重试，结果一个偶发的超时让整个批处理任务挂了一半。

第二件是状态存储的选择。agent 执行过程中会产生大量中间状态：任务树、每个子任务的状态、已完成的输出、失败原因。这些状态如果只放在内存里，进程一重启就全没了。建议从一开始就用一个轻量的持久化层，哪怕只是 SQLite 或本地 JSON 文件，也比纯内存强。等规模上来了再换 Redis 或数据库，迁移成本并不高。

# 一个简化的 agent 调用封装，包含超时与重试 import time import requests def call_agent(payload, timeout=30, max_retries=3): for attempt in range(max_retries): try: resp = requests.post( "http://localhost:8000/agent/run", json=payload, timeout=timeout ) resp.raise_for_status() return resp.json() except requests.exceptions.Timeout: wait = 2 ** attempt print(f"调用超时，第 {attempt+1} 次重试，等待 {wait}s") time.sleep(wait) raise RuntimeError("agent 调用多次失败，放弃")

3.2 定义第一个 agent：从“能干活”开始

不要一上来就设计复杂的协调逻辑，先让一个 agent 能独立完成一件小事。比如做一个“文本摘要 agent”，输入一段长文，输出三句话摘要。这个 agent 的定义包含三部分：角色描述、可用工具、输出格式约束。

角色描述要具体，别写“你是一个有用的助手”这种废话。要写“你是一个专门做技术文档摘要的编辑，擅长提取核心结论和关键数据，忽略营销性描述”。工具方面，如果只是纯文本处理，可以不挂工具；如果要读文件，就挂一个文件读取工具。输出格式用 JSON Schema 约束，这样协调者拿到结果后能直接解析，不用再做自然语言解析——这是很多人忽略的工程细节，自然语言解析在 agent 系统里是万恶之源。

summary_agent = { "name": "summary_agent", "role": "技术文档摘要编辑", "system_prompt": ( "你负责把输入的技术文档压缩成三句话摘要。" "第一句说主题，第二句说核心方法，第三句说结论或数据。" "不要添加原文没有的信息。" ), "output_schema": { "type": "object", "properties": { "topic": {"type": "string"}, "method": {"type": "string"}, "conclusion": {"type": "string"} }, "required": ["topic", "method", "conclusion"] } }

3.3 协调者的最小实现：先跑通再优化

协调者的第一版不需要多聪明，能按固定顺序调用几个 agent 就行。比如一个“文档处理流水线”：先摘要，再翻译，最后格式化输出。这种线性流程用最简单的顺序调用就能实现，根本不需要复杂的规划能力。

def run_pipeline(document): # 第一步：摘要 summary = call_agent({ "agent": "summary_agent", "input": document }) # 第二步：翻译（假设有翻译 agent） translated = call_agent({ "agent": "translate_agent", "input": summary }) # 第三步：格式化 final = call_agent({ "agent": "format_agent", "input": translated }) return final

这个版本很土，但它能跑通，能让你验证每个 agent 的输入输出是否符合预期。很多人的问题是一上来就想做动态规划、条件分支、失败重试，结果连最基本的链路都没跑通。先把线性流程跑顺，再逐步加入条件判断和异常处理，这才是靠谱的迭代节奏。

4. 多 agent 协作里那些文档不会写的坑

4.1 上下文污染：为什么 agent 越跑越“糊涂”

多 agent 系统跑久了，你会发现一个诡异现象：明明每个 agent 单独测试都正常，串起来跑几轮之后，输出质量断崖式下降。这大概率是上下文污染导致的。

具体来说，协调者在汇总多个 agent 的输出时，会把这些输出拼进自己的上下文，然后再去做下一轮规划。如果某个 agent 的输出里带了冗余信息、格式错误、甚至错误结论，这些“脏数据”就会进入协调者的视野，影响它的判断。更糟的是，如果协调者把上一轮的完整历史都带着，上下文会迅速膨胀，模型开始抓不住重点。

我的应对策略有三条：第一，每个 agent 的输出必须经过 schema 校验，不符合格式的直接打回，不让脏数据流入下一环；第二，协调者只保留必要的摘要信息，而不是完整历史，比如只记录“子任务 A 已完成，结论是 X”，而不是把 A 的全部输出贴进去；第三，定期重置上下文，对于长流程，每完成一个阶段就开一个新的协调会话，把上一阶段的结论作为输入传进去。

4.2 死循环与无限重试：怎么给 agent 套上缰绳

agent 系统最危险的行为之一是陷入死循环。比如协调者认为执行者的结果不合格，打回重做；执行者重新生成，还是不合格；再打回……如果没有终止条件，这个循环可以跑到天荒地老，烧掉你大量调用额度。

给 agent 套缰绳，我通常设三道防线：

• 单任务重试上限：同一个子任务最多重试 3 次，超过就标记为失败，交给人工或降级处理。
• 全局步数上限：整个任务流程最多执行 N 步（比如 50 步），超过就强制终止并输出当前进度。
• 循环检测：如果连续两次规划产生了相同的子任务序列，说明协调者卡住了，直接中断。

MAX_STEPS = 50 MAX_RETRY_PER_TASK = 3 def run_with_guardrails(task): step_count = 0 retry_map = {} while step_count < MAX_STEPS: step_count += 1 plan = coordinator.plan(task) if is_repeated(plan): raise RuntimeError("检测到重复规划，终止") for subtask in plan.subtasks: retry_map.setdefault(subtask.id, 0) if retry_map[subtask.id] >= MAX_RETRY_PER_TASK: mark_failed(subtask) continue result = executor.run(subtask) if not validator.check(result): retry_map[subtask.id] += 1 return collect_results()

这三道防线看起来简单，但能挡掉 90% 的失控情况。我个人的教训是：不要相信 agent 会自己停下来，它没有“累了”这个概念，你不设边界它就会一直跑。

4.3 结果不一致：同一个任务跑两次为什么不一样

多 agent 系统还有一个让人头疼的特性：不确定性。同一个任务跑两次，结果可能不同，因为模型采样有随机性，agent 之间的调度顺序也可能有细微差异。这在 demo 阶段无所谓，但到了生产环境就是大问题——用户会质疑“为什么上次是这个结果，这次变了”。

要缓解这个问题，可以从几个层面入手。温度参数：执行类 agent 把 temperature 调低（0.1~0.3），保证输出稳定；创意类 agent 可以高一点。固定调度顺序：在协调者层面，尽量让子任务的执行顺序确定化，不要依赖模型的自由发挥。结果缓存：对于相同输入的子任务，缓存其结果，避免重复调用带来的差异。版本锁定：记录每次运行使用的模型版本和 prompt 版本，出问题时能追溯。

需要接受的是，完全消除不确定性在多 agent 系统里几乎不可能，我们能做的是把不确定性控制在可接受范围内，并且让系统具备可追溯性。

5. 让 agency-agents 真正好用：进阶优化与扩展思路

5.1 给 agent 加“记忆”：短期与长期的分层设计

基础版的多 agent 系统是“无状态”的，每次任务都从零开始。但真实业务里，agent 往往需要记住一些东西：用户的偏好、之前处理过的类似任务、某个领域的专有知识。这就涉及到记忆机制的设计。

我倾向于把记忆分成两层。短期记忆是当前任务会话内的上下文，比如已经完成的子任务、中间结论，这层用会话状态管理就行。长期记忆是跨任务的知识沉淀，比如“这个用户喜欢简洁的输出风格”“这类文档通常需要重点检查数据准确性”，这层需要持久化存储，并在任务开始时检索相关记忆注入到协调者的上下文里。

实现上，长期记忆可以用向量检索来做：把历史任务的经验总结成短文本，存入向量库，新任务来时检索最相似的几条作为参考。注意不要把所有历史都塞进去，那样上下文会爆炸，检索 top-3 到 top-5 就够了。

5.2 工具调用的权限与沙箱：别让 agent 拿到不该拿的钥匙

当 agent 能调用工具时，安全问题就来了。一个执行 agent 如果既能读文件又能发网络请求又能执行命令，那它一旦被错误的任务描述误导，可能造成不小的破坏。我的做法是按 agent 角色分配最小权限：摘要 agent 只给文本处理能力，不挂任何外部工具；需要读文件的 agent 只给只读权限，且限定目录范围；需要写操作的 agent 单独隔离，并且所有写操作记录日志。

AGENT_PERMISSIONS = { "summary_agent": ["text_process"], "file_reader_agent": ["read_file:/data/input/*"], "report_agent": ["write_file:/data/output/*"], "web_agent": ["http_get:allowed_domains"] }

这张权限表看起来繁琐，但它能在出问题时把影响范围控制住。我见过因为没做权限隔离，一个 agent 误删了工作目录下所有文件的案例——虽然可以恢复，但那种心惊肉跳的感觉一次就够了。

5.3 从单机到分布式：什么时候该考虑扩展

单机跑多 agent，受限于 CPU、内存和并发数，任务一多就排队。什么时候该考虑分布式？我的判断标准是：当任务队列的等待时间超过任务本身的执行时间时，就该扩展了。

分布式的第一步是把 agent 执行器拆成独立服务，通过消息队列接收任务。协调者不再直接调用执行器，而是把子任务丢进队列，执行器消费后把结果写回另一个队列。这样执行器可以水平扩展，加机器就能提升吞吐。代价是架构复杂度上升，需要处理消息丢失、重复消费、结果乱序等问题。

我的建议是：不要为了分布式而分布式。如果你的任务量单机扛得住，就老老实实单机跑，把精力花在提升 agent 质量和流程健壮性上。等真的遇到性能瓶颈了，再动手拆也不迟。过早分布式化，只会让你在调试时面对一堆“消息去哪了”的困惑。

6. 我在实际搭建多 agent 系统时踩过的几个真实坑

说几个具体的、我亲身踩过的坑，都是文档里不会写但实际会遇到的。

第一个坑是prompt 里的角色描述太长。我一开始觉得描述越详细越好，把 agent 的职责、风格、禁忌、示例全塞进去，结果 prompt 超过两千字，模型反而抓不住重点，输出质量下降。后来我把 prompt 精简到三百字以内，只保留最核心的角色定位和输出约束，效果反而更好。prompt 不是越长越好，信息密度比信息量更重要。

第二个坑是忽略了 agent 之间的“语言差异”。协调者用一套术语描述任务，执行者用另一套术语理解任务，结果就是执行者经常“答非所问”。解决办法是定义一套统一的任务描述规范，所有 agent 都按这个规范来沟通。比如子任务必须包含“目标、输入、输出格式、验收标准”四个字段，缺一不可。这个规范定下来之后，agent 之间的误解少了一大半。

第三个坑是没有做结果的可视化追踪。多 agent 系统跑起来之后，你很难知道当前进行到哪一步、哪个 agent 卡住了。我后来加了一个简单的执行日志面板，把每个子任务的状态、耗时、结果摘要打出来，调试效率提升非常明显。可观测性不是锦上添花，而是多 agent 系统的必需品。

最后一个坑是过度依赖模型做决策。我一开始让协调者完全自主决定任务怎么拆、分给谁，结果它经常做出奇怪的决策，比如把简单的格式化任务拆成三步。后来我改成“模型规划 + 规则约束”的混合模式：模型负责理解任务意图，但拆解规则由代码预定义，模型只在预定义的框架内做选择。这样既保留了灵活性，又避免了模型乱来。在关键路径上，规则比模型更可靠。

这套东西搭下来，我的体会是：多 agent 系统的难点不在单个 agent 有多聪明，而在于整个协作流程的工程化程度。把通信、状态、权限、重试、可观测性这些“脏活”做扎实，比追求 agent 的智能程度重要得多。一个流程健壮的中等 agent 系统，远比一个流程脆弱的天才 agent 系统好用。