Pydantic-AI 中输出类型自定义的演进与实践

在 Pydantic-AI 0.1.8 版本中，一个重要变化是废弃了 result_type、result_tool_name 和 result_tool_description 参数，转而采用统一的 output_type 参数。这一变化虽然简化了接口设计，但也带来了一些灵活性上的挑战，特别是在需要精细控制输出工具定义的场景下。

背景与问题

在早期版本中，开发者可以通过三个独立参数来定义代理(Agent)的输出工具：

• result_type: 指定输出结果的 Pydantic 模型
• result_tool_name: 自定义工具名称
• result_tool_description: 提供详细的工具描述

这种方式允许开发者对输出工具进行全方位的定制，包括名称、描述和数据结构。然而在新版本中，这些参数被合并为单一的 output_type 参数，仅接受一个 Pydantic 模型类。这种简化虽然减少了参数数量，但也限制了开发者对工具元数据的控制能力。

实际场景中的挑战

考虑一个研究代理(ResearchAgent)的场景，该代理完成研究后需要返回一个交接消息。在旧版本中，可以这样定义：

class ResearchComplete(BaseModel):
    handoff_message: str

agent = Agent(
    result_type=ResearchComplete,
    result_tool_name="research_complete",
    result_tool_description="完成研究后调用此工具..."
)

这种定义方式能够提供：

1. 明确的工具名称("research_complete")
2. 详细的工具使用说明
3. 严格的数据结构定义

而在新版本中，同样的功能只能通过：

class ResearchComplete(BaseModel):
    """研究代理的结果"""
    handoff_message: str
    """交接消息..."""

agent = Agent(output_type=ResearchComplete)

这种方式自动生成的工具定义较为简单，缺乏详细的描述和自定义名称，可能导致模型理解不够准确。

解决方案：使用 ToolOutput 类

深入研究发现，Pydantic-AI 提供了更灵活的 ToolOutput 类来解决这一问题。开发者可以通过创建 ToolOutput 实例来完全控制输出工具的定义：

from pydantic_ai import ToolOutput

class ResearchComplete(BaseModel):
    handoff_message: str

tool_output = ToolOutput(
    type_=ResearchComplete,
    name="research_complete",
    description="完成研究后调用...",
    strict=True
)

agent = Agent(output_type=tool_output)

这种方法完美复现了旧版本的功能，同时保持了与新版本API的兼容性。ToolOutput 类提供了以下关键参数：

• type_: 指定输出数据类型
• name: 自定义工具名称
• description: 详细的工具描述
• strict: 是否严格验证输出

最佳实践建议

1. 简单场景：直接使用 Pydantic 模型作为 output_type，利用类文档字符串提供基本描述
2. 复杂场景：创建 ToolOutput 实例，全面控制工具元数据
3. 迁移策略：逐步将旧的三参数形式替换为 ToolOutput 方式
4. 文档注释：无论采用哪种方式，都应为模型字段添加详细的文档注释

总结

Pydantic-AI 的输出类型定义方式虽然经历了简化，但通过 ToolOutput 类仍然保留了足够的灵活性。开发者应当根据具体需求选择最适合的方式，在保持代码简洁的同时确保模型能够准确理解工具用途。这一演进体现了API设计在简化接口与保持灵活性之间的平衡考量。