1. 这篇文章真正要解决的问题

如果你正在寻找一个能快速构建、测试和部署智能体（Agent）的框架，并且对市面上那些要么过于复杂、要么功能简陋的解决方案感到失望，那么 agency-agents 这个项目值得你花十分钟了解一下。它不是一个试图解决所有问题的“大而全”平台，而是一个定位精准的“脚手架”和“工具箱”。这篇文章要解决的，正是开发者在构建AI Agent应用时面临的几个核心痛点： 上手门槛高、调试过程黑盒、以及难以将原型快速转化为可部署的服务 。

很多框架要么要求你从零开始理解复杂的异步通信和状态管理，要么将你锁定在特定的云服务或模型提供商中。 agency-agents 的核心价值在于，它通过提供一套清晰、模块化的基础组件，让你能专注于Agent的逻辑本身，而不是底层的基础设施。它解决了“从想法到可运行原型”的效率问题，特别适合需要快速验证多个Agent协作场景的开发者、研究者，或是希望将AI能力以服务形式嵌入现有系统的工程师。

读完本文，你将能清晰地理解 agency-agents 的设计哲学，掌握其核心概念，并能够独立完成一个包含多个协作Agent的示例项目的搭建、运行和调试。更重要的是，你会知道它适合什么场景，不适合什么场景，以及在实际工程化中需要注意哪些“坑”。

2. 基础概念与核心原理

在深入代码之前，我们需要统一几个关键概念，这是理解 agency-agents 设计思路的基础。

Agent（智能体） ：在 agency-agents 的语境下，Agent 是一个具有特定能力、可以接收消息、进行处理并返回响应的独立实体。它可以是一个调用大语言模型（LLM）的聊天助手，也可以是一个执行代码的代码解释器，或者一个查询数据库的工具。每个 Agent 都专注于一个明确的领域。

Skill（技能） ：这是 Agent 能力的具象化。一个 Agent 可以拥有多个 Skill。例如，一个“数据分析师”Agent 可能拥有“执行SQL查询”、“绘制图表”、“生成报告摘要”等多个 Skill。在实现上，一个 Skill 通常对应一个或多个可以被调用的函数（方法）。

Space（空间） ：这是整个框架最核心的抽象。你可以把 Space 理解为一个虚拟的“协作房间”或“消息总线”。所有的 Agent 都“生活”在同一个 Space 中。当一个 Agent 需要与另一个 Agent 通信时，它不需要知道对方的具体地址或端口，只需要向 Space 发送一条消息，指定目标 Agent 的名称即可。Space 负责消息的路由、传递和生命周期管理。这种设计极大地降低了Agent间耦合度。

Message（消息） ：Agent 之间通信的基本单位。一条消息通常包含发送者、接收者、消息内容以及可能的元数据（如消息类型、优先级等）。

工作原理流程 ：

  1. 初始化 ：创建一个 Space 实例，并向其中添加多个配置好的 Agent。
  2. 触发 ：外部请求（如HTTP API）或某个Agent主动发起，向Space中的某个目标Agent发送一条Message。
  3. 路由 ：Space 接收到消息，根据消息头中的目标Agent标识，将其放入对应Agent的消息队列。
  4. 处理 ：目标Agent从其消息队列中取出消息，根据消息内容识别需要调用的Skill，并执行相应的处理逻辑（可能涉及调用LLM、执行代码、访问API等）。
  5. 响应 ：处理完成后，Agent生成响应消息。这个响应可以直接返回给最初的发送者，也可以作为新的消息发送给Space内的另一个Agent，从而形成工作流。
  6. 交付 ：Space 将最终响应交付给最初的请求方。

这种基于消息传递的架构，使得系统非常灵活。Agent之间是松耦合的，你可以随时向Space中添加或移除Agent，而不会影响其他Agent的正常工作。这也为模拟复杂的多智能体协作场景（如辩论、评审、接力任务）提供了天然的基础。

3. 环境准备与前置条件

开始实践前，请确保你的开发环境满足以下要求。我们将以一个相对通用的Python环境为例进行说明。

操作系统 ：Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04+)均可。本文命令以Linux/macOS的bash shell为例，Windows用户可在PowerShell或WSL中执行类似操作。

Python版本 ： agency-agents 通常要求 Python 3.8 或更高版本。推荐使用 Python 3.9+ 以获得更好的兼容性。

# 检查Python版本
python3 --version
# 或
python --version

依赖管理工具 ：我们使用 pip 进行包管理。强烈建议使用虚拟环境（ venv ）来隔离项目依赖，避免污染系统Python环境。

# 创建并激活虚拟环境 (Linux/macOS)
python3 -m venv agency-env
source agency-env/bin/activate

# 创建并激活虚拟环境 (Windows PowerShell)
python -m venv agency-env
.\agency-env\Scripts\Activate.ps1
# 如果遇到执行策略限制，请先以管理员身份运行：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

激活虚拟环境后，命令行提示符前通常会显示环境名称 (agency-env) 。

安装核心框架 ：使用pip从GitHub直接安装 agency-agents 。由于它可能处于活跃开发中，我们安装主分支的最新版本。

pip install git+https://github.com/msitarzewski/agency-agents.git

可选但重要的依赖 ：为了让我们后续的示例能够真正运行起来（例如调用LLM），我们还需要安装 openai 库。同时， pydantic 和 httpx 也是框架常用的依赖。

pip install openai pydantic httpx

获取API密钥 ：如果示例中涉及调用OpenAI的模型，你需要准备一个有效的 OpenAI API Key。请妥善保管，不要将其直接硬编码在代码中。

环境准备就绪后，我们就可以开始构建第一个多Agent系统了。

4. 核心流程拆解：构建一个翻译校对系统

让我们通过一个具体的场景来学习 agency-agents ：构建一个“翻译-校对”双Agent系统。用户输入一句中文，系统先将其翻译成英文，然后由另一个Agent对英文翻译进行语法和流畅度校对。

4.1 步骤一：定义Agent和Skill

首先，我们需要定义两个Agent： Translator 和 Proofreader 。每个Agent都是一个Python类，继承自框架提供的基类（通常是 Agent ）。我们将在类中定义它们各自的Skill。

# 文件：translator_proofreader.py
from agency_agents import Agent, Space
from pydantic import BaseModel
import openai
import os

# 设置OpenAI API Key (实践中应从环境变量读取)
openai.api_key = os.getenv("OPENAI_API_KEY")

class TranslationRequest(BaseModel):
    """翻译请求的数据模型"""
    text: str
    target_language: str = "English"

class Translator(Agent):
    """翻译官Agent"""
    name = "translator"  # Agent在Space中的唯一标识

    def __init__(self):
        super().__init__()
        # 可以在这里初始化一些资源，如模型客户端

    async def translate(self, request: TranslationRequest) -> str:
        """核心Skill：将文本翻译成目标语言"""
        print(f"[Translator] 收到翻译请求: {request.text} -> {request.target_language}")
        
        # 调用OpenAI API进行翻译 (简化示例)
        # 注意：这是一个模拟调用，实际应用中需要处理错误和异步
        prompt = f"请将以下中文翻译成{request.target_language}：{request.text}"
        # 在实际项目中，这里应使用异步客户端，如 `await openai.AsyncClient().chat.completions.create(...)`
        # 为简化示例，我们假设一个同步调用
        try:
            # 模拟API调用返回
            # response = await openai_async_client.chat.completions.create(...)
            translated_text = f"[模拟翻译结果] {request.text} in {request.target_language}"
            return translated_text
        except Exception as e:
            return f"翻译失败: {str(e)}"

class Proofreader(Agent):
    """校对员Agent"""
    name = "proofreader"

    async def check_grammar(self, text: str) -> str:
        """核心Skill：检查文本的语法和流畅度"""
        print(f"[Proofreader] 收到校对文本: {text}")
        
        # 模拟调用LLM进行校对
        prompt = f"请检查以下英文句子的语法和流畅度，并给出修改建议：{text}"
        # 模拟API调用
        feedback = f"[模拟校对反馈] 句子结构良好，但建议将‘simulated’改为‘demonstrated’以更正式。"
        return feedback

关键点解析 ：

  1. 继承与命名 ：每个Agent类必须继承 Agent ，并设置一个唯一的 name 。这个 name 是Space内寻址的关键。
  2. Skill定义 ：类中的异步方法（如 translate , check_grammar ）会自动被框架识别为该Agent的Skill。方法参数通常使用Pydantic模型来确保类型安全。
  3. 异步支持 ：框架基于异步（ async/await ），所以Skill方法通常是异步的，以便高效处理I/O操作（如网络请求）。

4.2 步骤二：创建Space并注册Agent

定义了Agent之后，我们需要创建一个Space，并将这些Agent的实例“添加”进去。

# 接上文 translator_proofreader.py

async def main():
    # 1. 创建协作空间
    space = Space()
    
    # 2. 实例化Agent
    translator = Translator()
    proofreader = Proofreader()
    
    # 3. 将Agent添加到Space中
    await space.add(translator)
    await space.add(proofreader)
    
    print(f"Space已启动，包含Agent: {[agent.name for agent in space.agents.values()]}")
    
    # 4. 模拟一个用户请求：先翻译，后校对
    user_input = "今天天气真好，我们一起去公园散步吧。"
    
    # 4.1 向translator发送翻译请求
    translation_request = TranslationRequest(text=user_input, target_language="English")
    # 使用 `run` 方法同步等待一个异步Skill的执行结果
    translated_result = await space.run("translator", "translate", translation_request.model_dump())
    print(f"翻译结果: {translated_result}")
    
    # 4.2 将翻译结果发送给proofreader进行校对
    if isinstance(translated_result, str) and not translated_result.startswith("翻译失败"):
        proofread_result = await space.run("proofreader", "check_grammar", translated_result)
        print(f"校对反馈: {proofread_result}")
    else:
        print("翻译步骤出错，跳过校对。")
    
    # 5. 关闭Space (清理资源)
    await space.close()

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

关键点解析 ：

  1. Space创建 ： Space() 是核心容器。
  2. 添加Agent ： await space.add(agent) 是注册Agent的标准方式。添加后，Agent即可通过Space被寻址。
  3. 调用Skill ： await space.run(agent_name, skill_name, input_data) 是调用Agent Skill的核心API。 input_data 需要是一个字典，与Skill方法的Pydantic模型对应。
  4. 异步执行 ：整个流程必须在异步上下文（ asyncio.run ）中运行。

4.3 步骤三：运行与观察

将以上两部分代码合并到一个文件 translator_proofreader.py 中，并在终端运行。

# 确保在虚拟环境中，且已安装依赖
python translator_proofreader.py

预期输出 ：

Space已启动，包含Agent: ['translator', 'proofreader']
[Translator] 收到翻译请求: 今天天气真好，我们一起去公园散步吧。 -> English
翻译结果: [模拟翻译结果] 今天天气真好，我们一起去公园散步吧。 in English
[Proofreader] 收到校对文本: [模拟翻译结果] 今天天气真好，我们一起去公园散步吧。 in English
校对反馈: [模拟校对反馈] 句子结构良好，但建议将‘simulated’改为‘demonstrated’以更正式。

至此，你已经成功构建并运行了一个最简单的多Agent协作系统。虽然这里的LLM调用是模拟的，但整个架构和通信流程是真实可用的。

5. 完整示例：集成真实LLM与HTTP服务

上面的例子使用了模拟响应。现在，我们将其升级，集成真实的OpenAI API，并暴露为HTTP服务，使其成为一个可对外提供服务的应用。

5.1 升级Agent，集成OpenAI异步客户端

我们将使用 openai 库的官方异步客户端。

# 文件：advanced_agents.py
from agency_agents import Agent, Space
from pydantic import BaseModel, Field
from openai import AsyncOpenAI
import os
from contextlib import asynccontextmanager
import uvicorn
from fastapi import FastAPI, HTTPException

# 初始化OpenAI异步客户端
client = AsyncOpenAI(api_key=os.getenv("OPENAI_API_KEY"))

class TranslationRequest(BaseModel):
    text: str = Field(..., description="待翻译的文本")
    source_lang: str = Field("中文", description="源语言")
    target_lang: str = Field("英文", description="目标语言")

class Translator(Agent):
    name = "translator"

    async def translate(self, request: TranslationRequest) -> str:
        print(f"[Translator] 翻译: {request.source_lang} -> {request.target_lang}")
        prompt = f"请将以下{request.source_lang}文本翻译成{request.target_lang}：{request.text}"
        
        try:
            response = await client.chat.completions.create(
                model="gpt-3.5-turbo",  # 可根据需要更换模型
                messages=[{"role": "user", "content": prompt}],
                temperature=0.3,
                max_tokens=500,
            )
            translated = response.choices[0].message.content.strip()
            return translated
        except Exception as e:
            print(f"OpenAI调用失败: {e}")
            return f"翻译服务暂时不可用: {str(e)}"

class Proofreader(Agent):
    name = "proofreader"

    async def review(self, text: str) -> dict:
        """校对Skill，返回结构化的结果"""
        print(f"[Proofreader] 校对文本长度: {len(text)}")
        prompt = f"""请对以下英文文本进行校对，并返回一个JSON对象，包含以下字段：
        - `corrected_text`: 修改后的文本。
        - `issues_found`: 发现的语法或表达问题列表。
        - `overall_score`: 整体质量评分 (1-10分)。
        文本内容：{text}
        """
        
        try:
            response = await client.chat.completions.create(
                model="gpt-3.5-turbo",
                messages=[
                    {"role": "system", "content": "你是一个专业的英文校对助手，请始终返回有效的JSON。"},
                    {"role": "user", "content": prompt}
                ],
                temperature=0.2,
                response_format={"type": "json_object"},  # 要求返回JSON
            )
            import json
            result = json.loads(response.choices[0].message.content)
            return result
        except Exception as e:
            print(f"Proofreading失败: {e}")
            return {"error": str(e)}

5.2 创建FastAPI应用，封装工作流

我们将使用FastAPI创建一个HTTP端点，接收用户请求，在内部协调Translator和Proofreader完成工作。

# 接上文 advanced_agents.py

# 全局Space实例
space = None

@asynccontextmanager
async def lifespan(app: FastAPI):
    """管理应用生命周期：启动时初始化Space，关闭时清理。"""
    global space
    # 启动
    space = Space()
    translator = Translator()
    proofreader = Proofreader()
    await space.add(translator)
    await space.add(proofreader)
    print("Agency Space 已启动。")
    yield
    # 关闭
    await space.close()
    print("Agency Space 已关闭。")

app = FastAPI(lifespan=lifespan)

class UserQuery(BaseModel):
    chinese_text: str

@app.post("/translate-and-review")
async def translate_and_review(query: UserQuery):
    """主要业务端点：翻译并校对"""
    if space is None:
        raise HTTPException(status_code=503, detail="Service initializing")
    
    # 步骤1: 翻译
    trans_request = TranslationRequest(text=query.chinese_text)
    try:
        translated = await space.run("translator", "translate", trans_request.model_dump())
        if "暂时不可用" in translated:
            raise HTTPException(status_code=500, detail=f"Translation failed: {translated}")
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"调用Translator失败: {e}")
    
    # 步骤2: 校对
    try:
        review_result = await space.run("proofreader", "review", translated)
        if "error" in review_result:
            raise HTTPException(status_code=500, detail=f"Proofreading error: {review_result['error']}")
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"调用Proofreader失败: {e}")
    
    # 返回整合结果
    return {
        "original_text": query.chinese_text,
        "translated_text": translated,
        "proofreading_result": review_result
    }

@app.get("/health")
async def health_check():
    """健康检查端点"""
    if space and len(space.agents) > 0:
        return {"status": "healthy", "agents": list(space.agents.keys())}
    return {"status": "unhealthy"}, 503

if __name__ == "__main__":
    # 启动FastAPI服务器
    uvicorn.run(app, host="0.0.0.0", port=8000)

5.3 运行与测试

  1. 设置环境变量 ：在启动前，确保设置了 OPENAI_API_KEY 。

    export OPENAI_API_KEY='your-api-key-here'  # Linux/macOS
# set OPENAI_API_KEY=your-api-key-here      # Windows CMD
# $env:OPENAI_API_KEY='your-api-key-here'  # Windows PowerShell

  2. 安装额外依赖 ：

    pip install fastapi uvicorn openai

  3. 启动服务 ：

    python advanced_agents.py

    看到输出 Agency Space 已启动。 和 Uvicorn running on http://0.0.0.0:8000 即表示成功。

  4. 测试API ： 使用 curl 或 Postman 等工具测试。

    curl -X POST "http://localhost:8000/translate-and-review" \
     -H "Content-Type: application/json" \
     -d '{"chinese_text": "人工智能正在深刻改变软件开发的方式。"}'

    预期响应 （示例）：

    {
  "original_text": "人工智能正在深刻改变软件开发的方式。",
  "translated_text": "Artificial intelligence is profoundly changing the way software is developed.",
  "proofreading_result": {
    "corrected_text": "Artificial intelligence is profoundly changing the way software is developed.",
    "issues_found": [],
    "overall_score": 9
  }
}

这个示例展示了一个更接近生产环境的用法：集成了真实的AI服务、提供了结构化的API、并拥有了完整的应用生命周期管理。

6. 运行结果与效果验证

成功运行上述示例后，你可以从以下几个维度验证系统的效果和状态：

  1. 服务可达性 ：访问 http://localhost:8000/health ，应返回 {"status":"healthy","agents":["translator","proofreader"]} 。这证明Space和Agent已正常初始化。

  2. 核心功能验证 ：通过 /translate-and-review 接口发送请求。验证点包括：

    • HTTP状态码 ：成功应为 200 OK 。
    • 响应结构 ：返回的JSON应包含 original_text , translated_text , proofreading_result 三个字段。
    • 业务逻辑正确性 ：
      • translated_text 应为合理的英文翻译。
      • proofreading_result 应是一个包含 corrected_text 、 issues_found 和 overall_score 的JSON对象。
    • 控制台日志 ：观察服务端控制台，应能看到 [Translator] 翻译: ... 和 [Proofreader] 校对文本长度: ... 的打印信息，证明消息在Agent间正确流转。

  3. 错误处理验证 ：你可以通过以下方式测试系统的健壮性：

    • 断开网络 ：模拟OpenAI API调用失败，观察返回的错误信息是否符合预期（如“翻译服务暂时不可用”）。
    • 传入空文本或超长文本 ：检查服务是否崩溃或返回有意义的错误。
    • 停用一个Agent ：在代码中注释掉 await space.add(proofreader) ，再次调用接口，应收到关于调用Proofreader失败的明确错误。

如果以上验证均通过，说明你已成功部署了一个基于 agency-agents 的、具备基本容错能力的多Agent服务。

7. 常见问题与排查思路

在开发和部署过程中，你可能会遇到以下典型问题。下表列出了现象、可能原因及解决方案。

问题现象 可能原因 排查方式 解决方案
ModuleNotFoundError: No module named 'agency_agents' 1. 未正确安装 agency-agents 。
2. 虚拟环境未激活或不对。		 1. 运行 pip list | grep agency 。
2. 检查命令行提示符前是否有 (agency-env) 。		 1. 确保在正确的虚拟环境中，执行 pip install git+https://github.com/msitarzewski/agency-agents.git 。
2. 确认Python解释器路径。
RuntimeError: Event loop is closed 或异步相关错误 1. 在非异步上下文中调用了 await 。
2. 异步事件循环管理冲突（常见于Jupyter或已有循环的环境）。		 检查代码是否被 asyncio.run(main()) 或类似方式正确启动。 1. 确保入口函数是 async def ，并用 asyncio.run() 调用。
2. 在Jupyter中，尝试使用 nest_asyncio.apply() （需安装 nest_asyncio ）。
调用 space.run() 时提示 Agent 'xxx' not found 1. Agent名称拼写错误。
2. Agent未被成功添加到Space。
3. space.run 在Agent完全初始化前被调用。		 1. 打印 space.agents 查看已注册的Agent名称。
2. 检查 await space.add(agent) 是否执行成功，且没有异常被吞没。		 1. 确保 Agent 类的 name 属性与调用时一致。
2. 确保 add 操作在 run 之前完成，考虑在 lifespan 或 main 函数中确保顺序。
Skill方法未被调用，或无响应 1. Skill方法不是 async 异步方法。
2. 传入 space.run 的 input_data 参数格式不对，无法反序列化到Skill方法的Pydantic模型。		 1. 检查Skill方法定义是否有 async 。
2. 在Skill方法内第一行打印日志，看是否执行。
3. 检查 input_data ，确保它是字典，且键名与Pydantic模型字段名匹配。		 1. 将所有Skill方法改为 async def 。
2. 使用 request.model_dump() 来生成输入字典。
3. 在Skill方法开始时添加 print 或日志语句用于调试。
集成真实LLM时超时或报错 1. API Key 未设置或无效。
2. 网络问题。
3. OpenAI服务端错误或额度不足。
4. 未使用异步HTTP客户端，在同步代码中调用了异步库。		 1. 检查环境变量 OPENAI_API_KEY 。
2. 使用 try...except 捕获异常并打印详细错误。
3. 检查OpenAI控制台用量和状态。		 1. 确保使用 AsyncOpenAI 客户端。
2. 为API调用设置合理的超时参数（如 timeout=30.0 ）。
3. 实现重试机制和降级策略（如返回缓存或默认值）。
多个Agent协作时，流程阻塞或顺序不对 对 await 的理解有误。 await space.run() 会等待该次调用完成，但多个 space.run 之间默认是顺序执行的。 分析业务逻辑，确认哪些步骤可以并行，哪些必须串行。 如果需要并行调用多个Agent，使用 asyncio.gather() 。例如： result1, result2 = await asyncio.gather(space.run('agent1', 'skill1', data1), space.run('agent2', 'skill2', data2)) 。

8. 最佳实践与工程建议

将 agency-agents 用于实际项目时，遵循以下最佳实践可以避免很多麻烦：

  1. 清晰的Agent与Skill边界 ：

    • 单一职责 ：每个Agent应只负责一个明确的领域（如翻译、数据库查询、代码执行）。避免创建“上帝Agent”。
    • Skill粒度 ：Skill应该足够细粒度。一个“处理用户请求”的Skill过于庞大，应拆分为“解析意图”、“查询知识库”、“生成回复”等多个Skill。

  2. 完善的错误处理与日志 ：

    • Skill内部 ：每个Skill方法内部都应使用 try...except 捕获可能出现的异常（如网络错误、API限额、数据格式错误），并返回结构化的错误信息，而不是让异常抛出导致整个Space崩溃。
    • 全局日志 ：为Space和Agent配置统一的日志系统（如Python logging 模块），记录消息的流入流出、处理耗时和错误，这对于调试分布式Agent交互至关重要。

  3. 配置与密钥管理 ：

    • 永远不要硬编码 ：将API密钥、模型名称、超时时间等配置项放在环境变量或配置文件中（如 .env 文件，使用 python-dotenv 读取）。
    • 为不同环境配置 ：开发、测试、生产环境应使用不同的配置。

  4. 性能与可观测性 ：

    • 异步优化 ：确保所有I/O操作（网络请求、文件读写、数据库查询）都是异步的，以免阻塞整个事件循环。
    • 超时设置 ：为所有对外部服务的调用（如LLM API）设置明确的超时。
    • 添加监控 ：考虑在关键路径上添加指标（如请求次数、处理延迟、错误率），可以集成像Prometheus这样的监控系统。

  5. 测试策略 ：

    • 单元测试Skill ：将Skill作为纯函数或类方法进行单元测试，模拟其依赖（如LLM客户端）。
    • 集成测试Space ：编写测试用例，启动一个包含真实Agent的Space，测试端到端的协作流程。
    • 模拟外部服务 ：在测试中使用 unittest.mock 来模拟OpenAI等外部API的响应，保证测试的稳定性和速度。

  6. 安全考虑 ：

    • 输入验证 ：尽管Pydantic提供了基础的类型验证，但对于来自外部的输入（如API请求），仍需进行严格的业务逻辑验证和清洗，防止提示词注入等攻击。
    • 权限控制 ：如果Space暴露给多用户，需要考虑在Space层面或消息路由层面添加权限校验，确保用户只能与授权的Agent交互。
    • 敏感信息 ：Agent处理的数据可能包含敏感信息。确保日志不会记录敏感数据，并且通信通道（如果涉及网络）是安全的。

  7. 版本管理与部署 ：

    • 将Agent类、Skill定义和主要工作流代码进行版本控制。
    • 使用Docker容器化你的多Agent应用，确保环境一致性。
    • 考虑使用Kubernetes或类似的编排工具来管理多个Agent服务的部署、扩缩容和健康检查。

agency-agents 提供了一个优雅的抽象层，但构建稳定、高效、安全的生产级多Agent系统，仍然需要你在这些工程实践上投入精力。它更像是一个强大的“乐高底座”，让你能快速拼接出想法原型，而最终的“建筑”是否坚固，则取决于你如何运用这些最佳实践。

9. 总结与后续学习方向

通过本文，我们深入探讨了 agency-agents 这个专注于多智能体协作的Python框架。我们从其解决的核心痛点——降低多Agent系统开发门槛——入手，逐步构建了一个从模拟到真实、从本地脚本到HTTP服务的完整示例。

关键收获 ：

  1. 理解核心抽象 ：掌握了 Agent 、 Skill 、 Space 和 Message 这四个核心概念，理解了基于消息传递的松耦合架构优势。
  2. 掌握开发流程 ：学会了定义Agent和Skill、创建和配置Space、通过 space.run 进行Agent间调用的标准流程。
  3. 完成集成实践 ：成功将框架与真实的OpenAI API以及FastAPI Web框架集成，构建了一个可对外提供服务的应用。
  4. 识别潜在问题 ：了解了在开发中可能遇到的常见错误及其排查方法。
  5. 建立工程化思维 ：获得了将原型发展为生产应用所需的最佳实践清单。

后续可以深入的方向 ：

  • 探索高级模式 ：研究框架是否支持更复杂的交互模式，如发布/订阅（Pub/Sub）、Agent的持久化状态管理、技能的动态注册与发现。
  • 可视化与调试工具 ：寻找或开发能够可视化Space内消息流、Agent状态和性能指标的调试工具，这对理解复杂协作至关重要。
  • 与其他框架对比 ：将 agency-agents 与 LangGraph 、 AutoGen 、 CrewAI 等流行的多Agent框架进行对比，分析各自在编程模型、性能、生态系统上的优劣，以便为不同项目选择最合适的工具。
  • 设计复杂工作流 ：尝试用其构建更复杂的业务场景，如一个包含“需求分析Agent”、“架构设计Agent”、“代码生成Agent”和“单元测试Agent”的软件研发流水线。

agency-agents 项目目前可能仍处于快速迭代中，建议你持续关注其GitHub仓库的更新，了解最新的特性和API变化。对于希望快速搭建多智能体协作原型、并追求代码清晰度和控制力的开发者来说，它是一个非常值得放入工具箱的选择。建议将本文的示例代码作为起点，根据你的具体需求进行修改和扩展，在实践中不断深化理解。

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

大模型安全实战】智能体安全的攻防二元性：同一种能力，为什么既是防线也是攻击面？（第4期）

avatar 龙虾开发者社区
cover

SparkSQL 之 Hive On Spark 原理分析

avatar 龙虾开发者社区

RL训练Agentic模型实现并行多轮上下文检索：匹配前沿模型且快10倍

基于RL的Agentic检索模型正在成为AI Agent效率革命的关键驱动力。并行化：从串行单次调用转向多轮高并行调用自编辑：模型在检索过程中主动裁剪不相关信息迭代优化：检索器与Agent在RL训练中双向迭代当Agentic检索的速度提升10倍以上、成本大幅下降，AI系统将能在数秒内完成以往需要数分钟的复杂信息收集——这是Agent从“对话助手”走向“行动执行者”的关键一步。参考文献：, ACL

avatar 龙虾开发者社区