PydanticAI 生产实践：类型驱动的 Agent 设计模式

很多 Agent 项目后期都会遇到同一个问题：模型回答“看起来对”，但系统无法稳定消费。

PydanticAI 的优势是把输出约束前置到类型系统，让 Agent 不只是会说，还能稳定“交付可执行结果”。

核心思路：先定义结果，再让模型生成

与其先写 Prompt 再猜结果，不如先定义：

• 任务输入结构
• 任务输出结构
• 错误分支结构

这样可以把大量运行时问题提前暴露到开发阶段。

模式一：结构化输出优先

典型做法：

• 输出对象拆成小字段
• 枚举字段用有限值
• 不允许自由文本承载关键决策

当你接入下游服务（工单系统、CRM、告警平台）时，这个策略能显著降低解析失败率。

模式二：工具调用结果也要类型化

很多人只约束模型输出，却放任工具返回 dict[str, Any]。这会把混乱转移到链路后半段。

建议：

• 每个工具定义输入输出模型
• 异常结果返回可判定状态，而不是抛裸异常
• 对外部 API 增加超时和重试策略

模式三：错误恢复分层

推荐把恢复机制分成三层：

1. 模型内重试（小改提示）
2. 工具级降级（切换备选工具）
3. 任务级回退（人工接管）

这比“统一重试三次”更稳，也更易分析失败原因。

模式四：把评估嵌入开发流程

每次改提示或工具前，至少跑一组固定样例：

• 正常输入
• 边界输入
• 对抗输入

对比输出对象差异，记录回归风险。长期看，这比仅靠人工 spot check 更可靠。

总结

PydanticAI 的真正价值，不在于“又一个 Agent 框架”，而在于它强迫我们用工程化方式组织 Agent 逻辑。类型是约束，也是协作语言。

---

如果你的 Agent 需要与多个业务系统集成，类型驱动设计通常会在 1-2 个迭代内体现收益。