🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

大家好，我是专注于技术实战分享的博主。最近在探索AI智能体（AI Agent）的开发与集成时，发现了一个非常值得关注的GitHub项目—— agency-agents 。这个项目旨在提供一个简洁、模块化的框架，帮助开发者快速构建和编排具备不同能力的AI智能体。对于想要深入理解智能体架构，或者希望在自己的应用中集成AI决策能力的开发者来说，这是一个绝佳的实践入口。本文将带你从零开始，深入剖析 agency-agents 的核心概念、架构设计，并手把手完成一个多智能体协作的实战项目，涵盖环境搭建、代码编写、运行调试到最佳实践的全流程。

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

在深入项目之前，我们首先要厘清一个核心概念： AI智能体（AI Agent） 。它不仅仅是调用大语言模型（LLM）API的简单封装。

你可以将AI智能体理解为一个具备 感知、决策、执行和记忆 能力的自治软件实体。它接收来自环境（用户输入、系统事件、其他智能体消息）的“感知”，基于内部状态（记忆、知识）和预设目标进行“决策”，然后调用工具或API来“执行”动作，从而影响环境，并从中学习。

agency-agents 项目解决的核心问题 是：当我们需要构建一个由多个各司其职的智能体组成的复杂系统时，如何高效地管理它们之间的通信、任务分发、状态同步和工具调用？它提供了一个轻量级的框架，将智能体、工具、通信总线等概念抽象成清晰的模块，让开发者能像搭积木一样构建智能体应用。

常见应用场景包括：

• 自动化工作流 ：例如，一个“研究助理”智能体接收主题，调用“搜索”工具获取资料，然后交给“写作”智能体生成报告。
• 多角色对话系统 ：模拟会议，包含“主持人”、“技术专家”、“产品经理”等不同角色的智能体进行讨论。
• 复杂任务分解与执行 ：用户提出一个复杂需求（如“策划一次旅行”），由“规划师”智能体分解任务，并协调“预订”、“天气查询”、“路线规划”等智能体共同完成。

为什么需要 agency-agents 这样的框架？因为直接从头开始实现智能体间的消息路由、并发控制、错误处理和工具管理是复杂且容易出错的。该框架提供了这些基础设施，让开发者能更专注于智能体本身的行为逻辑设计。

2. 环境准备与版本说明

在开始编码前，请确保你的开发环境已就绪。本文示例基于一个常见的Python开发环境。

操作系统 : Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04+)均可。 编程语言 : Python 3.8 或更高版本。推荐使用 Python 3.9+ 以获得更好的兼容性。 关键依赖 :

• agency-agents : 本项目核心框架。
• openai : 用于接入OpenAI的LLM（如GPT-4），作为智能体的“大脑”。你也可以替换为其他兼容OpenAI API的库或本地模型。
• python-dotenv : 用于管理环境变量，安全存储API密钥。

版本说明 ：AI领域库更新较快，以下版本在撰写本文时测试通过，重点在于演示配置思路和核心用法，你的实际版本可能略有不同。

agency-agents==0.1.0  # 请以GitHub仓库发布的最新版本为准
openai>=1.0.0
python-dotenv>=1.0.0

IDE/工具 : 任何你熟悉的代码编辑器均可，如 VS Code、PyCharm。确保已安装Python扩展。 项目结构预览 ：我们将创建如下结构的项目：

ai_agency_demo/
├── .env                    # 存储敏感信息（如API密钥）
├── .gitignore             # Git忽略文件
├── requirements.txt       # 项目依赖列表
├── main.py               # 应用主入口
└── agents/               # 智能体模块目录
    ├── __init__.py
    ├── researcher.py     # 研究员智能体
    └── writer.py        # 写作智能体
└── tools/                # 工具模块目录
    ├── __init__.py
    └── web_search.py    # 模拟网络搜索工具

3. 核心架构与原理拆解

agency-agents 框架的核心思想是 模块化 和 消息驱动 。我们来拆解几个关键组件：

1. 智能体 (Agent) 智能体是框架中的核心执行单元。每个智能体通常包含：

• LLM客户端 ：用于处理自然语言理解和生成。
• 系统提示词 (System Prompt) ：定义智能体的角色、职责和行为规范。
• 工具集 (Tools) ：智能体可以调用的函数集合，用于执行具体操作（如计算、搜索、写文件）。
• 记忆 (Memory) ：用于存储对话历史或上下文，可以是简单的列表，也可以是向量数据库。

在 agency-agents 中，你通过继承基类并定义工具方法来创建自定义智能体。

2. 工具 (Tool) 工具是智能体扩展其能力的手段。一个工具本质上是一个Python函数，并附带有清晰的名称、描述和参数定义。框架会将这些工具的描述格式化后提供给LLM，LLM就能在需要时决定调用哪个工具。 例如，一个 search_web(query: str) 工具，其描述可能是“使用搜索引擎查询信息”。当用户问“今天天气如何？”，研究员智能体就可能调用这个工具。

3. 空间/总线 (Space/Bus) 这是框架的“神经系统”，负责所有智能体之间的通信。智能体将消息发送到总线，总线根据路由规则将消息传递给目标智能体。这种设计解耦了智能体间的直接依赖，使得系统架构更加灵活和可扩展。你可以实现同步或异步的消息传递。

4. 消息 (Message) 智能体间通信的基本单位。通常包含发送者ID、接收者ID、消息内容以及可能的元数据（如消息类型、时间戳）。内容可以是自然语言指令，也可以是结构化的数据。

工作流程简述 ：

1. 用户向某个智能体（如 Orchestrator ）发起请求。
2. 该智能体的LLM根据系统提示和用户请求，分析是否需要调用工具或与其他智能体协作。
3. 如果需要调用工具，则执行对应的Python函数并获取结果。
4. 如果需要协作，则通过总线向其他智能体发送消息。
5. 接收消息的智能体重复步骤2-4，直至最终任务完成，结果返回给用户。

4. 完整实战：构建一个“研究-写作”智能体协作系统

接下来，我们实现一个经典场景：用户输入一个研究主题，系统自动完成资料搜索和报告撰写。

4.1 创建项目并安装依赖

首先，创建项目目录并初始化虚拟环境（推荐）。

mkdir ai_agency_demo && cd ai_agency_demo
python -m venv venv
# Windows: venv\Scripts\activate
# macOS/Linux: source venv/bin/activate

创建 requirements.txt 文件并安装依赖：

agency-agents
openai
python-dotenv

pip install -r requirements.txt

4.2 配置环境变量

创建 .env 文件，存放你的OpenAI API密钥。 切记不要将此文件提交到Git！

# .env
OPENAI_API_KEY=sk-your-actual-openai-api-key-here

创建 .gitignore 文件：

# .gitignore
venv/
__pycache__/
*.pyc
.env

4.3 实现模拟搜索工具

由于真实网络搜索需要接入第三方API，我们先实现一个模拟工具。

# tools/web_search.py
"""
模拟网络搜索工具。
在实际项目中，你可以替换为SerpAPI、Google Custom Search等真实接口。
"""

def search_web(query: str, max_results: int = 3) -> str:
    """
    根据查询词模拟搜索并返回结果摘要。

    Args:
        query: 搜索查询字符串。
        max_results: 返回的最大结果数量。

    Returns:
        格式化的搜索结果字符串。
    """
    # 这是一个模拟函数。真实情况下，这里会调用搜索API。
    print(f"[工具调用] 模拟搜索: {query}")

    # 模拟返回一些静态数据
    mock_results = [
        {
            "title": f"关于{query}的全面研究 - 学术百科",
            "snippet": f"近年来，{query}领域取得了显著进展，主要包括A、B、C三个方向...",
            "url": "https://mock-site-1.com"
        },
        {
            "title": f"{query}的技术应用与未来趋势",
            "snippet": "多项案例表明，该技术已在工业界成功落地，提升了效率...",
            "url": "https://mock-site-2.com"
        },
        {
            "title": f"深入浅出理解{query}的核心概念",
            "snippet": "本文用通俗的语言解释了关键术语X和Y，并附有图解...",
            "url": "https://mock-site-3.com"
        }
    ][:max_results]

    # 将结果格式化为字符串，便于LLM阅读
    formatted_results = "\n---\n".join(
        [f"标题: {r['title']}\n摘要: {r['snippet']}\n链接: {r['url']}" for r in mock_results]
    )
    return f"针对“{query}”的搜索结果（共{len(mock_results)}条）：\n{formatted_results}"

# 可选：将函数包装成符合框架要求的工具格式（具体方式取决于agency-agents的版本）
# 例如，某些版本可能需要使用 @tool 装饰器
# from agency_agents import tool
# @tool(name="web_search", description="使用搜索引擎查询网络信息。")
# def search_web(query: str) -> str: ...

4.4 创建研究员智能体 (ResearcherAgent)

研究员负责接收主题，调用搜索工具收集信息，并整理成初步的笔记。

# agents/researcher.py
import os
from openai import OpenAI
from dotenv import load_dotenv
# 假设框架提供了Agent基类和tool装饰器（请根据实际框架源码调整导入）
# from agency_agents import Agent, tool
# 此处我们模拟一个简化实现

load_dotenv()  # 加载 .env 中的环境变量

class ResearcherAgent:
    """研究员智能体，负责信息搜集与整理。"""

    def __init__(self, agent_id: str = "researcher"):
        self.agent_id = agent_id
        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
        # 假设工具通过某种方式注册，这里我们先定义一个内部方法
        self._available_tools = [
            {
                "type": "function",
                "function": {
                    "name": "search_web",
                    "description": "使用搜索引擎查询网络信息，获取最新资料。",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "query": {"type": "string", "description": "搜索关键词。"},
                            "max_results": {"type": "integer", "description": "返回结果数，默认3", "default": 3}
                        },
                        "required": ["query"]
                    }
                }
            }
        ]
        self.system_prompt = """你是一位专业的研究员。你的任务是针对用户给定的主题，利用搜索工具（search_web）全面、高效地搜集信息。
        你需要对搜集到的信息进行初步梳理和总结，提取关键事实、数据和观点，形成一份结构清晰的研究笔记。
        笔记应包含：核心概念、现状分析、关键挑战/机遇、未来趋势等部分。
        请确保信息的准确性和客观性，并注明信息来源（如果搜索结果提供了链接）。
        你的输出将交给写作专家用于撰写正式报告。"""

    def _call_llm(self, prompt: str) -> str:
        """调用OpenAI API的简化封装。"""
        try:
            response = self.client.chat.completions.create(
                model="gpt-4o-mini",  # 可根据需要调整模型
                messages=[{"role": "system", "content": self.system_prompt},
                          {"role": "user", "content": prompt}],
                tools=self._available_tools,
                tool_choice="auto",  # 让模型自行决定是否调用工具
                temperature=0.2,
            )
            return response
        except Exception as e:
            return f"调用LLM时发生错误: {e}"

    def _execute_tool(self, tool_call):
        """执行工具调用。"""
        if tool_call.function.name == "search_web":
            # 解析参数
            import json
            args = json.loads(tool_call.function.arguments)
            from tools.web_search import search_web
            result = search_web(**args)
            return result
        else:
            return f"未知工具: {tool_call.function.name}"

    def research(self, topic: str) -> str:
        """执行研究任务的主方法。"""
        print(f"[{self.agent_id}] 收到研究主题: {topic}")
        user_prompt = f"请对以下主题进行深入研究，并整理成研究笔记：{topic}"

        llm_response = self._call_llm(user_prompt)
        message = llm_response.choices[0].message

        # 检查是否需要调用工具
        tool_calls = message.tool_calls
        if tool_calls:
            print(f"[{self.agent_id}] 决定调用工具...")
            for tool_call in tool_calls:
                tool_result = self._execute_tool(tool_call)
                # 将工具结果追加到对话中，再次请求LLM总结
                follow_up_response = self.client.chat.completions.create(
                    model="gpt-4o-mini",
                    messages=[
                        {"role": "system", "content": self.system_prompt},
                        {"role": "user", "content": user_prompt},
                        message,  # 包含工具调用的消息
                        {
                            "role": "tool",
                            "tool_call_id": tool_call.id,
                            "content": tool_result,
                        }
                    ],
                    temperature=0.2,
                )
                final_note = follow_up_response.choices[0].message.content
                print(f"[{self.agent_id}] 研究笔记生成完成。")
                return final_note
        else:
            # 如果没有工具调用，直接返回内容（可能用于简单主题）
            print(f"[{self.agent_id}] 直接生成笔记。")
            return message.content

4.5 创建写作智能体 (WriterAgent)

写作专家接收研究员整理好的笔记，将其润色成一篇结构完整、语言优美的报告。

# agents/writer.py
import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

class WriterAgent:
    """写作智能体，负责将研究笔记转化为正式报告。"""

    def __init__(self, agent_id: str = "writer"):
        self.agent_id = agent_id
        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
        self.system_prompt = """你是一位专业的科技报告撰写专家。你的文风严谨、清晰、有洞察力。
        你将收到一份由研究员整理的研究笔记，你的任务是将这份笔记转化为一篇适合公开发布或向团队汇报的正式报告。
        报告需要具备以下结构：
        1. 标题
        2. 摘要/概述
        3. 引言（背景与意义）
        4. 核心内容分析（根据笔记分小节展开）
        5. 结论与展望
        6. 参考文献（如果笔记中提供了来源）

        请确保报告逻辑连贯、论据充分、语言专业，并适当添加小标题以增强可读性。避免直接复制笔记原文，要进行提炼和重组。"""

    def write_report(self, research_note: str) -> str:
        """根据研究笔记撰写报告。"""
        print(f"[{self.agent_id}] 收到研究笔记，开始撰写报告...")
        prompt = f"请将以下研究笔记撰写成一份正式的书面报告：\n\n{research_note}"

        try:
            response = self.client.chat.completions.create(
                model="gpt-4o-mini",
                messages=[
                    {"role": "system", "content": self.system_prompt},
                    {"role": "user", "content": prompt}
                ],
                temperature=0.7,  # 写作可以稍高一点创造性
            )
            report = response.choices[0].message.content
            print(f"[{self.agent_id}] 报告撰写完成。")
            return report
        except Exception as e:
            return f"[{self.agent_id}] 撰写报告时发生错误: {e}"

4.6 集成与编排主程序

现在，我们创建主程序来协调研究员和写作专家两个智能体。这里我们模拟一个简单的线性工作流。

# main.py
import os
import asyncio
from dotenv import load_dotenv
from agents.researcher import ResearcherAgent
from agents.writer import WriterAgent

load_dotenv()

async def main():
    """主协程，编排智能体工作流。"""
    print("=== AI智能体协作系统启动 ===")
    
    # 1. 初始化智能体
    researcher = ResearcherAgent()
    writer = WriterAgent()
    
    # 2. 用户输入研究主题
    topic = input("请输入你想要研究的话题（例如：'人工智能在医疗诊断中的应用'）: ").strip()
    if not topic:
        topic = "大语言模型的最新进展"  # 默认主题
    
    print(f"\n开始处理主题: {topic}")
    
    # 3. 研究员工作
    print("\n--- 阶段一：研究 ---")
    research_note = await asyncio.to_thread(researcher.research, topic)
    print(f"\n[研究员生成笔记预览]:\n{research_note[:500]}...\n")  # 预览前500字符
    
    # 4. 写作专家工作
    print("\n--- 阶段二：写作 ---")
    final_report = await asyncio.to_thread(writer.write_report, research_note)
    
    # 5. 输出最终结果
    print("\n" + "="*50)
    print("最终报告生成完毕：")
    print("="*50)
    print(final_report)
    
    # 6. (可选) 保存报告到文件
    save = input("\n是否将报告保存到文件？(y/n): ").lower().strip()
    if save == 'y':
        filename = f"report_{topic[:20]}.md"
        with open(filename, 'w', encoding='utf-8') as f:
            f.write(final_report)
        print(f"报告已保存至: {filename}")

if __name__ == "__main__":
    asyncio.run(main())

4.7 运行与验证

在项目根目录下运行主程序：

python main.py

预期交互流程 ：

1. 程序启动，提示输入研究主题。
2. 输入后，控制台会显示 [researcher] 收到研究主题... 。
3. 研究员调用模拟搜索工具，显示 [工具调用] 模拟搜索: ... 。
4. 研究员生成笔记，并打印预览。
5. 写作专家开始工作，显示 [writer] 收到研究笔记... 。
6. 最终，一篇格式完整的报告会输出在控制台，并询问是否保存为文件。

结果说明 ：通过这个流程，你实现了一个简单的、端到端的AI智能体协作系统。研究员和写作专家各自专注，通过清晰的接口（研究笔记）进行协作，模拟了真实的内容创作流程。

5. 常见问题与排查思路

在实际开发和运行中，你可能会遇到以下问题：

问题现象	可能原因	排查思路与解决方案
导入错误： ModuleNotFoundError: No module named 'agency_agents'	1. 未正确安装 agency-agents 包。 2. 虚拟环境未激活或IDE未使用正确解释器。	1. 确认安装： pip list | grep agency-agents 。 2. 激活虚拟环境，并在终端或IDE中确认Python解释器路径指向 venv 。
OpenAI API 错误： AuthenticationError 或 InvalidRequestError	1. .env 文件中的 OPENAI_API_KEY 未设置或错误。 2. API密钥没有余额或权限。 3. 请求的模型不存在或不可用。	1. 检查 .env 文件是否存在、格式是否正确，并通过 print(os.getenv('OPENAI_API_KEY')) 调试。 2. 登录OpenAI平台检查账户状态和额度。 3. 确认代码中使用的模型名称（如 gpt-4o-mini ）在你的账户中可用。
智能体不调用工具	1. 工具的函数描述 ( description ) 不够清晰，LLM无法理解何时调用。 2. 系统提示词未明确指示智能体使用工具。 3. LLM温度 ( temperature ) 设置过高，导致输出随机性太大。	1. 优化工具描述，确保准确说明其功能和适用场景。 2. 在系统提示词中加入明确指令，如“你必须使用提供的搜索工具来获取最新信息”。 3. 尝试降低 temperature (如设为0.1或0.2)，使LLM行为更确定。
程序卡住或无响应	1. 网络问题导致API调用超时。 2. 异步编程逻辑错误，导致事件循环阻塞。 3. 智能体间消息循环（死循环）。	1. 为API调用设置合理的超时参数。 2. 检查 asyncio 使用是否正确，避免在异步函数中调用阻塞式IO。 3. 在智能体逻辑中加入防循环机制，例如限制消息转发次数。
生成的报告内容空洞或偏离主题	1. 研究员智能体收集的信息质量差（模拟工具返回固定数据）。 2. 写作专家的系统提示词约束力不够。 3. 主题过于宽泛或模糊。	1. 替换模拟工具为真实的搜索API，获取动态、高质量信息。 2. 强化写作专家的提示词，明确要求“基于给定笔记”、“不得虚构”。 3. 引导用户提出更具体的问题，或在研究员环节让LLM先对主题进行澄清和细化。

6. 最佳实践与工程建议

将智能体系统投入实际项目时，以下建议能帮助你构建更健壮、可维护的应用：

1. 智能体设计原则

• 单一职责 ：每个智能体应只负责一个明确、内聚的任务（如“搜索”、“分析”、“写作”、“审核”）。这有助于调试和迭代。
• 清晰的接口 ：智能体之间通过结构化的数据（如JSON）或定义良好的消息格式通信，避免传递冗长的自然语言导致信息损耗。
• 状态无状态化 ：尽可能设计无状态智能体，将需要持久化的状态（如对话历史、用户偏好）外置到数据库或缓存中。这便于水平扩展和故障恢复。

2. 提示词工程

• 系统提示词模板化 ：将系统提示词存储在外部文件或配置中心，便于管理和A/B测试。可以在提示词中注入动态上下文，如当前日期、用户信息。
• 分步骤思考 (Chain-of-Thought) ：对于复杂任务，在提示词中要求智能体“逐步推理”，例如“首先，分析用户需求；其次，规划步骤；然后，执行第一步...”。这能显著提升LLM的决策质量。
• 提供示例 (Few-Shot) ：在提示词中包含一两个输入输出的示例，能更有效地引导智能体遵循你期望的格式和逻辑。

3. 工具管理与安全

• 工具权限控制 ：不是所有智能体都需要所有工具。应根据智能体的角色，最小化其工具访问权限。例如，一个“只读”智能体不应有“删除文件”的工具。
• 输入验证与清理 ：所有从LLM解析出来用于调用工具的参数，都必须进行严格的验证和清理，防止注入攻击。
• 设置执行超时与限制 ：为工具调用设置超时和资源限制（如最大调用次数、内存使用），防止恶意或错误调用导致系统瘫痪。

4. 可观测性与调试

• 结构化日志 ：记录每个智能体的输入、输出、工具调用记录、耗时和Token使用量。使用JSON格式便于后续分析。
• 消息追踪 ：为每个用户会话或任务生成唯一ID，并贯穿所有智能体和工具调用，方便追踪整个工作流的执行路径。
• 开发与生产配置分离 ：开发阶段可以使用模拟工具和低成本模型；生产环境则需要切换为真实工具、高可靠性模型，并配置重试、降级策略。

5. 性能与成本优化

• 缓存策略 ：对频繁且结果不变的查询（如“今天的天气”），可以在智能体层或工具层增加缓存，减少对LLM和外部API的调用。
• 异步与非阻塞 ：利用框架的异步特性，让多个智能体可以并发执行独立子任务，大幅缩短端到端响应时间。
• 模型选型 ：根据任务复杂度选择合适的模型。简单的分类、格式化任务可以使用小型/廉价模型；复杂的推理、创作任务再使用大型模型。混合使用可以优化成本与效果。

6. 生产环境部署

• 容器化 ：使用Docker将每个智能体或整个应用打包，确保环境一致性。
• 健康检查与就绪探针 ：为智能体服务添加健康检查端点，便于Kubernetes等编排平台管理。
• 配置管理 ：将API密钥、模型端点、提示词模板等配置信息存储在环境变量或专业的配置服务中，切勿硬编码。

从零开始，我们完成了一个AI智能体协作系统的核心搭建。关键在于理解智能体作为自治单元、工具作为能力扩展、消息总线作为协作桥梁的核心架构思想。 agency-agents 这类框架的价值在于提供了实现这一思想的脚手架。

你可以在此基础上进行大量扩展：增加一个 ReviewerAgent 来审核报告质量；接入真实的搜索引擎、数据库查询工具；甚至引入 Human-in-the-loop ，在关键决策点请求人工确认。智能体系统的设计是一个持续迭代的过程，从简单的线性流程开始，逐步演进为更复杂的网状协作，是应对未来复杂AI应用挑战的有效路径。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度