在业务里做 AI 应用时很多团队会遇到一个很现实的问题单次调用大模型只能完成“写一段文字”“总结一份报告”这样简单的原子任务一旦需求变成“围绕一个主题做调研、整理、写作、审核”单个 Prompt 很难稳定地输出高质量结果。为了让大模型像真实团队一样分工协作多智能体Multi-Agent架构开始流行。今天要讲的msitarzewski/agency-agents就是一个非常轻量、适合快速上手、同时又具备完整多智能体协作能力的 Python 开源项目。本文会从项目定位与核心概念入手带大家完成环境搭建拆解它的 Agent 分工机制并用“技术写作小组”这个完整案例演示如何让多个 Agent 协作产出文章。最后给出常见排查方向和工程落地建议。无论你是刚开始接触 AI Agent还是已经在用 LangChain 这类重量级框架这篇文章都能帮你打开一个新的实现思路。1. 什么是 agency-agents它解决什么问题1.1 从单 Agent 到多 Agent 协作在理解agency-agents之前先回到一个基础问题为什么需要多 Agent 协作单一 Agent 的本质是“大模型 系统提示词 上下文”的组合。它可以处理用户的输入但存在几个明显限制角色冲突一个模型既要扮演调研者又要扮演写作者还要扮演审核者提示词会很冗长而且模型很难在长对话中始终维持某个角色的行为边界。上下文污染一次任务中的所有历史信息都会堆积在上下文窗口里无关信息会干扰模型对当前角色的判断。无法并行单 Agent 只能按顺序推进任务无法在同一段时间内并行完成资料收集、内容起草、质量检查这类互相独立的工作。结果不可控缺少“批评者”或“审核者”角色时模型输出的错误很难被及时纠正。多 Agent 架构的核心思路是把一个复杂目标拆成多个子任务交给不同角色负责再通过一个协调者Manager统一调度。每个 Agent 只需要专注于自己的职责范围上下文更干净Prompt 更聚焦整体输出的稳定性和质量也会有明显提升。1.2 agency-agents 的定位与特点msitarzewski/agency-agents是一个基于 OpenAI API 的轻量级多智能体协作框架。它在设计上和 LangChain、AutoGen 这类重型框架有明显区别轻量没有复杂的抽象层和庞大的依赖核心代码量很小理解起来不难。OpenAI 优先直接基于 OpenAI 的接口封装开箱即用不需要额外对接外部向量库、记忆模块。角色驱动通过Agent类定义“角色”通过ManagerAgent协调整个流程符合真实团队分工的直觉。透明可控运行过程中能看到每个 Agent 的输入输出与协作过程便于调试和结果分析。用一句话概括如果你需要一个简单、清晰、可读性强的多 Agent 协作示例或者希望在自己的项目中快速引入“多角色分工”的能力agency-agents是一个很合适的参考实现和技术选型。1.3 项目适用场景agency-agents的适用场景可以从两个维度看。第一类学习研究。想理解 Multi-Agent 系统是怎么设计出来的Agent 之间如何传递消息Manager 如何安排任务直接阅读这个项目会比啃大型框架轻松得多。第二类实际业务。比较典型的需求包括场景多 Agent 分工方式技术内容写作调研 Agent 收集资料写作 Agent 撰写初稿审核 Agent 检查逻辑与格式营销文案批量生成策划 Agent 负责选题文案 Agent 负责输出优化 Agent 负责 A/B 版本测试研究报告生成数据收集 Agent 负责抓取信息分析 Agent 负责汇总编辑 Agent 负责成稿代码审查辅助开发 Agent 生成代码审查 Agent 检查漏洞和风格测试 Agent 补测试用例由于项目保持了对 OpenAI API 的直接封装你可以很方便地在此基础上加上自己的业务逻辑、外部工具、数据库等灵活度非常高。2. 环境准备与项目快速体验2.1 环境要求在开始之前先确认本地环境。本文示例以常见环境为例具体版本需要根据你的项目实际情况调整。依赖建议操作系统Windows / macOS / Linux 均可Python3.9 及以上版本OpenAI 库openai Python SDK 1.x 版本API Key有效的 OpenAI API Key并确保账户有可用额度如果你使用的是国内大模型兼容 OpenAI 格式的服务也可以通过修改base_url来适配本文后面会提到这一点。2.2 获取项目代码有两种方式获取agency-agents项目源码。方式一直接克隆 GitHub 仓库。git clone https://github.com/msitarzewski/agency-agents.git cd agency-agents方式二下载 ZIP 压缩包在 GitHub 仓库页面点击Code-Download ZIP解压后进入目录。2.3 安装依赖进入项目目录后安装所需依赖。建议使用虚拟环境隔离项目依赖python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate pip install -r requirements.txt如果你只是想快速验证也可以只安装核心依赖pip install openai2.4 配置 API Key在项目根目录创建.env文件或者在系统环境变量中配置你的 API Key。export OPENAI_API_KEYsk-你的-api-key # macOS / LinuxWindows PowerShell 下使用$env:OPENAI_API_KEYsk-你的-api-key这里要特别提醒不要把 API Key 提交到 Git 仓库也不要写死在代码里。建议用环境变量或本地.env文件管理并确保.env已加入.gitignore。2.5 跑通最小示例安装完成之后可以先跑一个最简单的用例验证整个链路是否正常。# 文件路径examples/quick_start.py from agency_agents import Agent, ManagerAgent # 设置 API Key实际项目中建议从环境变量读取 import os api_key os.getenv(OPENAI_API_KEY) # 创建一个普通工作 Agent worker Agent( openai_api_keyapi_key, main_agentFalse, roleassistant, instructions你是一个乐于助人的助手请简洁地回答用户问题。, ) # 创建管理器并指定 worker 为主 Agent manager ManagerAgent( openai_api_keyapi_key, main_agentworker, agents[], ) # 运行任务 response manager.run( prompt请用一句话介绍 Python。, ) print(response)如果一切正常你会看到模型返回的 Python 介绍。这个示例虽然简单但已经把Agent、ManagerAgent、run()三个核心概念串起来了。3. 核心机制拆解Agent、Manager 与协作流程3.1 Agent 的构成与角色设计在agency-agents中Agent是基本的执行单元。每一个 Agent 都代表一个具备特定角色、指令和参数的大模型实例。创建一个 Agent 时常用参数如下参数作用openai_api_keyOpenAI API Keymain_agent是否为“主 Agent”通常只允许一个主 Agentrole角色名称用于在协作中标识该 Agent 的职责instructions系统提示词定义该 Agent 的行为准则、任务说明、输出格式model使用的模型名称默认值以项目代码为准常见为gpt-4系列temperature温度参数控制生成随机性角色需要严谨时建议调低max_tokens最大生成 token 数防止单次输出过长角色设计是使用这个框架最关键的环节。你可以把instructions想象成岗位说明书内容越具体Agent 的“人设”越稳定。research_agent Agent( openai_api_keyapi_key, main_agentFalse, roleresearch, instructions你是一名资深技术调研员。你的任务是围绕用户给出的主题进行资料梳理。 要求 1. 尽量全面地列出该主题的核心概念、常用工具、典型应用场景 2. 输出使用 Markdown 列表便于后续编辑 3. 不要做主观评价只做客观信息整理。, temperature0.3, )注意这里instructions里强调了输出格式和边界这是为了让后续协作 Agent 更容易解析结果。3.2 ManagerAgent 的任务协调机制ManagerAgent是整个多 Agent 协作的中枢。它本身不直接执行具体任务而是负责接收用户请求、拆分任务、分发给不同的 Agent并汇总结果。在agency-agents中ManagerAgent的构造函数通常包含参数作用openai_api_keyAPI Keymain_agent主 Agent通常是最终负责交付的 Agentagents参与协作的其他 Agent 列表run()方法是最核心的入口。调用时需要传入prompt有些版本还支持task参数来更细致地描述任务。Manager 会基于这些信息决定如何调度各个 Agent。一个常见的工作流程是Manager 接收用户的任务描述。将任务分发给可用的 Agent。各 Agent 根据自身角色和指令执行任务。结果返回 Manager由主 Agent 或 Manager 做最终整合。这种设计非常像真实的项目管理项目经理不负责写代码但他知道该让谁写、什么时候写好、如何把大家的工作成果合并到一起。3.3 Agent 之间的消息传递与上下文管理多 Agent 系统最容易出问题的就是消息传递和上下文管理。在agency-agents中Agent 之间的结果传递主要靠返回值。前一个 Agent 的输出会成为后一个 Agent 的输入上下文。这种串行/并行结合的方式避免了单一上下文无限膨胀的问题。实际使用中你可能会在run()中看到context或messages之类的参数。它们用于传递额外的上下文信息。response manager.run( prompt请写一篇主题为 X 的文章, context{ research_result: research_output, target_audience: 后端开发者, }, )这种方式的价值在于每个 Agent 不需要在自身 Prompt 中预埋所有信息而是从context中按需读取职责边界更清晰。3.4 输出解析与结果汇总由于每个 Agent 的instructions可以自定义输出格式Manager 汇总时就有了可解析的中间产物。比如调研 Agent 输出 Markdown 列表写作 Agent 基于这个列表生成文章审核 Agent 再针对文章给出修改意见。这种“结构化中间产物 逐步传递”的方式是多 Agent 协作比单 Agent 更可控的关键原因。你可以随时检查中间结果定位是哪个环节出了问题。4. 完整实战构建一个技术写作 Agent 小组下面用一个相对完整的案例演示agency-agents在实际场景中怎么用。我们的目标是搭建一个“技术写作小组”包含三个角色调研 Agent负责收集技术主题的要点。写作 Agent负责生成文章初稿。审核 Agent负责检查文章逻辑、格式和可读性。4.1 项目结构agency-writing-demo/ ├── main.py ├── agents.py └── requirements.txt4.2 依赖文件# 文件路径requirements.txt openai1.0.0 python-dotenv1.0.04.3 编写 Agent 定义# 文件路径agents.py from agency_agents import Agent def create_research_agent(api_key: str) - Agent: 创建调研 Agent return Agent( openai_api_keyapi_key, main_agentFalse, roleresearcher, instructions你是一名专业的技术调研员。 当你收到一个技术主题时你需要输出 1. 主题背景与价值 2. 核心概念与技术要点 3. 常用工具和框架 4. 典型应用场景。 请使用 Markdown 无序列表输出内容要客观、完整不要输出代码示例。, temperature0.3, ) def create_writer_agent(api_key: str) - Agent: 创建写作 Agent return Agent( openai_api_keyapi_key, main_agentFalse, rolewriter, instructions你是一名资深技术文章作者。 你会收到一份调研笔记请基于笔记内容写一篇结构完整的技术博客。 要求 1. 文章需要有清晰的小标题 2. 每个段落要详细、深入避免空话 3. 使用 Markdown 格式输出 4. 不要编造调研笔记中不存在的事实。, temperature0.7, ) def create_reviewer_agent(api_key: str) - Agent: 创建审核 Agent return Agent( openai_api_keyapi_key, main_agentFalse, rolereviewer, instructions你是一名严格的技术文章审核员。 你会收到一篇技术文章请从以下维度检查 1. 逻辑是否清晰段落之间是否有连贯性 2. 内容是否存在明显的事实错误 3. Markdown 格式是否正确 4. 是否有可读性提升空间。 请输出审核意见并给出具体的修改建议。, temperature0.2, )这里的关键点在于每个 Agent 的instructions都明确写了“输入是什么、输出是什么、格式要求是什么”。这样 Manager 才知道到底该把谁的结果给谁。4.4 编写主程序# 文件路径main.py import os from dotenv import load_dotenv from agency_agents import Agent, ManagerAgent from agents import create_research_agent, create_writer_agent, create_reviewer_agent load_dotenv() API_KEY os.getenv(OPENAI_API_KEY) def main(): # 1. 创建三个角色 Agent research_agent create_research_agent(API_KEY) writer_agent create_writer_agent(API_KEY) reviewer_agent create_reviewer_agent(API_KEY) # 2. 创建主 Agent负责最终交付 main_agent Agent( openai_api_keyAPI_KEY, main_agentTrue, roleeditor, instructions你是一名技术编辑。 你会收到调研结果、文章初稿和审核意见。 请综合所有材料输出一篇最终版技术博客。 要求 - 保留审核意见中有价值的修改 - 确保文章可读性高 - 使用 Markdown 输出。, temperature0.5, ) # 3. 创建 ManagerAgent把其他 Agent 挂载进来 manager ManagerAgent( openai_api_keyAPI_KEY, main_agentmain_agent, agents[research_agent, writer_agent, reviewer_agent], ) # 4. 运行任务 response manager.run( prompt请写一篇介绍 Python 虚拟环境venv的技术博客目标读者是刚入门的开发者。, ) # 5. 输出最终结果 print(最终成果) print(response) if __name__ __main__: main()4.5 运行与验证在项目目录下执行python main.py运行过程可能持续几十秒到几分钟取决于 API 响应速度和模型版本。最终输出是一篇包含小标题、段落、可能还有列表的 Markdown 技术博客。这个案例体现了agency-agents最核心的价值不是让一个大模型从头写到尾而是让调研、写作、审核、编辑四个角色各司其职最后汇总成更高质量的结果。4.6 结果说明如果运行正常你会看到最终文章比单 Agent 生成的文章有明显的结构性和逻辑性提升因为它经过了“调研 - 写作 - 审核 - 编辑”这么一条完整的流水线。你可以在main_agent的instructions中继续补充品牌风格、读者定位、字数要求让最终产出更贴近实际业务需求。5. 常见问题与排查思路在实际运行时agency-agents虽然代码精简但还是会遇到一些常见问题。下面整理了一份排查思路按“错误现象 - 常见原因 - 解决思路”来列。问题现象常见原因解决思路调用manager.run()后长时间无响应模型响应慢或网络不稳定先跑一个简单任务确认链路适当增加超时时间检查网络报错API key相关错误API Key 未正确配置检查环境变量是否读取成功确认 Key 是否有额度确认是否包含多余空格报错model not found模型名称不存在或当前账户不可用修改Agent的model参数换成账户可用的模型Agent 返回内容不符合预期instructions不够具体强化系统提示词明确角色、步骤、输出格式、禁止行为多个 Agent 协作结果混乱中间产物没有结构化让每个 Agent 都输出固定格式例如 Markdown 列表、JSON 等请求频繁触发限流多个 Agent 短时间密集请求增加请求间隔做好重试退避控制并发运行中上下文过长中间结果过大累积到上下文中精简每个 Agent 的输出在instructions中限制长度5.1 API 超时或连接失败如果你所在的网络环境访问 OpenAI 不稳定可以考虑使用官方推荐的base_url配置方式把请求指向可用的 API 网关或兼容服务。在代码中捕获异常并做重试。import time try: response manager.run(prompt...) except Exception as e: print(f请求失败{e}) time.sleep(5) response manager.run(prompt...)5.2 角色不生效一个很常见的坑Agent 的instructions写得很详细但运行起来却发现输出风格和默认模型差别不大。原因通常是instructions里缺少“你必须”“禁止”这类强约束词。temperature设置过高导致随机性压过了角色约束。输入上下文太长模型忽略了较早的系统提示词。建议把最重要、最不可违背的规则放在instructions的开头尽量用短句和编号列表。5.3 ManagerAgent 调度不符合预期agency-agents的调度逻辑相对直接如果你的业务需要更细粒度的编排例如“先调研再并行写作与审核”可以在 Manager 内置 Agent 的配置上做二次开发或者在prompt中更明确地描述执行顺序。5.4 成本控制多 Agent 协作意味着一次任务会消耗多次 API 调用。如果不加控制成本会比单 Agent 高很多。建议每个 Agent 都设置合理的max_tokens。调研 Agent 不需要生成 2000 token 时限制它只输出摘要。审核 Agent 的temperature调低减少无效变体。6. 最佳实践与工程建议6.1 角色提示词设计角色提示词是多 Agent 系统的灵魂。设计时可以遵循下面几个原则第一角色边界清晰。比如“调研 Agent 只负责收集事实不负责评价”和“审核 Agent 只负责挑问题不负责重写”这样明确的边界能减少 Agent 越权输出。第二输出格式明确。让每个 Agent 都输出固定结构的 Markdown 或 JSON这样 Manager 做汇总时不需要做复杂的自然语言解析。instructions 输出格式如下 ## 调研结论 - 核心概念... - 工具清单... - 应用场景... 第三要设置“不能做什么”。比如“不要编造数据”“不要输出代码”“不要输出无关内容”这类负向约束往往比正向约束更有效。6.2 配置管理不要把 API Key、模型名称、角色提示词全部散落在代码里。建议使用.env文件管理密钥用配置类或 YAML 文件管理 Agent 的提示词。# .env OPENAI_API_KEYsk-xxx WRITER_MODELgpt-4o WRITER_TEMPERATURE0.7# config.py import os from dataclasses import dataclass dataclass class AgentConfig: model: str temperature: float instructions: str def load_writer_config() - AgentConfig: return AgentConfig( modelos.getenv(WRITER_MODEL, gpt-4o), temperaturefloat(os.getenv(WRITER_TEMPERATURE, 0.7)), instructionsos.getenv(WRITER_INSTRUCTIONS, ), )6.3 异常处理与重试多 Agent 系统因为涉及多次网络调用失败概率比单次 API 调用更高。建议在所有 Agent 调用外层增加统一的异常处理逻辑超时重试、限流退避、失败降级。import time from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min2, max30)) def run_with_retry(manager, prompt): return manager.run(promptprompt)6.4 日志与可观测性多 Agent 协作过程是一个黑盒为了排错和优化必须记录详细的日志。建议至少记录以下信息每次调用的模型、输入 token、输出 token、耗时。每个 Agent 的输入摘要和输出摘要。Manager 的调度决策比如把任务分给了哪些 Agent。import logging logging.basicConfig(levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s) logger logging.getLogger(__name__) logger.info(调用调研 Agent主题%s, topic)有了日志后续优化提示词、调整参数就有据可依。6.5 安全与合规在多 Agent 应用中安全是一个必须提前思考的问题。密钥安全API Key 不能出现在前端代码、日志、Git 历史中。内容安全如果 Agent 会被外部用户输入触发要增加输入过滤和输出审核环节防止生成违规内容。权限隔离如果 Agent 需要调用外部系统或数据库必须遵循最小权限原则避免因为 Prompt 注入导致越权操作。人工兜底在自动化产出结果之前建议增加人工审核步骤尤其是面向用户的文案或报告。6.6 成本与性能优化多 Agent 系统的性能瓶颈通常在 API 调用次数和 token 消耗。常见的优化手段能并行调用的 Agent 尽量并行减少总耗时。在instructions中限制每个 Agent 的输出长度避免中间结果过大。对相同输入的重复请求做缓存减少无效调用。监控每个 Agent 的 token 消耗及时发现异常任务。7. 总结与学习路线通过这篇文章我们完整梳理了msitarzewski/agency-agents这个轻量级多智能体框架的定位、核心机制和实战用法。从最简单的Agent创建到ManagerAgent协调多个角色再到一个可落地的技术写作小组案例整个过程都保持了较低的抽象度和较高的可读性。对于想理解多 Agent 工作原理的开发者来说这是一个非常合适的入门项目对于想快速在自己业务中引入多角色协作能力的团队它也是一个灵活的参考实现。下一步你可以从这几个方向继续深入阅读agency-agents的源码理解ManagerAgent内部的调度实现尝试增加自己的任务拆分逻辑。在案例中加入工具调用和外部数据源让 Agent 能够联网搜索或查询数据库。对比 LangChain、AutoGen 等框架的 Agent 编排方式思考各自的设计取舍。尝试把多个 Agent 之间的协作结果用结构化数据输出对接下游业务系统。在实际项目中优先关注角色提示词的质量、API 调用的成本控制、异常重试机制以及面向用户时的内容安全审核。把这些基础打牢多 Agent 系统才能从“能跑”走向“好用”。如果本文对你有帮助可以收藏备用后续可以继续完善自己的 Agent 应用。