从零开始构建Agency Swarm项目：完整开发指南

从零开始构建Agency Swarm项目：完整开发指南

agency-swarm An opensource agent orchestration framework built on top of the latest OpenAI Assistants API. 项目地址: https://gitcode.com/gh_mirrors/ag/agency-swarm

前言

Agency Swarm是一个基于多智能体协作的开发框架，它允许开发者创建由多个专业AI智能体组成的协作系统。本文将详细介绍如何从零开始构建一个完整的Agency Swarm项目，包括环境配置、项目结构创建、工具开发、智能体定义以及最终系统集成。

环境准备与配置

设置OpenAI API密钥

在开始之前，我们需要配置OpenAI API密钥，这是Agency Swarm项目运行的基础。有两种方式可以设置API密钥：

1. 代码方式设置：

from agency import set_openai_key
set_openai_key("YOUR_API_KEY")

2. 环境变量方式（推荐）： 在项目根目录下创建.env文件，添加以下内容：

OPENAI_API_KEY=sk-...

使用环境变量的方式更加安全，也便于在不同环境间切换配置。

项目结构创建

智能体模板生成

Agency Swarm提供了便捷的命令行工具来创建标准化的智能体目录结构。执行以下命令：

agency-swarm create-agent-template --name "AgentName" --description "Agent Description"

可选参数说明：

• --path：指定生成目录的路径，默认为当前目录
• --use_txt：使用.txt格式而非.md格式的指令文件

标准目录结构解析

生成的智能体目录结构如下：

AgentName/
├── files/          # 存放需要上传至OpenAI的文件
├── schemas/        # 存放OpenAPI规范文件，可自动转换为工具
├── tools/          # 存放自定义工具实现
├── AgentName.py    # 智能体主类文件
├── __init__.py     # Python包初始化文件
└── instructions.md # 智能体指令文档

完整的Agency项目结构示例：

AgencyName/
├── AgentName/            # 智能体目录
├── AnotherAgent/         # 另一个智能体目录
├── agency.py             # 主入口文件
├── agency_manifesto.md   # 全局共享指令
├── requirements.txt      # 依赖文件

这种结构设计确保了项目的模块化和可扩展性，每个智能体都有独立的工作空间。

自定义工具开发

工具类基础结构

在Agency Swarm中，工具是智能体执行特定任务的能力单元。创建自定义工具需要继承BaseTool类：

from agency_swarm.tools import BaseTool
from pydantic import Field

class MyCustomTool(BaseTool):
    """
    工具功能描述文档
    这里详细说明工具的用途和功能
    智能体会根据这些描述决定何时使用该工具
    """
    
    # 使用Pydantic定义工具参数
    example_field: str = Field(
        ..., description="参数说明，解释其用途和使用场景"
    )

    def run(self):
        """
        工具核心逻辑实现
        不需要文档字符串，不会被智能体使用
        """
        # 工具逻辑实现
        result = do_something(self.example_field)
        
        # 返回字符串格式的结果
        return "操作执行结果"

工具开发最佳实践

1. 清晰的文档字符串：确保工具类的docstring详细描述工具的功能和使用场景
2. 参数验证：充分利用Pydantic的Field来定义参数约束和说明
3. 单一职责：每个工具应该只负责一项特定功能
4. 错误处理：在run方法中妥善处理可能的异常情况

智能体角色定义

智能体类实现

每个智能体都是一个独立的Python类，继承自基础Agent类：

from agency_swarm import Agent

class Developer(Agent):
    def __init__(self):
        super().__init__(
            name="Developer",
            description="负责执行具体开发任务",
            instructions="./instructions.md",
            files_folder="./files",
            schemas_folder="./schemas",
            tools_folder="./tools",
            temperature=0.3,
            max_prompt_tokens=25000,
            examples=[]
        )

关键参数说明：

• temperature：控制智能体输出的创造性（0-1）
• max_prompt_tokens：最大提示长度限制
• examples：可提供示例对话用于few-shot学习

智能体指令设计

instructions.md文件定义了智能体的行为准则：

# 角色
你是一名开发工程师，负责编写高质量代码

# 职责
- 编写清晰、高效的代码
- 确保代码可维护性和可扩展性
- 遵循最佳实践和编码规范

# 工作流程
1. 接收任务需求
2. 分析需求并设计解决方案
3. 选择合适的工具完成任务
4. 与相关智能体协作
5. 交付成果并获取反馈

指令文件应该清晰定义智能体的角色定位、职责范围和工作流程。

构建多智能体系统

系统集成实现

在agency.py中集成所有智能体：

from agency_swarm import Agency
from .Developer import Developer
from .CEO import CEO

developer = Developer()
ceo = CEO()

agency = Agency(
    [
        ceo,  # 顶层智能体，与用户直接交互
        [ceo, developer],  # 定义通信路径
    ],
    shared_instructions='./agency_manifesto.md'
)

通信架构设计

Agency Swarm采用有向通信模型：

• 左侧智能体可以发起与右侧智能体的对话
• 右侧智能体只能响应，不能主动发起
• 顶层列表中的智能体可以直接与用户交互

例如上述代码中：

• CEO可以与用户直接对话
• CEO可以主动联系Developer
• Developer不能主动联系CEO

这种设计确保了清晰的职责划分和可控的信息流。

系统运行与测试

三种运行模式

1. Web界面模式（适合交互式开发）：

agency.demo_gradio(height=900)

2. 终端交互模式：

agency.run_demo()

3. API调用模式（适合集成到其他系统）：

completion_output = agency.get_completion(
    "请为客户创建一个新网站",
    yield_messages=False
)

开发建议

1. 初期建议使用Web界面模式，便于调试和观察智能体交互
2. 生产环境推荐使用API调用模式，便于系统集成
3. 可以利用yield_messages=True参数逐步获取响应，实现流式处理

进阶开发建议

1. 工具复用：将常用功能封装为工具，提高开发效率
2. 智能体专业化：为不同领域任务创建专门的智能体
3. 通信优化：合理设计智能体间的通信路径，避免信息过载
4. 性能监控：关注token使用情况，优化提示设计

通过以上步骤，您已经掌握了从零开始构建Agency Swarm项目的基本流程。随着项目复杂度增加，可以考虑引入版本控制、自动化测试和持续集成等工程实践来保证系统质量。

agency-swarm An opensource agent orchestration framework built on top of the latest OpenAI Assistants API. 项目地址: https://gitcode.com/gh_mirrors/ag/agency-swarm