多智能体协作实战：从环境配置到任务编排与批量落地

先说结论msitarzewski/agency-agents 这类多智能体项目最值得研究的不是单个模型的调用方式而是一套把多个 AI 智能体组织起来协作完成任务的流程。如果你只是想让模型写一段文案或者回答一个问题单智能体反而更省事但如果你要处理的是需要资料收集、交叉验证、分类整理、最终成稿这种多角色任务那么多智能体结构确实能把任务拆得更清楚。这篇文章会从“到底解决什么问题”开始按我实际接触这类项目时的顺序讲环境准备、最小跑通、批量任务、参数调整和常见排查。1. 先搞懂它解决的是“多个智能体怎么协作”的问题1.1 多智能体项目不是多个 Chat 页面很多人第一次看到 agency-agents 这种项目名时会下意识以为这是个“多窗口聊天工具”。实际上多智能体系统的核心不是把同一个模型打开多个窗口而是给不同的任务角色分配独立的上下文、人设、工具和输出格式再通过编排逻辑让它们按顺序或按条件协作。一个典型的单智能体流程通常是这样的你输入一个 Prompt模型调用工具返回结果。整个过程是线性的所有上下文都在同一段对话里。多智能体则不同。比如一个调研任务会有“研究员”先收集信息然后“分析师”基于这些信息做判断最后“主编”把结果整理成正式报告。每个角色只负责自己那一部分看到的信息也会被裁剪。项目名里的 agency 和 agents 放在一起核心就是“机构化”的思路。不是让你把任务直接丢给一个模型而是把一个系统拆成几个人物分工。这样做的第一个好处是上下文隔离。单 Prompt 里如果塞了太多角色要求模型很容易混淆尤其是任务变长之后前面的约束会被后面的内容冲淡。多智能体让每个 Agent 只需要关心自己的规则稳定性会更好。第二个好处是流程可控。你可以看到哪个智能体在什么时候执行了哪一步输出是什么。对于需要审计、复现、调整的任务来说这比一个黑盒对话要可靠得多。我在实际调试多智能体项目时第一件事就是先把每个 Agent 的输入输出边界划清楚否则后面查问题会非常痛苦。1.2 什么时候该用什么时候别硬用多智能体不是银弹。如果任务本身用一个 Prompt 加一次工具调用就能完成硬拆成多智能体只会增加延迟和成本。比如“给这句话翻译成英文”“总结这段文章的核心观点”这种任务不需要多个角色协作单智能体更直接。更适合多智能体的场景有几个特征任务可以被拆成多个子任务子任务需要不同的处理策略某些环节需要交叉验证最终结果需要多层整理。举个例子写一份行业分析报告你可以让一个 Agent 搜索和整理数据另一个 Agent 负责判断数据是否可信再让一个 Agent 生成结论。这样每个环节都能单独替换和优化。判断是否需要上多智能体我有一个很简单的标准把任务写下来如果第二步依赖第一步的中间结果并且中间结果需要结构化保存那么多智能体值得考虑。如果所有内容都能在一个 Prompt 里完成说明这个任务还不够复杂用多智能体只是给自己增加维护成本。还有一个容易踩的点多智能体不会天然提升模型能力。底模能力不够的话拆成十个角色也不会突然变聪明。它提升的是任务组织的稳定性和过程可见性。理解这一点再看项目里的各种配置就不会被花哨的角色名带偏。2. 先把环境、依赖和成本账算清楚2.1 运行环境与通用安装流程我拿到一个多智能体项目时一般不会先改代码而是先把仓库拉到本地看 README、examples 和依赖文件。对于 mzitarzewski/agency-agents 这种类型的项目你大概率会遇到 Python 项目常见的环境问题Python 版本不一致、依赖冲突、缺 API Key。常见的安装流程是这样的git clone 仓库地址 cd agency-agents python -m venv .venv source .venv/bin/activate pip install -r requirements.txtWindows 下激活虚拟环境命令需要换成.venv\Scripts\activate。如果项目使用 poetry 或 uv命令会有所不同但思路一样先创建隔离环境再安装依赖。直接往系统 Python 里装依赖短时间省事后面版本冲突会非常头疼。依赖版本要以仓库里的配置文件为准。原始项目没有给出明确的版本要求所以落地时一定要先确认一下 requirements.txt 或 pyproject.toml 里锁定的版本。尤其是 pydantic、openai 这类库大版本之间改动很大经常出现“代码没变换了个依赖版本就跑不起来”的情况。API Key 的配置方式也看项目。大多数多智能体项目会读取环境变量比如OPENAI_API_KEY。也有项目支持自建模型服务或 OpenAI 兼容接口需要额外配置 base_url。我在测试时习惯用一个.env文件保存密钥再用python-dotenv加载。但要记得把.env加进.gitignore避免提交到仓库里。2.2 资源占用和成本预算多智能体项目最容易被低估的是成本。单次任务调用一次模型成本很直观。多智能体任务则不同一个任务可能触发十几个甚至几十次模型调用。每个智能体都要消费输入输出 Token还要加上中间结果、日志、重试次数。成本不是“多了一点”而是成倍增加。如果接的是云端模型接口运行时的主要资源是 CPU 和内存GPU 占用反而不高。因为推理发生在远端本地主要做流程编排、序列化和日志记录。我见过一些人误以为多智能体必须依赖大显存显卡其实大多数时候瓶颈在 API 限流和费用。如果是本地模型情况就不一样。多个 Agent 并发运行会同时加载多个模型实例显存占用会明显上升。低显存不是完全不能跑但要把并发数降到 1并且把上下文长度、batch size 都调小。这个时候多智能体的“快”不是靠并行而是靠流程拆分。成本估算可以按这个公式大致算一下单任务成本约等于“平均调用次数 × 每次调用 Token 数 × 模型单价”。实际操作中我会先拿一个固定样例跑 5 到 10 次统计平均 Token 消耗和调用次数再乘以目标任务量。如果发现成本超标优先做两件事减少智能体数量或者缩小每个智能体的上下文。2.3 需要提前掌握的几个概念多智能体项目里有些概念绕不开不看懂这些直接碰代码很容易把日志看成一堆乱码。第一个是 Agent。它不是一个固定的类也不是一次函数调用而是一组配置和状态的组合。通常包含角色描述、系统提示词、可选工具、记忆策略和输出格式。第二个是 Task。Task 是待处理的工作单元可能是一条用户请求也可能是一个子任务。Task 的输入输出结构决定了智能体之间怎么交接。很多项目的问题就出在 Task 定义得模模糊糊结果下游 Agent 拿到的东西格式不对。第三个是 Tool。Tool 是智能体可以调用的外部能力比如搜索接口、浏览器操作、文件读写、数据库查询。多智能体项目里最常见的翻车点是工具权限过大或工具返回内容没有被正确处理。第四个是 Message。Message 是智能体之间传递的信息载体。每个消息一般有发送者、接收者、内容和其他元数据。只要消息链路设计得清楚调试起来就轻松如果消息字段设计得很乱整个系统会变成一团乱麻。还有 Orchestrator也就是编排器。它决定哪个 Agent 先跑、什么时候跑、是否需要并行、什么时候结束。我不建议一开始就研究复杂的编排策略。先把一个简单的流程跑通再根据日志决定要不要加分支和条件判断。3. 最小跑通先跑默认示例再改自己的场景3.1 拿到项目后的第一步不是改代码很多人的习惯是把代码拉到本地后直接找一个业务文件开始改。这个习惯在多智能体项目里非常危险因为你还没弄懂框架的数据流转改坏了都不知道是环境问题还是代码问题。我建议的第一步是像对待新框架一样先找 examples 目录。一般开源项目都会带几个最小示例可能是basic_crew.py、research_agents.py之类的文件。没有 examples 就看 README 里的快速开始部分通常会有十几行代码让你跑通一个基础任务。运行示例之前先确认三件事Python 环境是否激活、依赖是否装完、API Key 是否已经配置到环境变量。如果这三件事没搞定跑出来的报错基本没有参考价值。我见过有人因为环境变量没生效反复查代码逻辑查了半天最后只是.env文件没被加载。运行示例的命令以 README 为准通常是python examples/basic_agent.py如果项目提供 CLI 入口也可能是agency-agents run --task 帮我调研...这里具体命令不重要关键是先跑通一个不需要你自己改代码的流程。3.2 如何判断一次示例算跑通判断跑通的标准不是“没有报错”这么简单。一个多智能体任务正常结束你应该能在日志里看到这些信息任务被创建并且下发给某个 AgentAgent 之间产生了消息流转有工具调用或子任务执行记录最终生成了一个明确的结果对象进程正常退出。如果你的日志里只有一行All tasks completed!但看不到中间过程那说明日志级别可能开得太高。多智能体项目最重要的调试工具就是日志。运行时可以把日志级别调成 DEBUG查看每个 Agent 收到的输入和产生的输出尤其是关键字段。我第一次跑多智能体示例时习惯先把任务设置成非常简单的指令比如“用一句话总结这段文本”。这样能最大程度减少模型输出波动优先验证框架链路是否完整。等链路确认没问题再换成真实业务任务。如果示例运行失败不要急着改业务代码。先看报错栈顶在哪个文件再判断是依赖问题、API Key 问题还是模型服务返回异常。常见的多智能体项目失败原因里模型返回格式解析失败占了很大比例因为模型输出的 JSON 偶尔会带多余文本而框架严格解析时就会直接报错。4. 跑通之后怎么理解智能体之间的协作链路4.1 一条典型任务的生命周期默认示例跑通之后你会看到一堆日志。刚开始可能觉得它们只是流水账其实这正是理解多智能体系统的关键材料。一条任务的生命周期通常分几个阶段。首先是任务接收与规划。编排器拿到用户输入后会判断这个任务需要哪些 Agent并按依赖关系生成执行计划。然后是子任务分发。每个 Agent 收到自己的输入可能调用工具也可能调用模型生成中间结果。再往下是结果汇总。多个 Agent 的输出会被收集到一起交给下一个角色加工。最后是最终结果生成并返回给调用者。在日志里我会重点关注消息的方向。比如一条日志写着Agent(researcher) - Agent(analyst)说明研究员把结果交给了分析师。如果发现消息从没有直接依赖关系的两个 Agent 之间传递就要考虑是不是任务定义或编排逻辑出了问题。还要关注工具调用边界。某些 Agent 如果只负责分析就不应该允许它调用外部搜索工具。多个 Agent 共享工具很容易造成权限混乱也会让日志变得很难追踪。4.2 调整角色提示词和交接协议跑通示例之后接下来才是真正开始“做业务”。你通常要修改每个 Agent 的系统提示词。修改前先想清楚这个 Agent 的输入是什么、输出是什么、有哪些限制。比如一个研究员 Agent如果它的输出需要被分析师消费那么研究员提示词里必须定义清楚输出格式。我会要求它在结果中带source_list和summary两个字段。分析师拿到这个结构化结果后可以直接引用来源列表。如果交接协议不明确下游 Agent 只会拿到一段散文解析起来很麻烦最终结果也会不稳定。还有角色边界。不要让两个 Agent 的职责重叠。一个 Agent 负责收集另一个负责分析中间不要互相抢活。否则同一个任务会出现两次判断结果可能不一致。我一般会用一小段固定文本来测试提示词调整效果。比如让“编辑”Agent 输出固定的 Markdown 标题结构。如果连续三次输出结构都一致说明提示词约束够强。如果每次输出格式都不一样就去检查是不是模型 temperature 设置太高或者提示词里缺少“只输出 JSON”这类限制。5. 从单任务到批量队列、重试、并发与结果落盘5.1 单任务和批量任务的差异单条任务跑通之后很多人会直接写一个 for 循环跑批量。这种做法不是不行只是要提前想清楚几个问题。首先是命名和落盘。单条任务你可以手动看结果批量任务必须把结果存到统一目录。我建议每条任务生成一个独立文件文件名带上任务 ID 或时间戳避免覆盖。比如outputs/20250212_1015_task_001.json。如果所有结果都写到一个文件里中途失败会导致很难恢复。其次是失败重试。多智能体任务比单模型调用更容易失败因为它涉及多次模型调用。任何一次调用超时都可能让整个任务失败。批量任务里必须设计重试机制。我一般会把任务拆成两步读入任务列表逐个执行执行失败时先重试重试失败再把任务 ID 记录下来最后统一二次处理。第三是断点续跑。批量任务如果跑了几百条后中断重新跑一遍成本很高。所以输出目录里要区分“已完成”和“进行中”。我常见的一个做法是任务处理前写一个.started标记文件处理完成后写一个.done标记文件。下次启动时跳过.done文件对应的任务。这样即使中断也能从断点继续。5.2 一个通用批量调度示意下面这段代码不是某个仓库的源码而是在做批量封装时常用的骨架。思路是串行执行加失败重试先把稳定性跑出来再考虑并发。import time def run_with_retry(task, max_retries3, timeout120): for attempt in range(max_retries): try: result agency.run(task, timeouttimeout) return result except Exception as exc: print(fattempt {attempt 1} failed: {exc}) time.sleep(2 ** attempt) raise RuntimeError(ftask failed after {max_retries} attempts: {task}) tasks load_tasks(tasks.jsonl) for task in tasks: result run_with_retry(task) save_result(task, result)这里的agency.run是示意你需要替换成项目实际的调用入口。重点在于超时和重试。多智能体任务经常出现某个 Agent 长时间无响应的情况没有 timeout 的话程序会一直卡在那里。等串行跑通之后再考虑使用线程池或异步并发。并发不是越高越好。多智能体任务的每个请求都可能触发多个内部请求如果并发设置过高很容易把 API 限流打满还会造成成本快速上升。5.3 并发和成本控制我建议并发从 1 开始测试。跑 20 条任务记录成功率、平均耗时和 Token 消耗。如果一切正常再把并发提高到 2 或 3。如果出现大量超时或 429 限流就降回去而不是无限调高并发。成本控制上除了设置单次任务的最大轮数还要留意输入上下文长度。很多多智能体任务会在多轮消息堆积后把上下文撑得非常大Token 消耗以肉眼可见速度上涨。解决方案是给某些 Agent 设置“只保留最近 N 轮消息”的策略或者把中间结果摘要化后再传给下游。还有一点批量任务跑完后要检查输出文件是否完整。我通常会写一个简单校验脚本统计任务数量与结果文件数量是否一致。如果不一致就把缺失的任务单独重新跑一遍。批量任务的稳定性不是看单次跑得多好看而是看连续跑几百条之后还能不能保持稳定。6. 关键参数与效果判断不能只看“能跑”6.1 需要关注的参数多智能体项目的参数比单模型调用多很多。除了常见的温度、最大 Token还要关注任务轮数、Agent 之间消息传递深度、工具调用权限、并发数和超时时间。我把常用参数整理成一个表方便对照检查参数影响推荐做法temperature影响输出随机性需要稳定格式时调到 0 到 0.3max_tokens限制单次输出长度给足但不要无限避免失控max_rounds限制多轮消息轮数防止死循环和成本爆炸timeout单次任务超时时间根据业务耗时设置不要过长concurrency同时执行的任务数从 1 开始逐步上调retry_times失败重试次数2 到 3 次比较合理很多问题不是模型能力不够而是参数没有设置合理。比如把 temperature 调到 1模型输出格式就会来回变。在多智能体协作中格式稳定性比创造性更关键所以我会默认把 temperature 调低。6.2 用数据判断效果只凭“任务跑完了”来判断效果容易把不稳定当成成功。我会在改进前先准备一个固定测试集包含 10 到 20 个有代表性的任务。然后记录几项指标任务成功率、平均耗时、Token 消耗、输出格式合格率、输出内容质量评分。成功率不是最重要的输出格式合格率才是。多智能体系统如果每次输出结构都不一样下游自动化就无法依赖它。所以我在评估时会更看重“连续 10 次输出是否保持同一结构”。内容质量评估则要结合业务。比如调研类任务我会看它是否真的引用了来源是否能在报告里找到对应的依据。不要只看生成的长度很多看似完整的回答实际上没有实质信息。调整参数时一次只改一个变量。如果同时改 temperature 和提示词出了问题你很难判断是哪个改动导致的。我做实验的习惯是每次改动后记录一组数据对比前后差异。这个方法虽然笨但在多智能体项目里非常有效。7. 常见问题排查链路与避坑清单7.1 启动失败和依赖问题启动失败是最常见的问题通常和项目逻辑没多大关系。我建议按这个顺序排查。先看 Python 版本。检查python --version是否在项目要求的范围内。多智能体项目常用比较新的 Python 特性版本太低会直接报语法错误。再看依赖安装。虚拟环境是否激活pip list里有没有安装项目依赖。如果某个依赖的版本和项目要求不一致优先把本地版本降到项目配置文件里的版本。然后看环境变量。API Key 是否真的加载到了当前进程。可以在项目入口加一行print(os.getenv(API_KEY))确认值存在。不要只看.env文件里写了还要注意当前终端是否在项目根目录运行。最后看网络和服务端状态。如果你调用的是远端模型服务先单独测试服务接口是否可用。多智能体项目启动失败时报错信息里如果出现了connection error或timeout大概率不是代码问题而是服务连接或网络条件问题。7.2 任务卡住、无输出、结果不正确任务卡住时第一步是看日志最后一条消息是哪个 Agent 发出的以及它发给了谁。如果某个 Agent 一直在等待上游结果说明上游可能出了问题如果同一个消息在循环里反复出现可能是编排逻辑里没有设置最大轮数。无输出时先确认模型是否真的返回了内容再检查项目是否按预期格式解析。很多框架要求模型返回 JSON 字符串如果模型返回了 Markdown 包裹的 JSON解析就会失败。这时候要么修改提示词让模型只输出纯 JSON要么在解析前做一层清洗。结果不正确时先看是偶发还是必现。如果是偶发优先怀疑模型随机性把 temperature 调低如果是必现优先怀疑提示词、上下文或工具调用。还有一点容易忽略多智能体项目里的中间结果可能被某个 Agent 改坏了。所以排查时要逐层看中间输出而不是只看最终结果。7.3 四个建议提前避开的坑第一不要把单智能体任务硬拆成多智能体。一个任务本来只需要一次模型调用硬拆之后延迟变高成本变高稳定性反而下降。多智能体的价值在于任务结构和上下文隔离不在数量。第二不要一开始就开高并发。多智能体任务的高并发很容易把 API 限流打爆。先串行跑通再加少量并发观察稳定后再逐步提升。第三不要忽略日志。多智能体项目的日志就是它的“黑匣子”。如果日志不完整调试和优化都无从下手。运行前应该把日志输出级别、保存路径、是否包含请求 ID 这些细节都确认好。第四不要因为一次跑通就宣布方案已经稳定。多智能体任务的随机性比单模型更高。要跑至少 20 到 50 个样本统计成功率和格式合格率再判断是否适合生产使用。最后留一个经验多智能体项目真正落地时最值得盯住的往往不是新功能而是任务定义、输入格式、资源占用和失败重试。把这几件事做扎实比堆多少个 Agent 角色都更管用。