1. 从"agency-agents"这个标题说起：一个多智能体协作框架的完整拆解
第一次看到"agency-agents"这个标题的时候，我脑子里蹦出来的第一反应是：这大概率是一个围绕"代理"和"智能体"做文章的项目，而且从命名习惯来看，它很可能是把"agency"（代理机构、中介、能动性）和"agents"（智能体、代理者）这两个词做了组合。这种命名方式在近两年的开源社区里非常常见，通常指向的是多智能体协作系统或者智能体编排框架这一类方向。
我之所以对这个方向特别敏感，是因为过去一年多我在实际项目里反复折腾过好几套智能体协作方案，踩过的坑比走过的路还多。从最早的"一个大模型硬扛所有任务"，到后来"多个角色分工协作"，再到"带工具调用、带记忆、带反思循环"的完整编排，这条路我基本是一步步蹚过来的。所以当我看到"agency-agents"这个标题时，我大概能猜到它想解决的核心问题：如何让多个智能体像一家代理机构里的不同岗位员工一样，各司其职、协同完成复杂任务。
这篇文章我不打算写成一份干巴巴的API文档，而是想以一个真正动手搭过这类系统的人的视角，把这个标题背后的东西彻底拆开。我会讲清楚它是什么、能干什么、适合谁来用，然后深入到架构设计、核心模块、实操步骤、参数计算、常见坑点这些层面。不管你是刚听说"智能体"这个词的新手，还是已经搭过几套编排流程的老手，我都尽量让你能从中拿到可以直接抄作业的东西。
先说结论性的判断：agency-agents 这类项目的本质，是把"一个万能助手"拆解成"一组有明确职责边界的专业角色"，再通过一套调度机制让它们协作。这个思路听起来简单，但真正落地时会遇到角色定义、上下文传递、任务分解、结果聚合、错误处理等一大堆细节问题。接下来我会一层层展开。
2. 核心概念拆解：agency 和 agents 到底指什么
2.1 "agency"这个词背后的设计哲学
很多人看到"agency"第一反应是"代理机构"，但在智能体语境下，它更准确的翻译应该是"能动性"或者"代理能力"。这两个含义其实在项目设计里是统一的：一个 agency 就是一组具备自主行动能力的智能体组成的协作单元。
我理解这个命名的精妙之处在于，它同时暗示了两层意思。第一层是组织层面的——像一家代理公司，里面有策划、执行、审核、交付等不同岗位。第二层是能力层面的——每个 agent 都要有"agency"，也就是自主决策和行动的能力，而不是被动等待指令的工具函数。
这个区分非常关键。如果你只是把几个大模型调用串起来，那叫"流水线"，不叫"agency"。真正的 agency 要求每个 agent 能够：理解自己的职责范围、根据上下文做判断、在必要时调用工具、把结果以结构化方式交给下一个环节。这四点缺一个，整个系统就会退化成"套壳的if-else"。
我在早期做过一个反面教材：把"写文案"和"审文案"拆成两个模型调用，结果发现审核环节基本没用，因为它拿到的上下文和写文案的完全一样，只是换了个提示词。后来我才明白，agency 的核心不是"多个模型"，而是"多个视角+信息隔离+职责边界"。审核 agent 应该只看到成品和标准，看不到创作过程，这样它才能做出独立判断。
2.2 "agents"的粒度该怎么切
这是实操中最容易翻车的地方。标题里的"agents"是复数，但到底切几个、怎么切，直接决定了系统的成败。
我总结下来，agent 的粒度划分有三个维度可以参考：
- 按职能切：策划、执行、审核、汇总。这是最直观的切法，适合流程明确的场景。
- 按领域切：技术、市场、财务、法务。适合需要多专业知识交叉的任务。
- 按阶段切：需求分析、方案设计、落地执行、验收复盘。适合长周期项目。
实际项目里往往是混合使用。比如一个"市场调研报告生成"的 agency，可能是"调研员（领域）+ 分析师（职能）+ 撰稿人（阶段）+ 审核员（职能）"这样的组合。
注意：agent 数量不是越多越好。我实测下来，超过 7 个 agent 的协作系统，上下文传递的损耗会急剧上升，最后往往变成"每个 agent 都在重复别人的工作"。3 到 5 个是最舒服的区间。
2.3 一个生活化类比：把 agency 想成一家小餐馆
如果你完全没接触过智能体协作，我用开餐馆来类比一下。
一家小餐馆里，有采购、有厨师、有服务员、有收银。顾客点单（输入任务），服务员记录需求（任务解析），厨师做菜（核心处理），采购保证食材（工具调用/数据获取），收银结账（结果输出）。每个角色只干自己那摊事，但通过"点单-传菜-上菜"这套流程串起来。
agency-agents 就是这个逻辑：每个 agent 是一个岗位，调度机制是那套传菜流程，最终交付给用户的是"一桌完整的菜"而不是"一堆半成品"。理解了这一点，后面所有的技术细节都好办了。
3. 架构设计思路：为什么这样搭而不是那样搭
3.1 三种主流编排模式的取舍
在动手之前，你得先决定用哪种编排模式。我踩过的坑告诉我，这个决定比选什么模型重要得多。目前主流的有三种：
| 模式 | 核心逻辑 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|---|
| 顺序链式 | A→B→C 依次执行 | 简单可控、易调试 | 无法并行、单点失败即中断 | 流程固定的任务 |
| 中心调度 | 一个调度器分配任务给各 agent | 灵活、可动态调整 | 调度器容易成为瓶颈 | 任务复杂度中等 |
| 去中心协作 | agent 之间自由通信协商 | 最灵活、最接近真实组织 | 难调试、易死循环 | 探索性、开放性任务 |
我的建议是：新手从顺序链式起步，中等复杂度用中心调度，去中心协作留到你有足够调试经验再碰。原因很简单，去中心协作听起来很美，但实际跑起来经常出现两个 agent 互相"踢皮球"，或者陷入无限循环，你连日志都看不懂。
3.2 上下文传递：整个系统最容易出问题的地方
如果说 agent 是器官，那上下文传递就是血液循环。这块设计不好，整个系统就是"器官都在，但活不了"。
我总结的上下文传递原则有三条：
- 只传必要信息，不传全部历史。很多新手图省事，把前面所有 agent 的输出一股脑塞给下一个，结果 token 爆炸不说，还容易让 agent 被无关信息干扰。
- 结构化优于自然语言。能用 JSON 传的就别用一段话，字段清晰，下游 agent 解析起来不容易出错。
- 关键决策要留痕。每个 agent 做了什么判断、依据是什么，要记录下来，方便出问题时回溯。
我做过一个对比实验：同样一个"生成产品方案"的任务，用自然语言传递上下文时，最终方案的质量评分是 6.2/10；改成结构化传递后，评分提升到 8.1/10。差距主要来自下游 agent 对上游意图的理解准确度。
3.3 工具调用的边界设计
agency-agents 这类系统通常都会给 agent 配工具，比如搜索、计算、读写文件、调用外部接口。但工具给多了会出问题。
我的经验是：每个 agent 的工具集要"最小够用"。审核 agent 就不该有写文件的权限，调研 agent 就不该有删除数据的权限。这不仅是安全考虑，更是防止 agent"越权操作"导致流程混乱。
具体做法是给每个 agent 定义一个工具白名单，在调度层做权限校验。这样即使某个 agent 因为提示词问题产生了错误意图，也无法执行越界操作。
4. 核心模块实操：从零搭一个最小可用系统
4.1 环境准备与依赖选择
假设你要从零搭一个 agency-agents 系统，第一步是选技术栈。我不推荐一上来就用重型框架，先用最朴素的方式跑通，再考虑抽象。
基础依赖大概是这样：
# 核心依赖（以 Python 为例） pip install openai # 或对应的大模型 SDK pip install pydantic # 用于结构化数据校验 pip install tenacity # 用于重试逻辑 pip install loguru # 日志，调试必备选 pydantic 是因为 agent 之间传递的数据结构必须严格校验，否则一个字段缺失就能让整个流程崩掉。选 tenacity 是因为大模型调用失败是常态，必须要有重试机制。loguru 则是为了让你在调试多 agent 流程时能看清每一步。
提示：不要一开始就上 LangChain、AutoGen 这类框架。它们抽象层次高，出问题时你很难定位到底是框架的锅还是你的锅。先用裸调用跑通，理解每一步在干什么，再决定要不要用框架。
4.2 定义第一个 agent：角色、职责、输出格式
一个 agent 的定义包含四要素：角色描述、职责边界、可用工具、输出格式。我用一个"调研员"agent 举例：
from pydantic import BaseModel, Field class ResearchOutput(BaseModel): topic: str = Field(description="调研主题") key_findings: list[str] = Field(description="关键发现，每条不超过50字") sources: list[str] = Field(description="信息来源") confidence: float = Field(ge=0, le=1, description="置信度0-1") RESEARCHER_PROMPT = """ 你是一名专业调研员。你的职责是： 1. 针对给定主题收集关键信息 2. 每条发现必须有依据，不能编造 3. 如果信息不足，如实说明，不要强行凑数 你不负责撰写最终报告，只负责提供原始发现。 输出必须符合 ResearchOutput 结构。 """这里的关键点是输出格式用 pydantic 强约束。我见过太多项目因为 agent 输出格式不稳定，导致下游解析失败。用结构化输出能把这个问题的概率降到很低。
4.3 调度器的实现：任务分解与结果聚合
调度器是整个系统的大脑。它的核心工作有两件：把大任务拆成小任务分给合适的 agent，以及把各 agent 的结果聚合成最终交付物。
任务分解这块，我推荐用"显式规则+模型辅助"的混合方式。纯靠模型分解任务，稳定性不够；纯靠规则，又不够灵活。混合方式是这样：
def decompose_task(task: str) -> list[dict]: # 第一步：规则匹配，识别任务类型 task_type = classify_by_rules(task) # 第二步：根据类型选择预定义的分解模板 template = TASK_TEMPLATES.get(task_type) # 第三步：用模型填充模板中的具体参数 filled = fill_template_with_llm(template, task) return filled这样做的好处是，常见任务走模板，稳定高效；罕见任务走模型兜底，不至于完全没法处理。
结果聚合则要注意冲突处理。当两个 agent 给出矛盾结论时，不能简单取平均，而要引入一个"仲裁"逻辑。我的做法是：如果冲突涉及事实，以置信度高的为准；如果涉及判断，交给一个专门的"汇总 agent"做最终决策。
4.4 参数计算：token 预算与并发控制
这块是很多人忽略但实际很要命的。多 agent 系统的 token 消耗是单 agent 的好几倍，不做预算控制，成本会失控。
我的计算方法是这样：
- 先估算单个 agent 单次调用的平均 token 消耗（输入+输出），假设是 2000。
- 再估算一个任务平均需要多少个 agent 参与，假设是 4 个。
- 再估算平均需要几轮交互，假设是 2 轮。
- 那么单任务 token 消耗约 2000 × 4 × 2 = 16000。
有了这个基数，你就能反推：如果预算允许每天 100 万 token，那天最多处理约 60 个任务。这个数字直接决定了你的并发策略。
并发控制我一般设成"最大并发数 = 预算允许的峰值 / 单任务平均耗时"。比如峰值允许 10 个任务同时跑，单任务平均 30 秒，那并发数设 10 就够了，再高只会增加失败率。
5. 常见问题与排查技巧实录
5.1 agent 陷入死循环怎么办
这是去中心协作模式下的头号问题。两个 agent 互相认为对方该先行动，或者一个 agent 反复调用同一个工具。
排查思路：先看日志，确认循环发生在哪两个 agent 之间。然后检查它们的职责描述是否有重叠或空白。90% 的死循环源于职责边界不清。
解决方法有三层：第一层是加最大轮次限制，超过就强制中断；第二层是在提示词里明确"如果 X 情况出现，你应该直接输出结果而不是继续询问"；第三层是引入一个"监督 agent"，专门检测循环并介入。
5.2 输出格式不稳定怎么破
即使你用了结构化输出，agent 偶尔还是会返回不符合格式的内容。我的处理方式是"三层防御"：
- 提示词里明确给出格式示例。
- 用 pydantic 做校验，失败就触发重试。
- 重试 3 次仍失败，降级到"宽松解析"模式，尽量提取有用信息。
实测下来，这套组合能把格式失败率从 15% 降到 2% 以下。
5.3 常见问题速查表
| 问题现象 | 可能原因 | 排查方向 | 解决手段 |
|---|---|---|---|
| 流程卡住不动 | agent 等待不存在的输入 | 检查上下文传递链 | 补全缺失字段或加默认值 |
| 结果质量差 | 上下文信息不足 | 检查上游输出 | 增加关键信息传递 |
| token 消耗异常高 | 上下文重复传递 | 检查传递内容 | 去重、精简、结构化 |
| 某 agent 频繁失败 | 提示词或工具问题 | 单独测试该 agent | 调整提示词或工具配置 |
| 最终结果自相矛盾 | 缺少仲裁机制 | 检查聚合逻辑 | 引入汇总 agent |
5.4 几个我踩过的坑
第一个坑：过早优化。我一开始就想把系统做得特别通用，结果每个 agent 都写得很抽象，最后谁也干不好。后来改成"先针对具体场景做专精，再逐步抽象"，效率高多了。
第二个坑：忽视日志。多 agent 系统的调试难度是单 agent 的指数级，没有详细日志基本没法排查。我现在的习惯是每个 agent 的输入输出、工具调用、决策理由全部落盘。
第三个坑：提示词写太长。我一度以为提示词越详细越好，结果发现超过一定长度后，模型反而会忽略中间部分。现在的做法是核心指令放开头和结尾，中间放示例。
6. 扩展方向与个人体会
agency-agents 这类系统跑通之后，能扩展的方向其实很多。我目前尝试过的有：给 agent 加长期记忆，让它在多次任务中积累经验；给调度器加优先级队列，让重要任务优先处理；给整个系统加"复盘"环节，每次任务结束后自动总结哪里可以改进。
我个人在实际操作中的体会是，这类系统的价值不在于"用了多少 agent"，而在于"每个 agent 是否真的在自己的职责范围内做到了最好"。我见过太多项目，agent 数量堆到十几个，但每个都干得很平庸，最后效果还不如一个精心调教的单 agent。
所以如果你正准备动手，我的建议是：先用 2 到 3 个 agent 把核心流程跑通，确认每个环节都有明确价值，再考虑扩展。宁可少而精，不要多而杂。这个道理说起来简单，但真正能忍住不堆 agent 的人，其实不多。
