pydantic/pydantic-ai¶
这个项目在系统里负责哪一层¶
PydanticAI 负责的是类型优先的 AI 应用框架层。它解决的问题是：怎样把 AI 应用里的不稳定能力，尽量往类型、校验和结构化契约这层前移。
它不是单纯聊天框架，更像一条很工程化的路线：输入要约束，输出要约束，工具要约束，依赖要显式注入，结果要能评测和观测。对 Go 开发者来说，它最值得学的不是 Python 语法，而是这条“把风险前移”的设计态度。
先抓整体结构¶
比较合适的阅读顺序是：
- 最小 agent。
- 结构化输出和 result model。
- tools 和 dependencies。
- validation。
- eval 和 observability。
- durable execution 或 graph 能力。
这样读会先看到它怎样把模型输出收进类型系统，再看到它怎样把工具和依赖做成正式边界。
一条典型执行链¶
一条典型链路大致这样跑：
- 服务端准备 agent 和依赖。
- 用户输入进入模型调用。
- 模型需要工具时，运行时按定义调用工具。
- 模型输出被解析成 result model，而不是一段随意文本。
- 校验失败时，系统有机会修复、重试或安全退出。
- 整条链的结果进入评测、日志和观测体系。
这里最关键的不是“类型很多”，而是结果从第一时间就被收进可校验对象。这样后面的业务流程、回归和排障都有抓手。
值得学的设计¶
PydanticAI 最值得学的有两点。
第一，它对结构化结果几乎是默认严肃对待的。很多系统把结构化输出当可选增强，它更像是在说：只要结果后面还要继续被系统消费，就应该尽量变成可校验对象。第二，dependency injection 被放在很靠前的位置。很多 AI demo 会把模型、数据库、工具 client 全糊在一起，跑起来快，但后面测试和替换都很痛。显式依赖不是形式主义，而是在给未来演进留空间。
这两点放到 Go 项目里同样值钱。只要你把输出 schema 化、把依赖边界理清，很多“模型系统难测难排查”的问题都会提前变轻。
适合借回自己项目的点¶
- 输入参数和模型结果尽量显式 schema 化。
- 依赖边界要清，不要把模型、工具、数据库糊成一锅。
- eval 和 observability 跟着主链走，不要变成临时脚本。
- 把校验失败当正式分支处理，而不是默认模型总会答对。
不要照抄的地方¶
- 不要误以为类型安全就等于业务安全。权限、审批、审计仍然要靠服务端治理。
- 不要为了“类型完整”把 schema 设计得比业务还复杂。
- 不要只学 result model，不学 eval 和 observability；那样只学到一半。