PydanticAI 项目介绍

PydanticAI 项目介绍

项目定位

Pydantic AI 是一个 Python Agent 框架，旨在将 FastAPI 级别的开发体验带给 GenAI 应用和 Agent 开发——通过类型安全、可组合的 Capabilities 和多模型抽象，让开发者构建生产级 AI 应用时感到”流畅”。

核心能力

能力	说明
类型安全	Agent 泛型 Agent[DepsT, OutputDataT]，全链路类型提示，IDE 自动补全 + pyright 类型检查
多模型支持	30+ 提供商：OpenAI、Anthropic、Google Gemini、Bedrock、Groq、Ollama、LiteLLM 等，统一 Model ABC 抽象
可组合 Capabilities	将工具、钩子、指令和模型设置打包为可复用单元——Thinking、WebSearch、MCP、Instrumentation 等
结构化输出	三种模式：Tool（函数调用）、Native（模型原生）、Prompted（prompt 注入 JSON Schema），支持渐进验证
MCP 协议集成	基于 FastMCP 的客户端，支持 Stdio/SSE/StreamableHttp 传输，工具缓存与通知失效
持久化执行	Temporal / DBOS / Prefect 三种后端，支持故障恢复和长时间运行工作流
Evals 框架	系统化评估 Agent 性能，数据集驱动的测试与 OTel Span 分析
流式输出	PartStart/Delta/End 事件模型，防抖与渐进验证，结构化数据实时流
Human-in-the-Loop	工具审批机制，延迟工具调用，支持人工审核与拒绝
Agent Spec	YAML/JSON 声明式 Agent 定义，无需代码

技术栈

维度	技术
语言	Python 3.10+
包管理	uv workspace（monorepo）
核心依赖	Pydantic v2、anyio、httpx
可选依赖	OpenAI SDK、Anthropic SDK、Google ADK、FastMCP、Logfire/OTel
类型检查	pyright
测试	pytest、inline-snapshot、pytest-recording + vcrpy
文档	MkDocs Material + mkdocstrings-python
图引擎	pydantic_graph（独立包，Builder-based API）

架构概览

快速体验

# 安装
pip install pydantic-ai

# 最简示例
from pydantic_ai import Agent

agent = Agent('anthropic:claude-sonnet-4-6', instructions='Be concise.')
result = agent.run_sync('What is 2+2?')
print(result.output)

教程导读

本教程基于 Pydantic AI main 分支（commit cff2825f）编写，覆盖以下内容：

AI 应用通用知识（12 章）

从 Pydantic AI 的源码中抽象出 Agent 框架的通用知识，每章以该项目为案例：

章节	主题	引用的 Common 教程
01	Agent 核心循环：基于图的状态机	Agent 核心循环
02	多模型适配架构	多模型适配
03	工具调用系统	工具调用协议
04	Capabilities 中间件系统	Hook 系统
05	MCP 协议集成	MCP 协议
06	结构化输出多模式	结构化输出策略
07	流式传输架构	流式传输
08	多轮对话消息管理	记忆系统
09	Agent 安全与限制	安全沙箱
10	Evals 评估框架	质量门控
11	Human-in-the-Loop 审批	Human-in-the-Loop
12	可组合能力与扩展	Skill 设计

编程核心技术（11 章）

聚焦 Pydantic AI 的具体工程实践：

章节	主题
01	uv Monorepo 与多包架构
02	类型安全设计
03	pydantic_graph 图库
04	异步编程模式
05	可观测性集成
06	测试策略
07	文档工程
08	Durable Execution 持久化
09	回退模型与故障转移
10	CLI 与 Web UI
11	Agent Spec 声明式定义