基于agency-agents构建多智能体协作系统：从核心概念到实战应用

最近在尝试构建一个多智能体协作系统时，发现市面上虽然有不少框架，但要么过于复杂，要么功能不够灵活。直到我深入研究了msitarzewski/agency-agents这个开源项目，它提供了一种清晰、模块化的方式来构建和管理智能体（Agent），让我眼前一亮。本文将带你从零开始，全面解析agency-agents的核心概念、架构设计，并通过一个完整的实战项目，手把手教你如何用它来构建一个具备自主协作能力的智能体系统。无论你是想入门智能体开发，还是希望为现有项目引入更灵活的自动化能力，这篇文章都能为你提供一套可直接复用的解决方案。

1. 背景与核心概念：什么是智能体（Agent）与agency-agents？

在深入代码之前，我们有必要厘清几个核心概念。在人工智能领域，智能体（Agent）通常被定义为一个能够感知环境、进行决策并执行动作以实现特定目标的实体。它不仅仅是调用一个 AI 模型（如 GPT），而是一个包含记忆（Memory）、规划（Planning）、工具使用（Tool Use）等能力的完整系统。

那么，agency-agents是什么？它是一个用 Python 编写的开源库，旨在简化智能体的构建过程。它的核心思想是“将智能体视为可组合的模块”。与一些“大而全”的框架不同，agency-agents提供了高度解耦的组件，让你可以像搭积木一样，自由组合不同的能力来创建智能体。

它解决了什么问题？

1. 模块化缺失：许多框架将记忆、工具、规划逻辑紧耦合，难以替换或升级单一组件。
2. 通信复杂：在多智能体场景中，智能体间的消息传递、协作逻辑编写起来很繁琐。
3. 状态管理困难：智能体的对话历史、知识库等状态如何持久化和隔离，是常见的痛点。

agency-agents通过清晰的抽象（如Agent、Tool、Memory、Channel）和松耦合的设计，让开发者能专注于智能体的业务逻辑，而非底层通信机制。

常见应用场景：

• 自动化工作流：例如，一个智能体读取邮件，分析内容后，调用另一个智能体在日历中创建会议。
• 多专家协作系统：构建具有不同专业领域（如代码生成、文案写作、数据分析）的智能体，让它们共同完成复杂任务。
• 游戏 NPC：为游戏中的非玩家角色赋予更复杂的决策和行为树。
• 研究与实验平台：快速原型化新的智能体架构或交互模式。

2. 环境准备与版本说明

在开始实战之前，请确保你的开发环境已就绪。本文将使用 Python 作为主要语言。

操作系统: Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04+) 均可。Python: 推荐使用 Python 3.9 或更高版本。你可以通过python --version检查。包管理工具: 使用pip进行安装。IDE: 推荐使用 VSCode 或 PyCharm，它们对 Python 有很好的支持。

首先，创建一个干净的虚拟环境来隔离项目依赖，这是一个非常重要的最佳实践。

# 创建项目目录并进入 mkdir agency-agents-demo cd agency-agents-demo # 创建 Python 虚拟环境 (以 venv 为例) python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate

激活后，你的命令行提示符前应该会出现(venv)字样。

接下来，安装agency-agents库。由于它是一个较新的项目，我们直接从其 Git 仓库安装。同时，为了给智能体提供“大脑”，我们需要一个 LLM（大语言模型）后端。这里我们使用 OpenAI 的 API（你也可以替换为其他兼容 OpenAI 接口的模型，如本地部署的 Ollama）。

# 安装 agency-agents pip install git+https://github.com/msitarzewski/agency-agents.git # 安装 OpenAI Python SDK，这是 agency-agents 与 GPT 模型通信所必需的 pip install openai # 可选：安装 python-dotenv 来管理环境变量（推荐） pip install python-dotenv

版本说明：

• agency-agents: 本文基于撰写时的最新主分支代码。开源项目迭代较快，核心概念稳定，但具体 API 可能有细微调整，请以官方文档为准。
• openai: 版本 >= 1.0.0。注意 OpenAI SDK 在 1.x 版本有重大更新。
• 其他依赖将由agency-agents自动处理。

项目结构预览： 在开始编码前，我们先规划一下项目结构，这有助于保持代码清晰。

agency-agents-demo/ ├── .env # 存储敏感信息，如 API Key ├── .gitignore # Git 忽略文件 ├── requirements.txt # 项目依赖列表 ├── main.py # 主程序入口 ├── agents/ # 智能体模块目录 │ ├── __init__.py │ ├── writer_agent.py # 写作智能体 │ └── coder_agent.py # 编程智能体 ├── tools/ # 工具模块目录 │ ├── __init__.py │ └── calculator_tool.py # 自定义工具示例 └── memory/ # 记忆模块目录（可选） └── __init__.py

3. 核心架构与组件拆解

agency-agents的威力源于其简洁而强大的抽象。让我们逐一拆解其核心组件，理解“为什么这样设计”。

3.1 智能体 (Agent)

Agent类是核心。一个智能体至少需要：

1. 一个名字 (name)：用于标识。
2. 一个系统提示词 (system_prompt)：定义它的角色、能力和行为准则。
3. 一个模型 (model)：即 LLM 的配置，告诉它使用哪个 AI 模型进行思考。
4. 工具列表 (tools)：智能体可以调用的函数集合。

关键设计：Agent本身不处理与 LLM 的通信细节，它只定义“谁”和“能做什么”。实际的 LLM 调用由Model组件负责，这实现了控制反转（IoC），使得更换模型（比如从 GPT-4 换到 Claude）变得非常容易。

3.2 工具 (Tool)

Tool是智能体与外部世界交互的桥梁。任何 Python 函数，只要加上@tool装饰器，就可以被智能体发现和调用。框架会自动处理函数描述的生成、参数的 JSON Schema 转换以及调用。

为什么需要工具？LLM 本身是“纯思考”的，它需要工具来执行具体操作，如计算、搜索、读写文件、调用 API 等。

3.3 记忆 (Memory)

Memory组件负责存储和检索智能体的对话历史、知识等。agency-agents内置了简单的对话历史记忆。你也可以实现自定义的Memory类，例如连接到向量数据库（如 Chroma, Pinecone）来实现长期记忆和语义检索。

记忆的重要性：没有记忆的智能体就像金鱼，每次对话都是新的。记忆使其能够进行连贯的多轮对话，并基于历史信息做出决策。

3.4 通道 (Channel) 与空间 (Space)

这是实现多智能体协作的关键抽象。

• Channel: 可以理解为一条通信线路（如一个 Slack 频道、一个微信群）。智能体加入同一个Channel后，就可以相互发送和接收消息。
• Space: 是一个运行环境，管理着智能体和通道的生命周期。你可以把Space想象成一个“房间”，里面有不同的“讨论组”（Channel），智能体们在这些组里交流。

这种设计使得智能体间的协作模式非常灵活：可以是一对一私聊，也可以是多对多的群组讨论。

3.5 模型 (Model)

Model封装了与具体 LLM 提供商（如 OpenAI, Anthropic）的交互细节。它接收智能体的提示词，调用 API，并返回解析后的响应。通过配置不同的Model，你可以轻松切换底层的大模型。

4. 完整实战案例：构建一个写作与编程智能体协作系统

现在，我们将理论付诸实践。我们的目标是创建两个智能体：一个写作助手（Writer）和一个代码专家（Coder）。Writer 负责构思内容大纲，Coder 负责将大纲实现为具体的代码（比如一个简单的网页）。它们需要通过协作来完成“创建一个介绍 Python 的网页”这个任务。

4.1 项目初始化与配置

首先，创建.env文件来安全地存储你的 OpenAI API Key。

# 在项目根目录下创建 .env 文件 echo "OPENAI_API_KEY=你的实际API密钥" > .env

重要：请将你的实际API密钥替换为你从 OpenAI 平台获取的有效密钥。确保.env文件已被添加到.gitignore中，避免密钥泄露。

然后，创建requirements.txt文件，记录依赖。

openai>=1.0.0 python-dotenv>=1.0.0 # agency-agents 通过 git 安装，通常不直接写在 requirements.txt 里，但可以备注 # git+https://github.com/msitarzewski/agency-agents.git

4.2 创建自定义工具

让我们先为 Coder 智能体创建一个简单的工具，用于“创建文件”。在tools/calculator_tool.py旁边，我们创建file_tool.py。

# file: tools/file_tool.py import os from agency_agents import tool @tool def create_file(filepath: str, content: str) -> str: """ 在指定路径创建或覆盖一个文件，并写入内容。 Args: filepath (str): 要创建的文件的路径，例如 './output/index.html'。 content (str): 要写入文件的内容。 Returns: str: 操作结果信息，例如 '文件创建成功' 或错误信息。 """ try: # 确保目录存在 os.makedirs(os.path.dirname(filepath), exist_ok=True) with open(filepath, 'w', encoding='utf-8') as f: f.write(content) return f"文件 '{filepath}' 创建成功。" except Exception as e: return f"创建文件时出错: {str(e)}" # 再创建一个简单的计算器工具，供 Writer 或 Coder 在需要时使用 @tool def calculator(a: float, b: float, operation: str) -> float: """ 执行简单的数学运算。 Args: a (float): 第一个数字。 b (float): 第二个数字。 operation (str): 运算类型，支持 'add', 'subtract', 'multiply', 'divide'。 Returns: float: 运算结果。 """ if operation == 'add': return a + b elif operation == 'subtract': return a - b elif operation == 'multiply': return a * b elif operation == 'divide': if b == 0: raise ValueError("除数不能为零") return a / b else: raise ValueError(f"不支持的运算: {operation}")

4.3 定义智能体

接下来，我们分别定义 Writer 和 Coder 智能体。

# file: agents/writer_agent.py from agency_agents import Agent from openai import OpenAI import os from dotenv import load_dotenv load_dotenv() # 加载 .env 中的环境变量 # 首先，创建一个 Model 实例，指向 OpenAI 的 GPT-4 # 注意：这里使用了 OpenAI SDK 1.x 的写法 client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) # 定义一个简单的 Model 包装类（agency-agents 未来可能会提供更官方的集成） from agency_agents import Model class OpenAIModel(Model): def __init__(self, model_name="gpt-4-turbo-preview"): self.model_name = model_name self.client = client def generate(self, messages): # 将 agency-agents 的消息格式转换为 OpenAI 格式 openai_messages = [] for msg in messages: # 这里简化处理，实际应根据 agency_agents 的 Message 对象结构调整 # 假设 msg 有 ‘role‘ 和 ’content‘ 属性 openai_messages.append({"role": msg.role, "content": msg.content}) response = self.client.chat.completions.create( model=self.model_name, messages=openai_messages, temperature=0.7, ) # 返回 Assistant 的消息内容 return response.choices[0].message.content # 创建 Writer Agent writer_model = OpenAIModel("gpt-4-turbo-preview") writer = Agent( name="Writer", system_prompt="你是一个专业的写作助手，擅长将复杂的想法拆解为清晰、有条理的大纲和描述。你的输出应该结构清晰，要点明确，为后续的代码实现提供直接指导。", model=writer_model, # Writer 暂时不需要特定工具，如果需要可以添加 calculator tools=[], # 可以从 tools 模块导入 calculator )

# file: agents/coder_agent.py from agency_agents import Agent from .writer_agent import OpenAIModel # 复用同一个 Model 类 from tools.file_tool import create_file, calculator import os # 创建 Coder Agent coder_model = OpenAIModel("gpt-4-turbo-preview") # 可以使用不同模型，这里用同一个 coder = Agent( name="Coder", system_prompt="你是一个全栈开发专家，精通 HTML, CSS, JavaScript 和 Python。你能根据详细的内容大纲，快速生成简洁、规范、可运行的代码。你会使用 create_file 工具来保存你的代码成果。", model=coder_model, tools=[create_file, calculator], # Coder 拥有创建文件和计算工具 )

4.4 创建协作空间并运行任务

现在，让我们创建一个主程序，将两个智能体放入同一个空间，并启动它们的协作。

# file: main.py import asyncio from agency_agents import Space, Channel from agents.writer_agent import writer from agents.coder_agent import coder import os from dotenv import load_dotenv load_dotenv() async def main(): # 1. 创建一个协作空间 space = Space() # 2. 在空间中创建一个频道，可以把它想象成一个“项目会议室” project_channel = Channel(name="webpage-project") space.add_channel(project_channel) # 3. 将 Writer 和 Coder 智能体加入到这个频道 # 这样，它们就能听到频道里的所有消息并对彼此做出反应 await space.add_agent_to_channel(writer, project_channel) await space.add_agent_to_channel(coder, project_channel) # 4. 定义初始任务，并指定由 Writer 开始处理 initial_task = """ 任务：创建一个介绍 Python 编程语言的单页网站。 要求： 1. 页面需要包含 Python 的简介、主要特点、一个简单的代码示例。 2. 设计简洁美观，适合初学者阅读。 3. 最终产出为一个 index.html 文件。 请 Writer 先制定一个详细的内容大纲和设计要点。 """ print("=== 任务开始 ===") print(f"任务描述:\n{initial_task}\n") print("-" * 50) # 5. 将任务作为一条消息发送到频道，并指定发送者为“用户”（User） # 也可以不指定 sender，框架会有默认处理 initial_message = project_channel.create_message(role="user", content=initial_task) # 6. 触发智能体的协作流程 # 这里我们采用一种简单方式：让 Writer 先回复，然后 Coder 基于 Writer 的回复继续工作。 # 更复杂的协作（如自动接力）需要定义更精细的 Agent 行为逻辑或使用 Workflow 组件。 # 首先，获取 Writer 对任务的理解和计划 print("【Writer】正在思考...") writer_response = await writer.react_to_message(initial_message, project_channel) print(f"【Writer】说：\n{writer_response.content}\n") print("-" * 50) # 将 Writer 的回复作为新消息放入频道 writer_message = project_channel.create_message(role="assistant", content=writer_response.content, sender=writer.name) # 然后，让 Coder 基于 Writer 的大纲来生成代码 print("【Coder】正在基于大纲编写代码...") coder_response = await coder.react_to_message(writer_message, project_channel) print(f"【Coder】说：\n{coder_response.content}\n") print("-" * 50) # 注意：在实际的 agency-agents 高级用法中，可以通过设置 Agent 的 `loop` 或 `policy` # 来自动化这个“监听-反应”的过程。这里为了演示清晰，我们手动控制了两轮对话。 print("=== 任务阶段完成 ===") print("请检查 './output' 目录下是否生成了 index.html 文件。") if __name__ == "__main__": asyncio.run(main())

4.5 运行与结果

在终端中，运行主程序：

python main.py

你将看到类似下面的输出，展示了两个智能体的“对话”和思考过程：

=== 任务开始 === 任务描述: 任务：创建一个介绍 Python 编程语言的单页网站。 要求： 1. 页面需要包含 Python 的简介、主要特点、一个简单的代码示例。 2. 设计简洁美观，适合初学者阅读。 3. 最终产出为一个 index.html 文件。 请 Writer 先制定一个详细的内容大纲和设计要点。 -------------------------------------------------- 【Writer】正在思考... 【Writer】说： 好的，我将为“介绍Python编程语言的单页网站”制定一个详细的内容大纲和设计要点。 **一、内容大纲** 1. **页首 (Header)** * 网站主标题：`Python - 简洁强大的编程语言` * 副标题：`适合初学者入门，也是专家级开发者的利器` * 简洁的导航菜单（锚点链接）：首页 | 简介 | 特点 | 示例 | 资源 2. **简介部分 (Introduction)** * Python 是什么（通用、高级、解释型语言）。 * 创建者：Guido van Rossum，1991年首次发布。 * 设计哲学：优雅、明确、简单（“Python之禅”）。 * 主要应用领域：Web开发、数据分析、人工智能、自动化、科学计算等。 3. **主要特点部分 (Key Features)** * **易于学习阅读**：语法接近英语，缩进定义代码块。 * **解释型语言**：无需编译，快速迭代。 * **跨平台**：可在 Windows, macOS, Linux 上运行。 * **丰富的标准库**：“内置电池”哲学。 * **庞大的生态系统**：PyPI 上有数十万个第三方库。 * **社区支持**：庞大活跃的社区，资源丰富。 4. **代码示例部分 (Code Example)** * 示例1：经典的 `print("Hello, World!")`。 * 示例2：定义一个函数计算斐波那契数列，展示 Python 的简洁性。 * 示例3：使用 `requests` 库获取网页内容（需说明是第三方库）。 * 每个示例配以简短说明和输出预览。 5. **页尾 (Footer)** * 鼓励语：`开始你的 Python 之旅吧！` * 有用的链接：Python 官网、官方文档、PyPI、学习平台（如 Codecademy, Coursera）。 * 版权信息。 **二、设计要点** 1. **配色方案**： * 主色调：Python 标志性的蓝色 (#3776AB) 和黄色 (#FFD43B)。 * 背景：浅灰色 (#f8f9fa) 或白色。 * 文字：深灰色 (#333333)。 2. **字体**： * 标题：使用无衬线字体，如 `Segoe UI`, `Roboto`, `-apple-system`，显得现代。 * 正文：同上，或使用衬线字体如 `Georgia` 提升可读性（用于长段落）。 3. **布局**： * 单列流式布局，居中显示，在移动端和桌面端都有良好体验。 * 各部分之间有足够的留白。 * 代码示例区域使用等宽字体（如 `Consolas`, `Monaco`, `Courier New`），背景色为深色（如 #282c34），高亮显示语法。 4. **交互**： * 导航菜单平滑滚动到对应章节。 * 代码示例可以有一个“复制”按钮（通过少量JS实现）。 * 响应式设计，适配手机和平板。 这个大纲为 Coder 提供了清晰的结构和视觉指导，可以直接用于编写 HTML/CSS/JS 代码。 -------------------------------------------------- 【Coder】正在基于大纲编写代码... 【Coder】说： 我将根据 Writer 提供的大纲和设计要点，开始创建网站。首先，我需要创建 HTML 结构，然后添加 CSS 样式，最后实现简单的交互。 我将使用 `create_file` 工具来生成 `index.html` 文件。这个文件将包含内联的 CSS 和 JavaScript 以实现一个完整的单页应用。 （思考：我需要生成一个完整的 HTML 文件。内容要包含大纲中的所有部分，并应用设计要点中的配色和布局。我会先构建 HTML 骨架，然后填充内容，最后添加样式和脚本。） 让我开始创建文件。 （调用工具：create_file） 工具调用: create_file(filepath='./output/index.html', content='<!DOCTYPE html>\n<html lang="en">\n<head>\n <meta charset="UTF-8">\n <meta name="viewport" content="width=device-width, initial-scale=1.0">\n <title>Python - 简洁强大的编程语言</title>\n <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">\n <style>\n /* CSS 内容将在这里 */\n </style>\n</head>\n<body>\n <!-- HTML 内容将在这里 -->\n <script>\n // JavaScript 内容将在这里\n </script>\n</body>\n</html>') 工具返回: 文件 './output/index.html' 创建成功。 文件已创建成功。现在我需要填充具体的 CSS 和 HTML 内容。由于内容较长，我将分步骤进行。首先，我将用更完整的样式和结构替换文件内容。 （调用工具：create_file） ... (后续会看到 Coder 多次调用 create_file 工具，最终生成完整的 HTML 文件)

运行完成后，检查项目根目录下的./output文件夹，你应该能看到一个index.html文件。用浏览器打开它，一个根据 Writer 智能体的大纲、由 Coder 智能体自动生成的 Python 介绍网页就呈现在眼前了。

5. 常见问题与排查思路

在实践过程中，你可能会遇到一些问题。以下是常见问题的排查指南。

6. 最佳实践与工程建议

将agency-agents用于实际项目时，遵循以下建议可以提升系统的稳定性、可维护性和性能。

1. 智能体设计原则

• 单一职责：每个智能体应专注于一个明确的领域（如写作、编程、审核）。避免创建“全能”但逻辑复杂的智能体。
• 清晰的系统提示词：提示词是指引智能体行为的“宪法”。务必详细定义其角色、目标、约束和输出格式。好的提示词能大幅减少无效交互。
• 工具粒度适中：工具函数应完成一个具体的、原子性的操作。过于复杂的工具会让 LLM 难以正确调用。例如，create_file比create_web_project更原子。

2. 配置与安全管理

• 永远不要硬编码密钥：坚持使用.env文件和环境变量管理所有敏感信息（API Keys、数据库连接串）。
• 模型配置隔离：将Model的配置（如base_url,api_key,model_name）集中管理，方便切换不同环境（开发、测试、生产）或不同供应商（OpenAI, Azure, Anthropic）。
• 工具权限控制：对于有潜在危险的工具（如文件删除、数据库写入、网络请求），应在工具函数内部实现严格的参数校验和权限检查。可以考虑为智能体分配不同的工具集。

3. 状态与记忆管理

• 对话历史持久化：默认的内存可能只在会话中有效。对于需要长期记忆的应用，实现自定义的Memory类，将历史存储到数据库（如 SQLite, PostgreSQL）或向量数据库。
• 记忆窗口限制：LLM 有上下文长度限制。实现一个滑动窗口或摘要机制，只保留最近 N 条消息或自动总结早期对话，以避免 token 超限。
• 智能体状态分离：确保不同用户或会话的智能体状态是隔离的，避免信息泄露。可以通过为每个会话创建独立的Agent和Memory实例来实现。

4. 协作与流程编排

• 定义明确的协作协议：在多智能体系统中，事先约定好通信协议。例如，可以使用特定的消息格式（如 JSON）来封装任务描述、结果和元数据。
• 引入协调者（Orchestrator）：对于复杂工作流，可以创建一个专用的“协调者”智能体。它的职责不是完成具体任务，而是分解总任务、分配给专家智能体、收集结果并整合。
• 错误处理与重试：智能体调用工具或 LLM 可能失败。在Space或工作流引擎层面实现错误捕获、重试逻辑和降级方案（例如，让另一个智能体接手失败的任务）。

5. 性能与成本优化

• 缓存 LLM 响应：对于重复性或模板化的查询，可以考虑缓存 LLM 的响应结果，以降低 API 调用成本和延迟。
• 使用更便宜的模型：并非所有任务都需要 GPT-4。可以用 GPT-3.5-turbo 处理简单的分类、格式化任务，将复杂的推理留给更强的模型。
• 异步并发：agency-agents基于异步 IO。当多个智能体可以并行执行独立任务时，使用asyncio.gather来并发执行，显著提升整体吞吐量。

6. 测试与监控

• 单元测试工具函数：像测试普通 Python 函数一样，为所有@tool装饰的函数编写单元测试，确保其功能正确。
• 集成测试智能体交互：模拟用户输入，验证多智能体协作的端到端流程是否产生预期输出。
• 添加日志与可观测性：在关键节点（如收到消息、调用工具、调用 LLM、发送回复）添加详细的日志。这有助于调试复杂的交互和监控系统运行状态。

通过遵循这些最佳实践，你可以构建出不仅功能强大，而且健壮、可扩展、易维护的智能体应用系统。agency-agents提供的模块化架构为这种工程化实践奠定了良好的基础。