Pydantic AI：类型安全 Agent

为什么需要 Pydantic AI：LLM 输出不可信，用类型系统兜底

传统 LLM 应用中，让模型输出 JSON 主要靠提示词里的「请以 JSON 格式返回」，拿到字符串后要自己 json.loads、手动判空、类型转换；一旦模型多吐一个字段、把数字写成字符串或对不上 key，程序直接抛异常。工具调用（function calling，模型按声明好的函数签名生成参数并触发执行的机制）参数也没有编译期检查，模型传错参数名只在运行时暴露。这些问题在长上下文、多轮复杂任务中出现频率很高，成为线上事故的主要来源之一。

Pydantic AI 把 Pydantic v2 的校验引擎（Rust 核心 pydantic-core）直接用作 Agent 的边界守卫：声明 result_type 后，框架会引导模型生成符合结构的输出，并用完整 Pydantic 校验；校验失败时自动把错误信息回传给模型重试（重试次数可配置），而不是直接抛异常。工具函数的参数同样经过 Pydantic 校验，框架动态生成与模型能力对齐的 schema，保证「定义即约束」。

与 LangChain 的「框架大全」路线不同，Pydantic AI 只有 Agent、RunContext、Depends、Graph 这几个核心概念，没有 prompt 模板层、没有 memory 抽象，一切以类型为中心。对已经习惯 Python 类型体系的团队，心智负担和学习成本明显更低。

安装与环境配置：4 步就绪

步骤一·安装。Pydantic AI 提供两个安装入口：pydantic-ai 全量包含所有内置模型 Provider 的依赖；pydantic-ai-slim 只装核心运行时，再按需补充 extras（如 [openai]、[anthropic]、[ollama]）。生产环境推荐后者以控制依赖体积。

步骤二·配置。设置模型 API Key 环境变量。Linux/macOS 写入 shell 配置文件，Windows 用 setx；框架也支持项目根目录的 .env 文件自动加载。

步骤三·使用本地模型（可选）。没有云厂商 Key 时，安装 [ollama] extra 并在本机启动 Ollama，即可用 ollama:模型名 标识，无需任何 Key。

步骤四·验证。执行导入命令，不报错即安装成功。

# 方案一：全量安装（含所有模型 provider）pip install pydantic-ai # 方案二：精简安装，按需补充pip install "pydantic-ai-slim[openai]"pip install "pydantic-ai-slim[ollama]" # 配置 API Key（写入 ~/.bashrc 或项目 .env）export OPENAI_API_KEY="sk-你的密钥" # 验证安装python -c "from pydantic_ai import Agent; print('pydantic-ai 安装成功')"

快速上手：10 分钟跑通第一个 Agent

最小可用流程只有四步：定义输出结构（Pydantic Model）→ 实例化 Agent 并声明 result_type → 用 run_sync 同步调用 → 读取 result.data。三步代码即可完成一次结构化问答。

1. 新建项目目录并完成上节安装，创建 quickstart.py。

2. 定义一个 CityLocation 模型，字段为 city 和 country（均为 str）。

3. 创建 Agent，第一参数传入模型标识 'openai:gpt-4o'，第二参数 result_type 传入 CityLocation。

4. 调用 agent.run_sync('太阳从哪个城市升起？')，运行 python quickstart.py。

5. 观察输出：result.data 是已通过校验的 CityLocation 实例，可直接类型安全地访问 .city 和 .country，而非手写 JSON 解析。

6. 进阶：把模型标识替换为 'anthropic:claude-sonnet-4-20250514'、'gemini-1.5-pro' 或 'ollama:llama3.1'，其余代码无需改动——这是模型无关抽象的直接收益。

# quickstart.py：类型安全的城市信息问答from pydantic import BaseModelfrom pydantic_ai import Agent # 1. 定义期望的输出结构class CityLocation(BaseModel):    city: str    country: str # 2. 创建 Agent，声明输出类型agent = Agent('openai:gpt-4o', result_type=CityLocation) # 3. 同步运行一次result = agent.run_sync('太阳从哪个城市升起？') # 4. result.data 是校验通过的模型实例print(result.data)print(f"城市：{result.data.city}，国家：{result.data.country}")

核心能力详解：5 大支柱

支柱一·类型安全的结果校验。result_type 支持 Pydantic Model、TypedDict、基础类型等多种声明方式。模型返回后框架执行完整校验，失败时把错误明细注入对话并自动重试，直到结构合法或达到 max_retries 上限。这让「结构不合规」从运行时崩溃变成框架内部的自动修复循环。

支柱二·工具调用与参数校验。用 @agent.tool 装饰器注册工具，函数签名自动生成 JSON Schema 供模型调用；每次调用前参数都会经过 Pydantic 校验，类型错误会被拦截并反馈给模型修正。支持 async 工具、动态工具（通过 prepare 钩子按需启停），也支持给工具函数注入 RunContext 访问依赖。

支柱三·依赖注入。通过 deps_type 声明依赖类型，工具和系统提示词中用 RunContext[T] 访问外部对象（数据库连接、用户信息、内部 API client），运行时的 deps 参数传入实际值。这让 Agent 逻辑与基础设施解耦，测试时注入 mock 依赖即可，不必为每个用例起真实服务。

支柱四·多模型 Provider 与 MCP。模型标识统一为「provider:model」格式，内置 OpenAI、Anthropic、Gemini、Groq、Mistral、Ollama 等 Provider，切换模型只改字符串。0.2.0 起支持 MCP 协议，可把外部 MCP 服务器暴露的工具集直接接入 Agent，也可将自身作为 MCP Server 暴露给其他应用。

支柱五·Agent Graph 与 Evals。0.2.0 引入的 Graph API 把复杂流程建模为节点与边的有向图，支持条件跳转、并行节点、失败回退，替代外部编排库。内置 Evals 评测体系支持结构化断言与评分器，可把「输出结构是否正确」「是否调用了指定工具」固化为可重复执行的回归测试。

生产部署与监控：从上线到运维

部署方式一·FastAPI 集成。Agent 默认无状态，实例可安全复用。在 FastAPI 中直接用 await agent.run()，响应体就是校验后的结构化数据，天然可作为 REST API 的返回 schema；开箱即用的类型安全性让接口契约由代码声明，省去一层 DTO 转换。

部署方式二·异步与流式。长响应场景用 run_stream() 边生成边返回，配合 SSE 协议（Server-Sent Events，服务器向客户端单向推送的事件流协议）实现打字机效果；多实例部署时不要依赖进程内状态，会话上下文显式通过 message_history 参数传递。

可观测性。安装并配置 Logfire 后，Agent 的每次运行会自动被插桩：记录输入输出、token 消耗、延迟与工具调用链路，无需业务代码埋点。接入方式是 logfire.configure() 一行初始化，配合环境变量 LOGFIRE_TOKEN。生产环境还应对用户输入做长度限制，防止超长上下文推高成本。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>result_type 定义过细（如十几层的嵌套模型）会让模型频繁重试、token 成本翻倍——先宽松后收紧，按需裁剪字段。</li><li>在 async 接口里调用 run_sync 会阻塞事件循环导致请求排队，一律用 await agent.run()。</li><li>用精简包部署时容易漏装 provider extras，运行时才报「unknown provider」——把 extras 写进 pyproject.toml 或 requirements.txt。</li><li>API Key 不要写进代码或提交仓库，走环境变量或密钥管理服务，.env 加入 .gitignore。</li><li>工具函数内做重 IO（查库、调外部 API）时，要给 LLM 并发调用留好限流与超时兜底，避免打爆下游。</li></ul>

# app.py：将 Agent 暴露为 HTTP 接口from fastapi import FastAPIfrom pydantic import BaseModelfrom pydantic_ai import Agent app = FastAPI()agent = Agent('openai:gpt-4o', result_type=str) class AskRequest(BaseModel):    question: str @app.post('/ask')async def ask(req: AskRequest):    result = await agent.run(req.question)    return {'answer': result.data}

版本迭代

Pydantic AI 于 2024 年 12 月发布 0.1.0，主打类型安全 Agent；2025 年 3 月 0.2.0 完成架构重构，引入 Graph API 并拆分精简包 pydantic-ai-slim；此后以约每月一版的节奏围绕 MCP、Evals、可观测性持续迭代。0.1.x 到 0.2.x 存在 breaking change，选型与升级需关注官方迁移说明（截至训练数据，可能已有更新版本）。

AI 应用场景

常见误区

面试题