PydanticAI怎么用？从模型接入到类型化输出与工具函数的入门指南

PydanticAI是用于构建Python智能体的框架，可将模型调用、结构化结果和工具函数组织在一起。下面用客服工单整理和库存查询说明基本用法。具体参数与模型支持范围可能随版本变化，开始项目前请核对官方文档 ai.pydantic.dev。

安装与模型配置

建议在虚拟环境中安装：python -m pip install pydantic-ai。项目使用的Python版本及额外依赖，应以当前安装版本文档为准。

模型提供方通常通过模型标识和相应的凭据配置。不要把密钥写进源码或提交到版本库，可从环境变量读取，例如在运行环境中设置 OPENAI_API_KEY，再使用相应的模型标识初始化Agent。不同提供方的模型名称、认证变量及支持能力并不完全相同；示例中的配置需要按所选提供方文档调整。生产环境可使用部署平台的密钥管理功能，并限制密钥权限。

定义类型化输出

先用Pydantic模型描述客服工单字段，再让Agent按该结构返回结果。以下示例假定已经按所选供应商完成模型配置：

from pydantic import BaseModel
from pydantic_ai import Agent

class Ticket(BaseModel):
    category: str
    urgency: str
    建议: str

agent = Agent("你的模型标识", output_type=Ticket)
result = agent.run_sync("客户留言：订单已付款三天，仍未发货。整理为工单。")
ticket = result.output

实际代码中的模型标识应替换为供应商支持的值。调用返回的结构化结果可通过字段访问，也可使用Pydantic提供的模型校验与序列化能力。字段类型和格式校验有助于发现缺字段或类型不匹配，但不会验证留言内容是否真实，也不能保证紧急程度或建议判断正确。业务关键字段仍应设置明确规则，并由人检查。

注册只读工具函数

工具函数让模型在需要时调用应用提供的能力。下面把库存查询封装为只读函数，并通过依赖对象传入查询服务：

from dataclasses import dataclass
from pydantic_ai import RunContext

@dataclass
class Deps:
    inventory: object

@agent.tool
def lookup_stock(ctx: RunContext[Deps], sku: str) -> int:
    return ctx.deps.inventory.get_quantity(sku)

result = agent.run_sync(
    "查询 SKU-42 的库存，并简要说明查询结果。",
    deps=Deps(inventory=inventory_service),
)

工具参数会进入Python函数；需要严格限制输入时，可用类型标注及额外校验检查SKU格式、权限和业务范围。依赖对象适合传入数据库访问层、配置或测试替身，不要把数据库凭据直接暴露给模型。只读查询能降低误操作风险，但仍应校验查询权限、记录必要日志，并避免返回不应提供给用户的数据。工具执行可能因超时、连接失败或业务规则而报错；在应用边界捕获并记录异常，向调用方返回受控错误信息，不要将密钥、堆栈或内部数据交给模型。

同步、异步与测试

脚本或简单命令行任务可考虑同步调用 run_sync；Web服务或其他异步流程通常使用异步 run 并等待结果。具体方法签名及工具函数的同步、异步写法应以所安装版本的官方文档为准，避免在异步请求处理中阻塞事件循环。

最小测试可分三层：用固定输入验证Ticket字段与校验规则；用假库存服务测试工具收到正确SKU并返回预期数量；再对Agent流程做集成测试，检查结果结构和工具调用路径。集成测试会涉及模型配置及调用费用，宜使用受控测试输入、限制调用频率，并避免把真实客户敏感信息发送给不必要的外部服务。