Agency Swarm项目v1.x版本迁移指南：从v0.x升级到v1.x的技术解析

Agency Swarm项目v1.x版本迁移指南：从v0.x升级到v1.x的技术解析

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作为一个多智能体协作框架，在v1.x版本中进行了重大架构调整。本文将从技术角度深入解析v0.x到v1.x的迁移过程，帮助开发者理解变更背后的设计理念，并提供详细的迁移方案。

版本选择建议

当前v1.x处于beta预览阶段，建议根据项目需求选择版本：

• 生产环境：继续使用v0.x稳定版（pip install "agency-swarm<1.0.0"）
• 测试环境：可尝鲜v1.x beta版（pip install -U "agency-swarm>=1.0.0-beta.1"）

核心架构变更

v1.x版本重构了底层架构，主要变化体现在：

1. 执行核心：从直接使用OpenAI Assistants API转向基于OpenAI Agents SDK的agents.Runner
2. 状态管理：引入ThreadManager和ConversationThread管理会话状态
3. 智能体定义：Agent类现在继承自agents.Agent，整合了工具、子智能体注册等功能
4. 会话持久化：从仅存储Thread ID变为存储完整会话历史

必须处理的破坏性变更

以下变更会导致v0.x代码在v1.x中直接崩溃，需要优先处理：

1. 响应格式配置

# v0.x方式（已废弃）
agency.get_completion(response_format={"type": "json_schema", ...})

# v1.x正确方式
agent = Agent(output_type=YourPydanticModel, ...)

2. 响应验证机制

# v0.x方式（已移除）
agent = Agent(response_validator=my_validator, ...)

# v1.x替代方案
agent = Agent(output_guardrails=[my_guardrail], ...)

3. 异步方法变更

get_response()和get_response_stream()现在必须使用await调用：

# v1.x必须使用async/await
async def main():
    result = await agency.get_response("Hello")

详细迁移步骤

智能体定义变更

模型参数配置

# v0.x方式
agent = Agent(temperature=0.7, top_p=1.0)

# v1.x推荐方式
from agency_swarm import ModelSettings

agent = Agent(
    model_settings=ModelSettings(
        temperature=0.7,
        top_p=1.0,
        model="gpt-4o"
    )
)

工具定义变化

# v0.x工具类
class MyTool(BaseTool):
    arg1: str = Field(...)
    def run(self):
        return f"Result: {self.arg1}"

# v1.x函数式工具
@function_tool
def my_tool(arg1: str) -> str:
    """工具描述"""
    return f"Result: {arg1}"

机构(Agency)初始化

# v0.x方式
agency = Agency(agency_chart=[agent1, [agent1, agent2]])

# v1.x推荐方式
agency = Agency(
    agent1,  # 入口智能体
    communication_flows=[(agent1, agent2)],
    load_threads_callback=load_threads,
    save_threads_callback=save_threads
)

持久化回调调整

虽然回调函数签名不变，但数据格式从Thread ID变为完整会话历史：

def load_threads(chat_id):
    # 现在需要返回完整会话历史而非Thread ID
    return load_conversation_history(chat_id)

def save_threads(new_threads):
    # new_threads现在包含完整会话数据
    save_conversation_history(new_threads)

新增功能特性

v1.x引入了多项改进：

1. 结构化输出：通过Pydantic模型定义输出格式

   class TaskOutput(BaseModel):
       status: str
       result: str
   
   agent = Agent(output_type=TaskOutput)
   

2. 守卫机制：细粒度的输入输出验证

   @output_guardrail
   async def validate_output(ctx, agent, response):
       # 自定义验证逻辑
       return GuardrailFunctionOutput(...)
   

3. 模型设置集中管理：通过ModelSettings统一配置

迁移检查清单

1. [ ] 更新依赖版本
2. [ ] 替换所有response_format为output_type
3. [ ] 将response_validator迁移为output_guardrails
4. [ ] 更新Agency初始化方式
5. [ ] 调整持久化回调处理逻辑
6. [ ] 将同步调用改为异步模式
7. [ ] 测试所有工具功能
8. [ ] 验证结构化输出

结语

Agency Swarm v1.x通过架构重构带来了更强大的灵活性和控制能力。虽然迁移过程需要一定工作量，但新版本提供了更清晰的API设计和更强大的功能集。建议先在测试环境验证迁移效果，待v1.0正式发布后再考虑生产环境升级。

对于关键业务系统，可暂时保持v0.x版本，待v1.x稳定后再进行迁移。任何迁移问题可通过项目官方渠道反馈，开发团队会积极协助解决。

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