PydanticAI 多智能体应用开发指南

PydanticAI 多智能体应用开发指南

pydantic-ai Agent Framework / shim to use Pydantic with LLMs 项目地址: https://gitcode.com/gh_mirrors/py/pydantic-ai

引言

在现代AI应用开发中，单一智能体往往难以处理复杂任务。PydanticAI提供了灵活的多智能体协作机制，使开发者能够构建更强大的AI应用。本文将深入探讨PydanticAI中多智能体应用的四种构建方式及其适用场景。

多智能体应用复杂度层级

PydanticAI支持从简单到复杂的多智能体协作模式：

1. 单智能体工作流：基础模式，适用于简单任务
2. 智能体委托：智能体通过工具调用其他智能体
3. 程序化智能体交接：应用代码控制多个智能体的执行顺序
4. 基于图的工作流：复杂场景下使用图状态机控制多智能体

开发者可以根据需求混合使用这些策略。

智能体委托模式详解

基本概念

智能体委托是指一个智能体（主控智能体）将部分工作委托给另一个智能体（委托智能体）执行，待委托智能体完成任务后，控制权返回主控智能体。

关键特性：

• 委托智能体执行期间会暂停主控智能体
• 委托完成后自动恢复主控智能体执行
• 智能体间可以共享使用量统计

基础示例

from pydantic_ai import Agent, RunContext
from pydantic_ai.usage import UsageLimits

# 主控智能体：负责选择最佳笑话
joke_selection_agent = Agent(
    'openai:gpt-4o',
    system_prompt='使用joke_factory工具生成笑话并选择最佳的一个'
)

# 委托智能体：负责生成笑话列表
joke_generation_agent = Agent(
    'google-gla:gemini-1.5-flash', 
    output_type=list[str]
)

@joke_selection_agent.tool
async def joke_factory(ctx: RunContext[None], count: int) -> list[str]:
    # 调用委托智能体
    r = await joke_generation_agent.run(
        f'请生成{count}个笑话',
        usage=ctx.usage  # 共享使用量统计
    )
    return r.output

# 同步执行
result = joke_selection_agent.run_sync(
    '讲个笑话',
    usage_limits=UsageLimits(request_limit=5, total_tokens_limit=300)

控制流分析

graph TD
  START --> 主控智能体
  主控智能体 --> 笑话工厂工具
  笑话工厂工具 --> 委托智能体
  委托智能体 --> 笑话工厂工具
  笑话工厂工具 --> 主控智能体
  主控智能体 --> END

依赖管理技巧

当智能体间需要共享依赖时：

1. 定义统一的依赖类型
2. 主控智能体和委托智能体使用相同的deps_type
3. 在工具调用中传递依赖

@dataclass
class ClientAndKey:
    http_client: httpx.AsyncClient
    api_key: str

# 配置智能体使用相同依赖类型
joke_selection_agent = Agent(..., deps_type=ClientAndKey)
joke_generation_agent = Agent(..., deps_type=ClientAndKey)

@joke_selection_agent.tool
async def joke_factory(ctx: RunContext[ClientAndKey], count: int):
    # 传递依赖
    result = await joke_generation_agent.run(..., deps=ctx.deps)

程序化智能体交接

适用场景

当需要根据前一个智能体的输出或用户输入决定下一个执行的智能体时，适合使用程序化交接模式。

特点：

• 智能体间完全独立
• 应用代码控制执行流程
• 支持人工干预决策

机票预订示例

class FlightDetails(BaseModel):
    flight_number: str

# 航班搜索智能体
flight_search_agent = Agent(
    'openai:gpt-4o',
    output_type=Union[FlightDetails, Failed]
)

# 座位选择智能体
seat_preference_agent = Agent(
    'openai:gpt-4o',
    output_type=Union[SeatPreference, Failed]
)

async def main():
    usage = Usage()
    
    # 第一阶段：搜索航班
    flight = await find_flight(usage)
    
    if flight:
        # 第二阶段：选择座位
        seat = await find_seat(usage)

控制流分析

graph TB
  START --> 用户输入航班信息
  用户输入航班信息 --> 航班搜索智能体
  航班搜索智能体 --> 用户输入座位偏好
  用户输入座位偏好 --> 座位选择智能体
  座位选择智能体 --> END

基于图的工作流

对于极其复杂的业务场景，PydanticAI提供了基于图的工作流引擎，允许开发者：

1. 可视化定义智能体协作流程
2. 设置条件分支
3. 实现循环逻辑
4. 管理并行执行

（详细内容请参考专门的图工作流文档）

最佳实践建议

1. 模型选择：不同智能体可以使用最适合其任务的模型
2. 使用量控制：合理设置UsageLimits防止意外开销
3. 错误处理：为每个智能体定义清晰的失败输出类型
4. 依赖设计：尽量复用依赖以减少连接开销
5. 流程拆分：复杂流程拆分为多个独立阶段

总结

PydanticAI的多智能体协作机制为复杂AI应用开发提供了强大支持。从简单的智能体委托到复杂的图工作流，开发者可以根据应用复杂度选择合适的模式。理解这些模式的适用场景和实现方式，将帮助您构建更高效、更可靠的AI应用系统。

pydantic-ai Agent Framework / shim to use Pydantic with LLMs 项目地址: https://gitcode.com/gh_mirrors/py/pydantic-ai