PydanticAI 教程：结构化输出与工具人工审批

这篇教程做一个可审计的客服工单 Agent：模型先返回经过 Pydantic 校验的结构化建议，只读工具可以自动查询，任何写入或退款动作必须等待人批准。示例以虚构数据为基础，目标是验收边界，不是让模型直接处理真实订单。

1. 安装并隔离密钥

官方安装文档要求 Python 3.10 及以上。可用 pip install pydantic-ai，或仅安装所需供应商 extra 的 pydantic-ai-slim。在开发环境设置所选模型供应商的 API Key，不把它放进源代码、日志或截图。模型名、支持的工具调用和结构化输出方式，应按该供应商当前文档核对。

2. 定义业务上可检查的输出

先定义一个工单建议对象，限制类别、严重度和说明长度。示意代码如下，实际模型名请换成已开通的型号：

from typing import Literal
from pydantic import BaseModel, Field
from pydantic_ai import Agent

class TicketAdvice(BaseModel):
    category: Literal['billing', 'technical', 'other']
    priority: int = Field(ge=1, le=5)
    summary: str = Field(min_length=8, max_length=300)
    needs_human: bool

agent = Agent('openai:YOUR_MODEL', output_type=TicketAdvice)
result = agent.run_sync('客户说：本月被扣了两次费用，请给出工单建议。')
print(result.output)

检查 result.output 是否为 TicketAdvice，并用一组固定样本统计字段验证失败率、重试次数和事实错误。Pydantic 只知道类型和你写的校验规则，不知道客户是否真的被重复扣款；账单事实必须由只读订单服务提供。

3. 把查询与写入工具分开

只读查询工具只接收经过认证的用户和订单标识，服务端再次校验租户归属。退款、发邮件等写入工具必须单独定义，并给高影响操作添加 requires_approval=True 或按参数触发 。官方的延迟工具流程会返回 ，其中有待执行工具的名称、参数和 call ID。界面要把真实操作内容展示给有权限的人，禁止用一句“批准所有”替代具体审核。