← Frameworks

Pydantic AIPydantic AI

Pydantic

PythonPython 开源Open source MITMIT 编程底座Coding framework 通用harnessGeneral-purpose harness 类型安全Type-safe MCPMCP A2AA2A durable-executiondurable-execution 持久化Persistence 状态管理State management 图执行Graph execution 子代理Subagents 多AgentMulti-agent evaleval HITLHITL human-in-the-loophuman-in-the-loop 沙箱Sandbox 集成生态Integration ecosystem partial lifecycle: active 核验Checked 2026-10-23

Pydantic AI 是 Pydantic 出的 Python agent 库。

主打类型安全。官方自述把两个关键词并在一起 ——

Pydantic AI is the Python AI SDK: a typed, extensible agent loop with every model a string swap away.

「typed」是它的世界观：Pydantic 原生贯穿数据层到 agent 输出。「agent loop」是它的形态：给原语，不给你一个成品。

它与 OpenAI Agents SDK 同属这一档。但它把「类型安全」和「durable execution」两点做到明显更深。

Pydantic AI is the Python agent library from Pydantic. Its selling point is type safety. The official self-description puts two keywords together: "Pydantic AI is the Python AI SDK: a typed, extensible agent loop with every model a string swap away." "Typed" is its worldview: Pydantic runs natively from the data layer all the way to agent output. "Agent loop" is its shape: it hands you primitives, not a finished product. It sits in the same bracket as the OpenAI Agents SDK, but goes noticeably deeper on two points — type safety and durable execution.

适合与不适合When to use it, when not to

适合这几种情况：

Python 团队要「类型安全的结构化输出 + 依赖注入」
要把 agent run 变成 durable，用自己已有的引擎
做多 agent（delegation / hand-off / graph）
要 MCP 一等支持，且希望默认本地运行
既要薄 agent loop，又想要官方现成 Harness

不适合这几种情况：

TypeScript / Node 团队（看 Mastra）
追求最小依赖、不想引入 Pydantic 世界观
想完全避开任何商业组件（Logfire / Gateway 官方推荐但可选）
需要核心 SDK 自带进程级沙箱与网络策略

A fit when: you are a Python team that wants type-safe structured output plus dependency injection for your agents; you need to turn an agent run durable, using an engine you already operate; you are doing multi-agent work (delegation / hand-off / graph); you want first-class MCP support and want MCP running locally so you keep control of credentials; you want a thin agent loop and also want the official ready-made Harness (Coder / Researcher / memory / guardrails). Not a fit when: you are on TypeScript / Node (see Mastra); you want the smallest possible dependency set and do not want to bring in Pydantic; you want to avoid every commercial component (Logfire and Gateway are official recommendations but optional); you need process-level sandboxing and network policy built into the framework — the sandbox lives in the Harness / Monty, not in the core SDK.

中文生态China availability 国产 / 国内可直接用 / 备案状态 · 快照domestic / direct access / CAC filing · snapshot 2026-10-20

出品属地Origin: 国外出品foreign-made　国外主体（网信办公示名单未见对应备案主体）。foreign entity (no matching filing entity in the CAC registry).
国内使用Direct access: 大陆可直连direct OK　官网直连实测 200；PyPI 实测可达。official site measured 200 direct; PyPI measured reachable.
备案状态CAC filing: 未见于备案名单not in filing list：未见于网信办公示名单（2026-10-20 检索 13 批附件，https://www.cac.gov.cn/2024-04/02/c_1713729983803145.htm）；该产品未面向大陆公众提供服务，备案不适用。not in the CAC public registry (13 batch attachments searched 2026-10-20, https://www.cac.gov.cn/2024-04/02/c_1713729983803145.htm); the product does not serve the mainland public, so filing does not apply.

备案信息以网信办《生成式人工智能服务已备案信息》公示名单为准（按批次滚动更新，本站只抄编号不解读）；「大陆可直连」是本站从大陆网络直连实测的结果，不是厂商承诺。GitHub 类站点当日实测有波动，口径写在依据里。Filing status is quoted from the CAC public registry (updated batch by batch; this site copies the number and does not interpret it). "Direct access" is this site's own reachability measurement from a mainland network, not a vendor promise. GitHub-hosted sites fluctuated on the measurement day — the note says so.

固定坐标系Fixed coordinate system

8 个维度dimensions, 与同分区其他对象逐项可比each comparable item by item against others in the same section.

模型与开放条件Model & openness: 能接的模型 provider 最多，官方给了完整目录，换模型就是一个字符串。

官方第一卖点就是 model-agnostic。官方 overview 原文：

Model-agnostic: Supports virtually every model and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Cloud, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel, Nebius, OVHcloud, Alibaba Cloud, and SambaNova.

官方还补了一句，给自研模型留了口子。官方原文：

官方原文："If your favorite model or provider is not listed, you can easily implement a custom model."

官方目录把 provider 分四类。

模型开发商 9 家 —— OpenAI、Anthropic、Google(Gemini)、DeepSeek、Mistral 另有 Cohere / xAI / Moonshot(Kimi) / Z.AI

云平台 6 家 —— AWS Bedrock、Google Cloud(Vertex AI)、Azure Foundry、 Alibaba Cloud、Snowflake Cortex、Heroku

本地与自托管 3 个 —— Ollama（ollama:）、vLLM（vllm:）、LiteLLM（litellm:）
推理平台与网关 8 个 —— Groq、Cerebras、Hugging Face、Together、Fireworks、OpenRouter 这六个是推理平台，Vercel AI Gateway 与 Pydantic AI Gateway 是两个网关

用法是 <provider>:<model> 前缀字符串，例如 Agent('openai:gpt-5.2')。官方 models/overview 页给出 provider 目录表。每个 provider 在表里附服务类型与选择语法。

另有 fallback model 与 ModelProfile 可用。后者标记 supports_tools、supports_json_schema_output 等能力。

⚠ 一处官方自己划的边界：能力不保证跨 provider 等价。

官方原文："Feature support depends on the model and API you select, even when two services use the same API format."

换 provider 后行为完全等价，官方未给出此保证。官方口径是同一个 agent 可移植，但各家行为一致性需实测。
The most model providers connectable, with a full official catalog; switching models is one string.

The official first selling point is model-agnostic. Official overview, verbatim:

Model-agnostic: Supports virtually every model and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Cloud, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel, Nebius, OVHcloud, Alibaba Cloud, and SambaNova.

The official docs add a line leaving a door for in-house models. Official wording:

Official wording: "If your favorite model or provider is not listed, you can easily implement a custom model."

The official catalog splits providers into four groups.

9 model developers — OpenAI, Anthropic, Google(Gemini), DeepSeek, Mistral, plus Cohere / xAI / Moonshot(Kimi) / Z.AI

6 cloud platforms — AWS Bedrock, Google Cloud(Vertex AI), Azure Foundry, Alibaba Cloud, Snowflake Cortex, Heroku

3 local & self-hosted — Ollama (ollama:), vLLM (vLLM:), LiteLLM (litellm:)
8 inference platforms & gateways — Groq, Cerebras, Hugging Face, Together, Fireworks, OpenRouter (six inference platforms) plus Vercel AI Gateway and Pydantic AI Gateway (two gateways)

Usage is a <provider>:<model> prefix string, e.g. Agent('openai:gpt-5.2'). The official models/overview page gives a provider catalog table. Each provider row carries its service type and selection syntax.

There are also a fallback model and ModelProfile. The latter marks capabilities like supports_tools, supports_json_schema_output.

⚠ One boundary the official docs draw themselves: capabilities are not guaranteed equivalent across providers.

Official wording: "Feature support depends on the model and API you select, even when two services use the same API format."

Full behavioral equivalence after switching providers is not guaranteed by the official docs. The official position: the same agent is portable, but per-vendor behavioral consistency needs testing.
运行位置Where it runs: 纯 Python 库，不是一个服务 —— 安装后由你自己决定把它跑在哪。

安装是 uv add pydantic-ai（或 slim 变体）。它不启动 server。官方口径是「同一个 agent 到处运行」。官方 README 原文：

"The same agent runs everywhere you need it: behind a web frontend, in the terminal, on a voice call, on a durable background queue, in GitHub Actions, or as a plain object you call run() on."

运行面由你决定，官方给了这些入口：

嵌进 Web 前端（AG-UI / Vercel AI 事件流）
终端（官方 CLI clai）
端侧语音会话
丢进 durable background queue（那一路要把 engine 接上，见 background 轴）

谁运营 agent loop：你自己。官方另给两个可选组件 —— Pydantic AI Gateway（可自托管）做模型路由， Logfire 做观测。两者可选，不改变「库由你运营」这个事实。

官方还提供 GitHub Agentic Workflows，无头跑在 issues / PR 上。另有内置 web chat 入口。两者都建立在同一个库之上。
A pure Python library, not a service — after install, you decide where it runs.

Install is uv add pydantic-ai (or the slim variant). It does not start a server. The official position is "the same agent runs everywhere". Official README, verbatim:

"The same agent runs everywhere you need it: behind a web frontend, in the terminal, on a voice call, on a durable background queue, in GitHub Actions, or as a plain object you call run() on."

The runtime surface is yours; the official docs give these entry points:

embedded in a web frontend (AG-UI / Vercel AI event streams)
the terminal (official CLI clai)
on-device voice sessions
a durable background queue (that path requires wiring an engine — see the background axis)

Who runs the agent loop: you. Two optional official components — the Pydantic AI Gateway (self-hostable) for model routing, and Logfire for observability. Both optional; neither changes the fact that "the library is run by you".

The official docs also provide GitHub Agentic Workflows, running headless on issues / PRs. There is also a built-in web chat entry. Both are built on the same library.
本地文件Local files: 核心 agent 不带文件系统；官方 Harness 给了成套的本地文件能力。

普通 Agent 没有本地工作区概念。文件能力在 Pydantic AI Harness 里。官方 README 原文（Coding agent 段）：

"A complete coding agent in your terminal: workspace-rooted file access, allowlisted shell, repo orientation, planning, and context management that survives long sessions."

实现是一组可拆的 capabilities：

FileSystem('.')
Shell(cwd='.')
RepoContext()
SubAgents(...)
ClearToolResults()
ToolOutputLimits()

官方强调 Coder 只是把它们组合起来。官方原文：

官方原文："use it whole, or use the blocks it bundles directly; the two are equivalent"

关键边界官方写明了：文件访问是 workspace-rooted（限定工作区）， shell 是 allowlisted（白名单）。

另有 Monty，官方称其为 "a sandboxed Python interpreter that runs model-written code"。它用来跑模型写出的代码。

未知：核心 SDK 层面的文件访问默认边界（不经 Harness 时），官方未说明 核验：overview 与 harness 页已查。
The core agent carries no file system; the official Harness provides a complete local-file kit.

A plain Agent has no workspace concept. File capability lives in the Pydantic AI Harness. Official README, verbatim (Coding agent section):

"A complete coding agent in your terminal: workspace-rooted file access, allowlisted shell, repo orientation, planning, and context management that survives long sessions."

The implementation is a set of separable capabilities:

FileSystem('.')
Shell(cwd='.')
RepoContext()
SubAgents(...)
ClearToolResults()
ToolOutputLimits()

The official docs stress Coder merely composes them. Official wording:

Official wording: "use it whole, or use the blocks it bundles directly; the two are equivalent"

The key boundaries are written explicitly: file access is workspace-rooted (scoped to the workspace), shell is allowlisted (whitelist).

There is also Monty, officially "a sandboxed Python interpreter that runs model-written code". It runs code written by the model.

Unknown: the default file-access boundary at the core-SDK level (without Harness) is not stated by the official docs Verified: overview and harness pages checked.
关机后的任务Tasks after shutdown: 这是它最硬的差异点：durable execution 官方列出八种引擎， 且「每个模型与工具调用都成为一个 durable 单元」。

官方 durable execution 页原文：

"Pydantic AI allows you to build durable agents that can preserve their progress across transient API failures and application errors or restarts, and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability."

机制见官方原文：

"Each engine wraps every model request and tool call as its own durable unit"

官方 README 列举引擎为 Temporal、DBOS、Prefect、Restate、AWS Lambda、Kitaru、Airflow、Absurd，其中 "the first five co-maintained with the vendor teams"。第三方还有一种 durable execution backend builder，可以自接引擎。

接法示例：TemporalDurability() capability + PydanticAIWorkflow，官方称：

"a run working through a background queue survives restarts, failures, and long waits"

⚠ 边界要读出来：官方专设一句 ——

"Durability is not storage"

意思是：durable engine 只保证一次 run 跨崩溃存活。它不替你存对话线程，那是另设的 Persistence。

另外两条限制：run_sync() / run_stream_sync() 不能在工具内使用，须 async def。 每个 agent 只能挂一个 durable engine，挂第二个会抛 UserError。
Its hardest differentiator: the official docs list eight durable-execution engines, and "every model and tool call becomes its own durable unit".

Official durable execution page, verbatim:

"Pydantic AI allows you to build durable agents that can preserve their progress across transient API failures and application errors or restarts, and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability."

Mechanism, official wording:

"Each engine wraps every model request and tool call as its own durable unit"

The official README lists the engines as Temporal, DBOS, Prefect, Restate, AWS Lambda, Kitaru, Airflow, Absurd, with "the first five co-maintained with the vendor teams". Third parties also have a durable execution backend builder to plug in their own engine.

Connection example: the TemporalDurability() capability + PydanticAIWorkflow; officially:

"a run working through a background queue survives restarts, failures, and long waits"

⚠ Read the boundary out loud: the official docs dedicate one line —

"Durability is not storage"

Meaning: the durable engine only guarantees one run survives crashes. It does not store your conversation threads — that is a separate Persistence module.

Two more limits: run_sync() / run_stream_sync() cannot be used inside tools; use async def. Each agent can attach only one durable engine; attaching a second throws UserError.
工具与扩展Tools & extensions: 工具面有「函数工具 + MCP + A2A + capabilities 组合」四层。MCP 是核心能力。

函数工具用 @agent.tool 注册。官方原文：

官方原文："the rest of its signature and its docstring become the tool schema, arguments are validated before your code runs"

参数错误会回传给 LLM 重试。

MCP 官方支持两种方向（mcp/overview 页）：

① agent 连 MCP server，用它的工具
② agent 被放进 MCP server

推荐做法是 MCP capability。官方称：

"It runs the MCP server locally by default — keeping credentials, hooks, and tracing under your control"

并可用一个 native=True 开关选择走模型 provider 的原生 MCP（不支持时回落本地）。低层用 MCPToolset（toolsets=[...]）。 本地 MCP 默认这点对凭据可控性很重要。

⚠ A2A 已在退场。官方 integrations/a2a 页明确：

Agent.to_a2a() 与 pydantic-ai-slim[a2a] "deprecated and will be removed in 2.0"
fasta2a 已迁到 datalayer/fasta2a，并附带 Pydantic AI bridge

UI/接口：AG-UI、Vercel AI 事件流、CLI、内置 web chat、voice。另有 capabilities 组合机制。还有 YAML/JSON agent specs，可以无代码定义 agent。
The tool surface has four layers: function tools + MCP + A2A + capability composition. MCP is a core capability.

Function tools register with @agent.tool. Official wording:

Official wording: "the rest of its signature and its docstring become the tool schema, arguments are validated before your code runs"

Argument errors are fed back to the LLM for retry.

MCP officially supports two directions (mcp/overview page):

① the agent connects to an MCP server and uses its tools
② the agent is placed inside an MCP server

The recommended approach is the MCP capability. Officially:

"It runs the MCP server locally by default — keeping credentials, hooks, and tracing under your control"

and a single native=True flag opts into the model provider's native MCP (falling back to local when unsupported). Low-level: MCPToolset (toolsets=[...]). "Local by default" matters for credential control.

⚠ A2A is being retired. The official integrations/a2a page states explicitly:

Agent.to_a2a() and pydantic-ai-slim[a2a] are "deprecated and will be removed in 2.0"
fasta2a has moved to datalayer/fasta2a, with a Pydantic AI bridge

UI/interfaces: AG-UI, Vercel AI event streams, CLI, built-in web chat, voice. There is also the capabilities composition mechanism. And YAML/JSON agent specs for defining agents without code.
上下文与记忆Context & memory: 它把「持久化」和「durability」明确分成两件事，这是本维度的核心口径。

官方 durable execution 页原文：

"Durability is not storage — A durable engine keeps one run alive across crashes and restarts. It does not store your chat threads: saving a conversation and picking it up later is a different problem ... laid out in Persistence."

即：durable engine 管 run 的存活。 Persistence 管对话线程的保存与恢复，是另设模块。

Harness 另给上下文管理：官方 capabilities 列表含 memory、 context management（compaction）、persistence。官方 README 原文称 Harness：

官方原文："has everything an agent needs for complex, long-running work, snapped on as capabilities"

所以本站的「状态 ≠ 上下文」在这里被官方拆成三块： durable run（引擎）、chat thread（Persistence）、上下文压缩（compaction）。

未知：compaction 的具体裁剪策略与阈值，官方文档未给出默认值 核验：README 与 durable 页已查。
It explicitly splits "persistence" from "durability" — the core framing of this dimension.

Official durable execution page, verbatim:

"Durability is not storage — A durable engine keeps one run alive across crashes and restarts. It does not store your chat threads: saving a conversation and picking it up later is a different problem ... laid out in Persistence."

i.e. the durable engine manages run survival. Persistence manages saving and resuming conversation threads — a separate module.

Harness additionally provides context management: the official capabilities list includes memory, context management (compaction), persistence. Official README, verbatim says Harness:

Official wording: "has everything an agent needs for complex, long-running work, snapped on as capabilities"

So our "state ≠ context" is split by the official docs into three: the durable run (engine), the chat thread (Persistence), context compaction.

Unknown: the concrete trimming strategy and thresholds of compaction — the official docs give no defaults Verified: README and durable page checked.
权限与限制Permissions & limits: 人工介入是「工具级审批」，沙箱在 Harness / Monty，凭据默认本地。

HITL 工具审批是官方 overview 第 8 条：

"Human-in-the-Loop Tool Approval: Easily lets you flag that certain tool calls require approval before they can proceed, possibly depending on tool call arguments, conversation history, or user preferences."

这一条出自 deferred tools 页。它与本站其它对象的层次不同：它拦的是「这次工具调用能不能跑」，且可依据参数与历史动态判定。

guardrails 也随 Harness 提供（官方 Harness 能力列表含 guardrails）。

沙箱：官方 Monty 是 "a sandboxed Python interpreter that runs model-written code"。 Harness 的 Shell 是 allowlisted，FileSystem 是 workspace-rooted。

凭据：MCP 默认本地运行，官方称 "keeping credentials, hooks, and tracing under your control"。

未知：核心 SDK 是否有进程/网络级沙箱、以及内置认证/权限边界，官方未说明 核验：overview、durable、mcp 三页已查。企业级权限与审计由 Logfire / Gateway 那侧承担。
Human intervention is "tool-level approval"; sandboxing sits in Harness / Monty; credentials default to local.

HITL tool approval is item 8 of the official overview:

"Human-in-the-Loop Tool Approval: Easily lets you flag that certain tool calls require approval before they can proceed, possibly depending on tool call arguments, conversation history, or user preferences."

This line comes from the deferred tools page. Its level differs from other listed objects: it intercepts "may this tool call run", and can decide dynamically from arguments and history.

guardrails also ship with Harness (the official Harness capability list includes guardrails).

Sandbox: the official Monty is "a sandboxed Python interpreter that runs model-written code". Harness's Shell is allowlisted; FileSystem is workspace-rooted.

Credentials: MCP runs locally by default; officially "keeping credentials, hooks, and tracing under your control".

Unknown: whether the core SDK has process/network-level sandboxing and built-in auth/permission boundaries is not stated by the official docs Verified: overview, durable, and mcp pages checked. Enterprise-grade permissions and auditing are handled on the Logfire / Gateway side.
适合什么任务Best for: 适合：需要类型安全的 Python 团队，以及要把 agent run 变成 durable 的人。

Python 团队要做「类型安全的结构化输出 + 依赖注入」的 agent
需要把 agent run 变成 durable（跨重启、长等待、HITL），且想用自己已有的引擎，如 Temporal / DBOS / Prefect

要做多 agent（agent delegation / hand-off / graph）
需要 MCP 一等支持，且希望 MCP 本地运行以控制凭据
既要薄 agent loop，又想要官方现成的 Harness（Coder / Researcher / memory / guardrails）
想要 Pydantic 验证从数据层一路贯穿到 agent 输出

不适合：非 Python 栈、极简主义者，以及需要核心 SDK 自带沙箱的人。

TypeScript / Node 团队（该看 Mastra）
追求最小依赖、不想引入 Pydantic 与可选能力包（它的世界观是 typed end to end）
想完全避免任何商业组件 —— Logfire 与 Gateway 是官方推荐但可选，官方声明 OTel 与自托管都支持

需要框架开箱自带进程级沙箱与网络策略 —— 沙箱在 Harness / Monty，非核心 SDK
Fits: Python teams needing type safety, and anyone turning agent runs into durable ones.

Python teams building agents with "type-safe structured output + dependency injection"
You need agent runs to become durable (across restarts, long waits, HITL), and want to use engines you already have, like Temporal / DBOS / Prefect

Building multi-agent systems (agent delegation / hand-off / graph)
You need first-class MCP support and want MCP running locally to control credentials
You want both a thin agent loop and the official ready-made Harness (Coder / Researcher / memory / guardrails)
You want Pydantic validation to run end to end from the data layer to agent output

Does not fit: non-Python stacks, minimalists, and anyone needing a core-SDK-shipped sandbox.

TypeScript / Node teams (look at Mastra)
Chasing minimal dependencies, not wanting Pydantic and optional capability packages (its worldview is typed end to end)
Wanting to avoid any commercial component entirely — Logfire and Gateway are officially recommended but optional; the official docs state OTel and self-hosting are both supported

Needing framework-shipped process-level sandbox and network policy in the core — sandboxing sits in Harness / Monty, not the core SDK

头号误解Top misconception

以为它是「纯薄 harness」—— 官方今另有 Pydantic AI Harness，把 memory/guardrails/sub-agents/上下文管理打包成 capabilities，还附完整 CoderAssuming it is a purely thin harness — the official Pydantic AI Harness now bundles memory, guardrails, sub-agents and context management as capabilities, plus a complete Coder agent.
把「durability」当成「存对话」—— 官方明文 "Durability is not storage"：durable engine 只保证 run 存活，线程持久化是另一模块Reading "durability" as "conversation storage" — official docs state plainly that "Durability is not storage": the durable engine only keeps a run alive, while thread persistence is a separate module.
以为 evals / 观测必须用 Pydantic Logfire —— 官方声明是标准 OpenTelemetry，任何 OTLP 后端都能接Assuming evals / observability require Pydantic Logfire — official docs state instrumentation is standard OpenTelemetry, so any OTLP backend works.
以为 A2A 是长期内建能力 —— 官方已把 to_a2a() 标为 1.x 弃用、2.0 移除，fasta2a 迁到 datalayer/fasta2aAssuming A2A is a long-term built-in — the official docs mark Agent.to_a2a() as deprecated in 1.x and removed in 2.0, with fasta2a moved to datalayer/fasta2a.

未知项清单Known unknowns

核心 SDK 不经 Harness 时的文件访问默认边界（官方未说明，已查 overview 与 harness 页）
核心 SDK 是否有进程/网络级沙箱与内置权限边界（官方未说明，沙箱在 Harness / Monty）
Harness compaction 的默认裁剪策略与阈值（官方未说明）
Pydantic AI Gateway 的计费细节（官方定价页未单列；费率按本站的报价记录约定本站不采）
八种 durable 引擎之间的功能对齐度（官方未说明）
不同 provider 之间行为完全等价性（官方已声明「取决于所选模型与 API」）
A2A 移除后官方在 2.0 的替代路线（官方指向 datalayer/fasta2a）

The default file-access boundary of the core SDK without Harness (not stated officially; overview and harness pages checked)
Whether the core SDK has process/network-level sandboxing and built-in permission boundaries (not stated officially; sandboxing sits in Harness / Monty)
The default trimming strategy and thresholds of Harness compaction (not stated officially)
Billing details of the Pydantic AI Gateway (not itemized on the official pricing page; rates not recorded per D9)
Feature alignment across the eight durable engines (not stated officially)
Full behavioral equivalence across providers (the official docs already state it "depends on the model and API you select")
The official 2.0 replacement path after A2A removal (the official docs point to datalayer/fasta2a)

证据来源Evidence sources

判断可回到以下一手源复核。本站核验日Every judgement can be rechecked against the primary sources below. Verified on 2026-10-23，内容更新日content updated on 2026-10-08。

类型Type	名称Name	链接Link
repo	pydantic/pydantic-ai · 仓库（20,801★，MIT，Python，滚动核验 2026-10-23）pydantic/pydantic-ai · repository (20,801★, MIT, Python, rolling verification 2026-10-23)	https://github.com/pydantic/pydantic-ai
docs	主 README（"Python AI SDK / typed agent loop"、model-agnostic 清单、durable execution 八引擎、Harness、Coder）Main README ("Python AI SDK / typed agent loop", model-agnostic list, eight durable-execution engines, Harness, Coder)	https://github.com/pydantic/pydantic-ai
docs	官方文档 · Overview（Why use Pydantic AI 十二条、类型安全、MCP/A2A、HITL、durable execution）Official docs · Overview (twelve "Why use Pydantic AI" items, type safety, MCP/A2A, HITL, durable execution)	https://pydantic.dev/docs/ai/overview/
docs	官方文档 · Models and Providers（provider 目录表、`<provider>:<model>`、ModelProfile、fallback model、本地/网关）Official docs · Models and Providers (provider catalog table, `<provider>:<model>`, ModelProfile, fallback model, local/gateways)	https://pydantic.dev/docs/ai/models/overview/
docs	官方文档 · Durable Execution（八引擎、每个模型/工具调用为 durable 单元、"Durability is not storage"）Official docs · Durable Execution (eight engines, every model/tool call a durable unit, "Durability is not storage")	https://pydantic.dev/docs/ai/capabilities/durable_execution/overview/
docs	官方文档 · Graphs（pydantic-graph，可独立于 pydantic-ai 使用；类型化状态机）Official docs · Graphs (pydantic-graph, usable independently of pydantic-ai; typed state machines)	https://pydantic.dev/docs/ai/graph/graph/
docs	官方文档 · Pydantic Evals（code-first 评估、datasets/cases/evaluators、trajectory 评估）Official docs · Pydantic Evals (code-first evaluation, datasets/cases/evaluators, trajectory evaluation)	https://pydantic.dev/docs/ai/evals/evals/
docs	官方文档 · MCP（连 MCP server、被暴露为 MCP server、MCP capability 默认本地运行、native=True）Official docs · MCP (connect to MCP servers, be exposed as an MCP server, MCP capability local by default, native=True)	https://pydantic.dev/docs/ai/mcp/overview/
docs	官方文档 · Dependencies（类型安全依赖注入、RunContext、可覆盖以便测试）Official docs · Dependencies (type-safe dependency injection, RunContext, overridable for testing)	https://pydantic.dev/docs/ai/core-concepts/dependencies/
docs	官方文档 · Multi-agent Applications（五个复杂度层级：单 agent、delegation、hand-off、graph、Deep Agents）Official docs · Multi-agent Applications (five complexity tiers: single agent, delegation, hand-off, graph, Deep Agents)	https://pydantic.dev/docs/ai/guides/multi-agent-applications/
docs	官方文档 · Agent2Agent (A2A)（to_a2a 1.x 弃用、2.0 移除；fasta2a 迁至 datalayer/fasta2a）Official docs · Agent2Agent (A2A) (to_a2a deprecated in 1.x, removed in 2.0; fasta2a moved to datalayer/fasta2a)	https://pydantic.dev/docs/ai/integrations/a2a/
pricing	官方定价页（核验 2026-10-08：Pydantic 库永久 MIT 免费；Logfire 免费档含 1,000 万 spans/月、另有 Pro 档；报价按本站的报价记录约定不存）Official pricing page (verified 2026-10-08: Pydantic libraries permanently MIT and free; Logfire free tier includes 10M spans/month, plus a Pro tier; quotes not stored per D9)	https://pydantic.dev/pricing/
changelog	Releases（v2.54.0 @ 2026-10-02）Releases (v2.54.0 @ 2026-10-02)	https://github.com/pydantic/pydantic-ai/releases

实测记录Measured runs

本档未跑集成与性能实测；结论只覆盖 API 与官方文档披露的能力面。

实测建议（按编程底座 + 类型安全 / durable 维度定制）：

#	测什么	为什么值得测
1	最小 hello agent 要几个文件、多少行	量化「薄 agent loop」的真实上手成本
2	给一个 Pydantic 输出模型，验证 run 必返回该类型	官方卖点是 typed end to end，要验证「返库即类型」
3	接 Ollama 本地模型跑通一个带工具与结构化输出的 agent	官方目录单列 Ollama，验证真实可行性
4	用 TemporalDurability 跑一个长任务，kill 进程后续跑	官方 durable 承诺的核心，必须验证
5	agent delegation / hand-off / graph 三种多 agent 写法代码量对比	官方给五种复杂度层级，验证选型建议
6	MCP capability 默认本地 vs `native=True` 的凭据与行为差异	官方强调默认本地保凭据可控，值得验证

This site has not completed measured runs. The test protocol is at protocols/framework/_protocol.md.

Suggested runs (tailored to coding-base + type-safety / durable dimensions):

#	What to test	Why it is worth testing
1	How many files and lines for a minimal hello agent	quantifies the real onboarding cost of the "thin agent loop"
2	Give it a Pydantic output model; verify the run must return that type	the official selling point is typed end to end — verify "the returned value is the type"
3	Run an agent with tools and structured output on an Ollama local model	the official catalog lists Ollama separately — verify real feasibility
4	Run a long task with TemporalDurability, kill the process, then resume	the core of the official durable promise — must verify
5	Code-volume comparison of agent delegation / hand-off / graph for multi-agent	the official docs give five complexity tiers — verify the selection advice
6	Credential and behavior differences: MCP capability local-by-default vs `native=True`	the official docs stress local-by-default keeps credentials under control — worth verifying

与 OpenAI Agents SDK 的对照：本站最该给读者看的一张表Versus the OpenAI Agents SDK: the table our readers most need to see

两者都是「给你 agent loop 的 Python 库」，风格相近。差异点很具体：

	OpenAI Agents SDK	Pydantic AI
类型体系	可选 dataclass / Pydantic 输出	Pydantic 原生：typed 输出 + typed 依赖注入 + typed tools
非 OpenAI 模型	litellm / any-llm 适配器	provider 目录原生：`<provider>:<model>` 字符串切换，含本地 Ollama/vLLM
durable execution	无独立引擎（自建）	官方八种引擎（Temporal/DBOS/Prefect/Restate/AWS Lambda/Kitaru/Airflow/Absurd）
上层能力	primitives-only	另有 Pydantic AI Harness（memory/guardrails/sub-agents/compaction + 现成 Coder）
观测	Traces 默认上报 OpenAI 后端	标准 OpenTelemetry，任何 OTLP 后端；Logfire 可选

一句口诀：要 Python 的「类型安全 + durable」选 Pydantic AI；要极简、要 guardrails 内建、认 OpenAI 生态选 OpenAI Agents SDK。

Both are "Python libraries that give you an agent loop", similar in style. The differences are concrete:

	OpenAI Agents SDK	Pydantic AI
Type system	optional dataclass / Pydantic output	Pydantic-native: typed output + typed dependency injection + typed tools
Non-OpenAI models	litellm / any-llm adapters	native provider catalog: `<provider>:<model>` string switching, incl. local Ollama/vLLM
durable execution	no dedicated engine (DIY)	eight official engines (Temporal/DBOS/Prefect/Restate/AWS Lambda/Kitaru/Airflow/Absurd)
Upper capabilities	primitives-only	plus Pydantic AI Harness (memory/guardrails/sub-agents/compaction + a ready Coder)
Observability	Traces report to the OpenAI backend by default	standard OpenTelemetry, any OTLP backend; Logfire optional

One-line rule: want Python's "type safety + durable" → Pydantic AI; want minimalism, built-in guardrails, and the OpenAI ecosystem → OpenAI Agents SDK.

model-agnostic：provider 目录是官方的第一卖点Model-agnostic: the provider catalog is the official first selling point

官方 overview 原文：

Model-agnostic: Supports virtually every model and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Cloud, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel, Nebius, OVHcloud, Alibaba Cloud, and SambaNova.

用法是前缀字符串 Agent('openai:gpt-5.2')。换模型是 "a string swap away"，也就是改一个字符串。

官方 models/overview 页有完整的 provider 目录表。 Ollama / vLLM / LiteLLM 这些本地与自托管路径都在其中。

⚠ 一处官方自己划的边界：能力不保证跨 provider 等价。

"Feature support depends on the model and API you select, even when two services use the same API format."

Official overview, verbatim:

Model-agnostic: Supports virtually every model and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Cloud, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel, Nebius, OVHcloud, Alibaba Cloud, and SambaNova.

Usage is a prefix string Agent('openai:gpt-5.2'). Switching models is "a string swap away" — change one string.

The official models/overview page has the full provider catalog table. Local and self-hosted paths like Ollama / vLLM / LiteLLM are all in it.

⚠ One boundary the official docs draw themselves: capabilities are not guaranteed equivalent across providers.

"Feature support depends on the model and API you select, even when two services use the same API format."

durable execution：官方八引擎，且「每个模型与工具调用都成为 durable 单元」Durable execution: eight official engines, and "every model and tool call becomes a durable unit"

这是它区别于 OpenAI Agents SDK 的核心。 官方 durable execution 页原文：

Pydantic AI allows you to build durable agents that can preserve their progress across transient API failures and application errors or restarts ... Each engine wraps every model request and tool call as its own durable unit.

引擎清单（README 原文）：Temporal、DBOS、Prefect、Restate、AWS Lambda、Kitaru、Airflow、Absurd。前五个 "co-maintained with the vendor teams"。第三方还可走 backend builder，自接引擎。

⚠ 必须读出来的一条边界：官方专设一句 ——

Durability is not storage. A durable engine keeps one run alive across crashes and restarts. It does not store your chat threads: saving a conversation and picking it up later is a different problem ... laid out in Persistence.

即：durable run 与对话线程持久化是两件事，正是本站「状态 ≠ 上下文」的同构表达。

This is what distinguishes it from the OpenAI Agents SDK. Official durable execution page, verbatim:

Pydantic AI allows you to build durable agents that can preserve their progress across transient API failures and application errors or restarts ... Each engine wraps every model request and tool call as its own durable unit.

Engine list (README, verbatim): Temporal, DBOS, Prefect, Restate, AWS Lambda, Kitaru, Airflow, Absurd. The first five are "co-maintained with the vendor teams". Third parties can also use the backend builder to plug in their own engine.

⚠ The boundary that must be read out loud: the official docs dedicate one line —

Durability is not storage. A durable engine keeps one run alive across crashes and restarts. It does not store your chat threads: saving a conversation and picking it up later is a different problem ... laid out in Persistence.

i.e. the durable run and conversation-thread persistence are two things — precisely an isomorphic expression of our "state ≠ context".

MCP：两个方向都支持，且默认本地运行以控制凭据MCP: both directions supported, local by default to control credentials

官方 mcp/overview 页写了两个方向：

① agent 连 MCP server，用它的工具
② agent 被放进 MCP server

推荐做法是 MCP capability。官方称：

It runs the MCP server locally by default — keeping credentials, hooks, and tracing under your control — and lets you opt into the model provider's native MCP support with a single native=True flag.

低层可用 MCPToolset（toolsets=[...]）。 「默认本地」这点对凭据可控性很有价值。与「把凭据交给 provider 原生 MCP」相比，这是一个可选取舍。

The official mcp/overview page describes two directions:

① the agent connects to an MCP server and uses its tools
② the agent is placed inside an MCP server

The recommended approach is the MCP capability. Officially:

It runs the MCP server locally by default — keeping credentials, hooks, and tracing under your control — and lets you opt into the model provider's native MCP support with a single native=True flag.

Low-level: MCPToolset (toolsets=[...]). "Local by default" is valuable for credential control. Versus "handing credentials to the provider's native MCP", this is an optional trade-off.

A2A：官方已开始退场，注意时点A2A: officially being retired — mind the version timing

这一条要写清，否则会误判为长期内建能力。官方 integrations/a2a 页大标题就是：

Deprecated in 1.x, removed in 2.0

Agent.to_a2a() 与 pydantic-ai-slim[a2a] 已弃用，2.0 移除。
fasta2a 现由 datalayer/fasta2a 维护。自 v0.6.1 起附带 Pydantic AI bridge（agent_to_a2a）。

所以「Pydantic AI 支持 A2A」这句话，要补上版本时点才准确。

This must be written clearly, or it will be misjudged as a long-term built-in capability. The official integrations/a2a page headline reads:

Deprecated in 1.x, removed in 2.0

Agent.to_a2a() and pydantic-ai-slim[a2a] are deprecated, removed in 2.0.
fasta2a is now maintained by datalayer/fasta2a. Since v0.6.1 it ships a Pydantic AI bridge (agent_to_a2a).

So the sentence "Pydantic AI supports A2A" needs a version timestamp to be accurate.

Harness 与 Graph 是两个独立上层Harness and Graph are two independent upper layers

Pydantic AI Harness：官方称把 memory、guardrails、sub-agents、planning、 context management（compaction）、persistence 打包成 capabilities，并附现成的 Coder / Researcher 完整 agent。

官方也强调 Coder 不是黑盒。官方原文："use it whole, or use the blocks it bundles directly; the two are equivalent"。

pydantic-graph：官方 graphs 页称它可独立于 pydantic-ai 使用 —— "it has no dependency on pydantic-ai and can be considered as a pure graph-based state machine library"。官方还幽默地提醒：图是 nail gun，不是所有任务的正确工具。

结论：这两块都是从核心库上长出来的可选层，这也是本站仍按 coding-base 归档的理由。

Pydantic AI Harness: officially packages memory, guardrails, sub-agents, planning, context management (compaction), and persistence into capabilities, and ships ready-made Coder / Researcher complete agents.

The official docs also stress Coder is not a black box. Official wording: "use it whole, or use the blocks it bundles directly; the two are equivalent".

pydantic-graph: the official graphs page says it can be used independently of pydantic-ai — "it has no dependency on pydantic-ai and can be considered as a pure graph-based state machine library". The official docs also humorously note: a graph is a nail gun, not the right tool for every job.

Conclusion: both are optional layers grown off the core library — which is why we still file this under coding-base.

核验说明Verification notes

confidence: partial 的依据：

为什么仍是 partial：八维已从官方页核到结论。但仍有若干处官方确实没写、只能记「官方未说明」的项：

核心 SDK 不经 Harness 时的文件访问默认边界
核心 SDK 是否有进程/网络级沙箱与内置权限边界
compaction 的默认裁剪策略
Gateway 的加价费率
八种 durable 引擎之间的功能对齐度

这些不是「没查到」，是官方文档本身未给，故不足以升到 verified。

已核到的官方页：

仓库 README（定位、model-agnostic 清单、durable 八引擎、Harness、Coder 示例）
docs/ai/overview（Why use 十二条 + bank support 示例）
docs/ai/models/overview（provider 目录表、ModelProfile、fallback）
docs/ai/capabilities/durable_execution/overview
docs/ai/graph/graph
docs/ai/evals/evals
docs/ai/mcp/overview
docs/ai/core-concepts/dependencies
docs/ai/guides/multi-agent-applications
docs/ai/integrations/a2a
官方定价页 pydantic.dev/pricing
releases（v2.54.0 @ 2026-10-02）

核验方法：WebFetch 打开各官方页与 GitHub API（仓库元数据、releases）。

Basis for confidence: partial:

Why still partial: all eight axes are verified to conclusions from official pages. But several items remain that the official docs genuinely don't state, recordable only as "not stated officially":

the default file-access boundary of the core SDK without Harness
whether the core SDK has process/network-level sandboxing and built-in permission boundaries
the default trimming strategy of compaction
the Gateway's markup rates
the feature alignment across the eight durable engines

These are not "couldn't find it" — the official docs themselves don't give them, so it cannot rise to verified.

Official pages checked the 2026-10-08 check:

Repo README (positioning, model-agnostic list, eight durable engines, Harness, Coder example)
docs/ai/overview (twelve "Why use" items + bank support example)
docs/ai/models/overview (provider catalog table, ModelProfile, fallback)
docs/ai/capabilities/durable_execution/overview
docs/ai/graph/graph
docs/ai/evals/evals
docs/ai/mcp/overview
docs/ai/core-concepts/dependencies
docs/ai/guides/multi-agent-applications
docs/ai/integrations/a2a
the official pricing page pydantic.dev/pricing
releases (v2.54.0 @ 2026-10-02)

Verification method: WebFetch on each official page plus the GitHub API (repo metadata, releases).