OPEN SOURCE / 2026.11.12
要把模型调用收成可复用的 Python 对象,并让输出和工具参数带上类型时,不必先自研一套 Agent 循环。结论先说:先按官方文档走最小安装路径。
本文是文档核验版上手指南,未在本机安装或调用模型。版本、许可以 2026 年 11 月 12 日公开页为准,之后可能会变。
能做什么、不能做什么
官方文档把 Pydantic AI 写成 typed 的 Python AI SDK:用 Agent 作为与大模型交互的主接口,可配置指令、函数工具、结构化输出类型、依赖类型和默认模型。
按 Agents 指南,一次运行可以用 run()、run_sync()、流式接口或逐步迭代。文档示例里,指定 output_type 后,结果会经 Pydantic 校验并带上类型。
默认安装还包含 OpenAI、Anthropic、Google 模型库,以及 CLI、MCP 客户端、Evals、Web UI 和 Logfire 等集成。这些是安装范围的说明,不等于你已经在自己的环境里跑通其中任何一项。
它不能替代「先锁字段契约」这类产品判断,也不能把 pip 成功当成一次真实任务已交付。调用真实模型需要相应提供商的密钥;文档排障页写明,未设置 OPENAI_API_KEY 时会报错,并可用内置 Agent('test') 在无密钥时试用。
可选的 MCP 集成在 slim 安装里依赖 fastmcp-slim[client],定位是客户端。若要把内部函数包成 MCP 服务器,应看FastMCP 文档核验指南,那是另一条路径。
环境、安装与版本纪律
官方安装页写明:Pydantic AI 在 PyPI 上的包名是 pydantic-ai,需要 Python 3.11 或更高版本。
安装页的 pip 标签给出 pip install pydantic-ai,另有 uv 标签;仓库 README 给出 uv add pydantic-ai。
![Pydantic AI Installation 页 Slim Install 一节给出 pip install pydantic-ai-slim[openai] 命令与可选 extras 分组](https://school.myshirtai.com/wp-content/uploads/2026/11/s1112-oss-pai-install.jpg)
同页说明:默认安装会带上核心依赖,以及使用 OpenAI、Anthropic、Google 模型所需的库。若只想保留某一个提供商,可改用 pydantic-ai-slim,例如 pydantic-ai-slim[openai]。
11 月 12 日查询 PyPI,pydantic-ai 的当前稳定版是 2.67.0。requires_python 为 >=3.11。
该版本上传时间为 2026-11-11T00:23:27Z,即北京时间 11 月 11 日 08:23:27。日后可能被更新或替换,生产环境应钉死当时要用的精确版本后再复核。

安装页还提醒:部分提供商的 HTTP 请求会校验操作系统信任库中的证书,而不是附带 certifi 包。精简容器或公司代理若使用私有 CA,需要在镜像里装好系统证书,或自行传入配置好的 HTTP 客户端。
官方同时提供 pydantic-ai-examples 可选组件,以及单独的 Harness 包。
文档里的 Coder 完整编码助手需要额外安装 pydantic-ai-harness[coder],不要把默认包理解成已经自带完整编码 Agent。
最小 Agent 怎么写
安装之后,官方下一步指向 Agents 指南。下面这段同步调用示例来自该页「Running Agents」一节,模型标识以 11 月 12 日文档为准,之后可能会改。本文没有执行这段代码。
from pydantic_ai import Agent
agent = Agent('openai:gpt-6.1-sol')
result_sync = agent.run_sync('What is the capital of Italy?')
print(result_sync.output)
#> The capital of Italy is Rome.

文档把 Agent 比作可在应用里复用的对象,类似小型 FastAPI 应用:先实例化一次,再在多处调用。真实调用前,需按排障页设置对应提供商的环境变量,或在 Provider 里传入密钥。
若只想先看代码能否跑通、暂不消耗模型额度,排障页建议使用内置测试模型 Agent('test')。这能验证框架接口,不能代替真实模型验收。
需要结构化结果时,把 output_type 设成 Pydantic 模型即可;要不要先锁字段契约,见先锁 JSON Schema 的判断文;本文只给实现入口。
许可、维护与停止条件
11 月 12 日核验:GitHub 仓库 pydantic/pydantic-ai 的 LICENSE 文件是 MIT License,版权人为 Pydantic Services Inc.,自 2024 年至今。
GitHub License API 的 SPDX 标识与 PyPI 的 license_expression 均为 MIT。MIT 覆盖的是这份软件,不包括你调用的模型 API 条款。
文档设有 Enterprise Support 入口,说明开源库之外另有商业支持。是否购买支持不影响 MIT 许可本身,但也不能把商业支持和「开源可随意使用模型」混为一谈。
维护信号方面,公开文档、主分支 README 与 11 月 11 日刚上传的 PyPI 版本表明项目仍在更新。本文未统计提交频率,也不把社交预览或星标数当成可用性证据。
| 条件 | 建议 | 说明 |
|---|---|---|
| Python 低于 3.11 | 先停,不要强装 | 不在官方安装范围 |
| 只想先验证接口 | 可用 Agent('test') | 官方排障页的无密钥路径 |
| 要调用真实模型 | 准备对应密钥并钉死版本 | 安装成功不等于任务跑通 |
| 只需单一提供商 | 考虑 pydantic-ai-slim | 避免装入用不到的依赖 |
| 要做 MCP 服务器 | 改走 FastMCP 文档 | 本文只覆盖客户端集成声明 |
| 许可或版本与当日不一致 | 以当时官方页为准并回查本文 | 数字和条款允许变更 |
最小行动是:确认本机 Python 至少为 3.11,按官方安装页安装并钉死版本,先用文档中的 run_sync 或 Agent('test') 看接口。在你自己留下运行记录之前,不要把这条路径当成已经跑通。
注意:这是文档核验,没有本机运行记录。能做什么以当日官方文档和 PyPI 为准;不能把 README、安装成功或示例输出注释,当成你自己的运行结果。


评论列表 (0条):
加载更多评论 Loading...