Pydantic-AI项目：Agent工具链的故障转移机制实现

在基于LLM的智能代理开发中，工具调用失败时的优雅降级是一个常见需求。本文将以Pydantic-AI项目为例，深入探讨如何实现当Agent调用某个工具失败时自动切换到备用工具的解决方案。

核心问题场景

在实际业务场景中，我们经常会遇到这样的情况：当Agent调用某个工具（如专家查询工具）时，可能由于输入参数不匹配或数据缺失等原因返回无效结果（如空DataFrame）。此时，开发者希望系统能够自动触发备用工具（如通用AI回答工具）继续完成任务。

技术实现方案

Pydantic-AI提供了ModelRetry异常机制来实现这种故障转移。该异常被设计为当工具执行过程中遇到特定条件时，可以向Agent传递明确的指令，要求其尝试其他工具。

基础实现模式

from pydantic_ai import ModelRetry

@agent.tool
async def primary_tool(ctx):
    try:
        # 主逻辑处理
        if not valid_result:
            raise ModelRetry("请调用secondary_tool工具")
    except Exception:
        raise ModelRetry("主工具失败，请调用secondary_tool")

实际应用示例

在专家查询场景中，我们可以这样实现：

@rag_agent.tool
async def get_expert_details(ctx, name: str) -> str:
    df = pd.read_csv('data/mentors.csv')
    # 使用模糊匹配查找专家
    mask = df['Name'].apply(lambda x: fuzz.partial_ratio(str(x), name) >= 80)
    
    if df[mask].empty:
        raise ModelRetry("未找到匹配专家，请调用get_ai_response工具")
    return str(df[mask])

进阶技巧

1. 错误信息优化：在抛出ModelRetry时，提供清晰的指令有助于LLM正确理解意图
2. 条件判断：可以在工具内部实现复杂的业务逻辑判断，决定是否触发备用工具
3. 多级降级：可以设计多级备用工具链，形成完整的故障处理流程

实现原理

Pydantic-AI的Agent在执行工具时会捕获ModelRetry异常，并将其中的提示信息作为新的指令传递给LLM。LLM会根据这些指令重新规划工具调用策略，从而实现工具间的故障转移。

最佳实践建议

1. 确保备用工具具有处理主工具失败场景的能力
2. 在系统提示中明确说明工具间的备用关系
3. 对工具返回结果进行充分的验证后再决定是否降级
4. 记录工具调用链以便后续分析和优化

通过这种机制，开发者可以构建出更加健壮的Agent系统，有效提升终端用户体验。这种设计模式特别适用于数据查询、API调用等可能失败的业务场景。