Pydantic AI 快速入门：类型化 Agent 从第一个请求到生产部署

这是什么？适合谁？

Pydantic AI 是 Pydantic 团队推出的 Python Agent 框架，用类型注解把「模型、依赖、工具、输出」固定成可检查的代码。 换模型只需要改一个字符串；供应商失败可以自动 fallback 到备用模型；同一个 Agent 可以跑在 Web 前端、终端、语音通话、持久化后台队列与 GitHub Actions 里。

适合已经有 Python 工程习惯、想让 LLM 调用像写普通函数一样可测试可维护的开发者。 如果你只是想网页上聊天，它不是给你的；如果你在写会进生产、要过代码评审的 Agent 服务，它值得先试一个 demo。

核验日期：2026-11-10。本文基于官方文档（pydantic.dev/docs/ai）与 GitHub / PyPI 公开元数据整理，AI 辅助生成，尚未完成独立实测。

前置条件与安全边界

• Python 3.9+（建议 3.10 以上）；先 python --version 确认解释器，不要假设系统自带。
• 一个模型供应商的 API key（OpenAI、Anthropic、Google、DeepSeek、Groq、Ollama 本地模型等均支持）。
• key 放环境变量，不要写进代码或提交进仓库。
• Agent 会真的执行你注册的工具函数；涉及文件、Shell、网络请求的工具先在小范围授权内试。
• 阅读所用模型供应商的数据政策：框架本地运行不等于所有数据都留在本机。

安装与第一个任务

python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install pydantic-ai
export OPENAI_API_KEY=你的key      # 或 ANTHROPIC_API_KEY / GOOGLE_API_KEY

写一个最小的结构化输出 Agent（hello.py）：

from pydantic_ai import Agent
from pydantic import BaseModel

class Result(BaseModel):
    city: str
    temperature_c: float

agent = Agent('openai:gpt-4o-mini', output_type=Result,
              instructions='回答天气问题，温度只给数字。')

result = agent.run_sync('北京今天大约多少度？')
print(result.output)   # Result(city='北京', temperature_c=12.0)
print(result.usage())  # token 用量

成功判定：输出是带类型的 Result 对象而不是裸字符串，且 usage() 能打印请求数与 token 数。

初级用法：工具调用与依赖注入

给 Agent 注册普通 Python 函数当工具，运行期类型注解会转成 JSON Schema 交给模型：

from pydantic_ai import Agent, RunContext
from dataclasses import dataclass

@dataclass
class Deps:
    db_conn: object  # 你的数据库连接或任意对象

def get_balance(ctx: RunContext[Deps], user_id: str) -> float:
    return ctx.deps.db_conn.get(user_id).balance

agent = Agent('openai:gpt-4o-mini', deps_type=Deps, tools=[get_balance])
result = agent.run_sync('查一下 user_42 的余额', deps=Deps(db_conn=my_conn))

要点：依赖对象不进提示词，模型拿不到；工具返回值会作为工具消息回给模型继续推理。

高级玩法

1. 一行换模型与 fallback

把 'openai:gpt-4o-mini' 改成 'anthropic:claude-sonnet-4' 或 'google-gla:gemini-2.0-flash' 即可切换；配合 FallbackModel 可在主供应商 429/超时自动换备用模型，不必自己写重试循环。

2. Pydantic Evals 评估输出

用 pydantic_evals 对同一批输入跑多个模型/多个 Agent 版本，按输出与工具调用轨迹打分，把「改了提示词效果变没变」变成可回归的测试用例。

3. Pydantic Graph 编排多步控制流

把多步流程写成类型化节点图，节点间传递的数据也是 Pydantic 模型；适合审批流、研究流水线这类「LLM 调用只是其中一环」的场景。

4. Pydantic AI Harness 组装编码/研究助手

Harness 以 capability 形式挂载 memory、guardrails、sub-agents、planning、context compaction、persistence，配合沙箱执行环境（Docker、E2B 等）可组装出完整编码 Agent；也可直接用内置 Coder / Researcher harness。

小技巧

• run_sync 是同步入口；Web 服务里用 agent.run（async）避免阻塞。
• output_type 给简单类型（如 str）就退化为普通文本回复，先跑通再加结构。
• instrumentation 钩子可以把每次调用接入 OpenTelemetry/Logfire，生产排障必备。
• 用 result.all_messages() 导出完整消息历史，方便离线复盘模型行为。
• 本地开发接 Ollama（ollama:qwen3 一类模型名）可做到零 API 费用调试。

常见踩坑

1. 拿到的是空输出或校验报错

output_type 模型字段太复杂或 instructions 没说清格式时，模型可能给不出合法 JSON。先用最简模型跑通，字段一个个加。

2. 工具函数抛异常导致整轮失败

在工具函数内部 try/except，把错误信息作为返回值交给模型，让模型自己决定重试还是换路。

3. 忘记 deps 类型对齐

Agent(..., deps_type=Deps) 与 run_sync(..., deps=...) 传的类型不一致会直接报校验错；两边都来自同一个 dataclass 定义即可。

4. 同步入口用在 async 框架里

FastAPI 等环境用 run_sync 会阻塞事件循环；改用 await agent.run(...)。

5. 把 key 写进代码

环境变量或 .env 管理；提交前 git grep API_KEY 自查一遍。

常见问题 FAQ

Q1: Pydantic AI 和 LangChain 有什么区别？

A: Pydantic AI 主打类型安全与简洁 API，围绕 Pydantic 的校验体系组织输入输出；LangChain 生态面更宽、抽象层更多。按团队熟悉度选，不要按星数选。

Q2: 支持哪些模型供应商？

A: 官方文档 Models & Providers 列出 OpenAI、Anthropic、Google、AWS Bedrock、Azure/Foundry、DeepSeek、Groq、Mistral、Moonshot/Kimi、Ollama、OpenRouter、xAI、Z.AI 等，也支持任意 OpenAI 兼容 API。

Q3: 商用要付费吗？

A: 框架 MIT 开源免费；你调用的模型 API、托管沙箱等第三方资源按各自计费。

Q4: 会不会把我的数据传出去？

A: 框架只在你配置的供应商之间转发；数据边界取决于所选供应商，用本地 Ollama 可完全离线。

Q5: 能脱离 Pydantic 库单独用吗？

A: 它基于 Pydantic v2 构建，结构化输出、校验都依赖 Pydantic；单独用意义不大。

权限、成本与免责声明

• 模型 API 按 token 计费；工具里的副作用（下单、发邮件、写文件）由你授权范围决定，框架不替你兜底。
• 沙箱执行环境（Docker/E2B 等）按平台各自计费。
• 本文基于公开资料整理，功能细节以官方文档为准，MagicNetWorld 尚未完成独立实测。

参考链接

• Pydantic AI 官方文档
• pydantic/pydantic-ai GitHub 仓库
• pydantic-ai PyPI