← Harness

Pydantic AIPydantic AI

Pydantic

Python 开源 MIT 编程底座通用harness 类型安全 MCP A2A durable-execution 持久化状态管理图执行子代理多Agent eval HITL human-in-the-loop 沙箱集成生态 partial lifecycle: active 核验Checked 2026-10-08

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 可移植，但各家行为一致性需实测。

运行位置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 入口。两者都建立在同一个库之上。

本地文件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 页已查。

关机后的任务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。

工具与扩展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。

上下文与记忆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 页已查。

权限与限制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 那侧承担。

适合什么任务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

头号误解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 的计费细节（官方定价页未单列；费率按 D9 口径本站不采）
八种 durable 引擎之间的功能对齐度（官方未说明）
不同 provider 之间行为完全等价性（官方已声明「取决于所选模型与 API」）
A2A 移除后官方在 2.0 的替代路线（官方指向 datalayer/fasta2a）

证据来源Evidence sources

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

类型Type	名称Name	链接Link
repo	pydantic/pydantic-ai · 仓库（12,978★，MIT，Python，核验 2026-10-08）	https://github.com/pydantic/pydantic-ai
docs	主 README（"Python AI SDK / typed agent loop"、model-agnostic 清单、durable execution 八引擎、Harness、Coder）	https://github.com/pydantic/pydantic-ai
docs	官方文档 · Overview（Why use Pydantic AI 十二条、类型安全、MCP/A2A、HITL、durable execution）	https://pydantic.dev/docs/ai/overview/
docs	官方文档 · Durable Execution（八引擎、每个模型/工具调用为 durable 单元、"Durability is not storage"）	https://pydantic.dev/docs/ai/capabilities/durable_execution/overview/
docs	官方文档 · Graphs（pydantic-graph，可独立于 pydantic-ai 使用；类型化状态机）	https://pydantic.dev/docs/ai/graph/graph/
docs	官方文档 · Pydantic Evals（code-first 评估、datasets/cases/evaluators、trajectory 评估）	https://pydantic.dev/docs/ai/evals/evals/
docs	官方文档 · MCP（连 MCP server、被暴露为 MCP server、MCP capability 默认本地运行、native=True）	https://pydantic.dev/docs/ai/mcp/overview/
docs	官方文档 · Dependencies（类型安全依赖注入、RunContext、可覆盖以便测试）	https://pydantic.dev/docs/ai/core-concepts/dependencies/
docs	官方文档 · Multi-agent Applications（五个复杂度层级：单 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）	https://pydantic.dev/docs/ai/integrations/a2a/
pricing	官方定价页（核验 2026-10-08：Pydantic 库永久 MIT 免费；Logfire 免费档含 1,000 万 spans/月、另有 Pro 档；报价按 D9 口径不存）	https://pydantic.dev/pricing/
changelog	Releases（v2.54.0 @ 2026-10-02）	https://github.com/pydantic/pydantic-ai/releases

实测记录Measured runs

本站尚未完成实测。测试协议见 tasks/_protocol.md。

实测建议（按编程底座 + 类型安全 / 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` 的凭据与行为差异	官方强调默认本地保凭据可控，值得验证

与 OpenAI Agents SDK 的对照：本站最该给读者看的一张表

两者都是「给你 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。

model-agnostic：provider 目录是官方的第一卖点

官方 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."

durable execution：官方八引擎，且「每个模型与工具调用都成为 durable 单元」

这是它区别于 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 与对话线程持久化是两件事，正是本站「状态 ≠ 上下文」的同构表达。

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 — and lets you opt into the model provider's native MCP support with a single native=True flag.

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

A2A：官方已开始退场，注意时点

这一条要写清，否则会误判为长期内建能力。官方 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」这句话，要补上版本时点才准确。

Harness 与 Graph 是两个独立上层

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 归档的理由。

核验说明

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）。