Pydantic AI
Pydantic · Python
Type-first agent framework that treats durability and OpenTelemetry as architecture, not integrations.
Assessed at pydantic/pydantic-ai@679756763a · reviewed 18 Aug 2026 · rubric v1.0.0 · reviewer Fizz
architecture score
Assessment
Six axes, each 0–4, weighted to 100. Every basis line below is backed by citations pinned to the reviewed commit.
Control flow & multi-agent composition
3/4 · weight 20%
The default shape is a single typed agent loop with toolsets, and multi-agent work is documented as agent delegation. A separate graph library is available and documented for explicitly authored state machines. Held at 3: composition is documented and exercised, but the graph layer is an adjacent library rather than the default execution model, so most runs are a loop rather than an inspectable topology.
State, memory & durability
4/4 · weight 20%
Durability is delegated to real workflow engines rather than reimplemented: Temporal, DBOS and Prefect each attach as a durability capability on an Agent. Each integration has its own test module, so resumption is evidenced against actual engines rather than claimed. This is the strongest durability story of the frameworks reviewed here because the recovery guarantees are the host engine's, not the framework's own best effort.
Tools, integrations & interoperability
4/4 · weight 15%
Toolsets are a real abstraction, not a list of callables: there are combined, deferred-loading, dynamic and approval-required toolsets behind an abstract base, plus MCP support. Tool availability becomes a composable, swappable policy — including a toolset whose entire purpose is to gate execution on approval, which is an enforcement boundary rather than a convenience.
Reliability, safety & human controls
4/4 · weight 15%
The retry documentation is unusually honest: it names five distinct retry layers that do not share budgets and maps each to its configuration point, which is the actual cause of runaway retries in production. Beyond docs, the codebase carries explicit SSRF protection and a cancellation module, and approval-required toolsets gate tool execution.
Observability & evaluation
4/4 · weight 15%
Instrumentation imports OpenTelemetry directly and follows the GenAI semantic conventions, including the standard token-usage metric. That means traces land in any OTel backend without an adapter, and the vendor's own Logfire is one consumer rather than the only path. Vendor-neutral by construction, not by plugin.
Developer experience, portability & maintainability
4/4 · weight 15%
Documentation is extensive and lives in-repo so it pins to the reviewed revision, there is a runnable examples package, and a migration guide is maintained. The decisive evidence is a docs-parity test: the repository enforces in CI that documented behaviour matches the code, which is a maintainability guarantee most projects only aspire to.
Strengths
Durability is delegated to Temporal, DBOS or Prefect instead of reinvented, so recovery guarantees are a mature workflow engine's rather than the framework's own best effort.
Tracing is OpenTelemetry by construction and follows the GenAI semantic conventions, so it works with an existing observability stack without an adapter or a vendor account.
A docs-parity test means the documentation is enforced against the code in CI — documented behaviour cannot silently drift.
The retry documentation names five separate retry layers and states they do not share budgets, which is unusually candid about the most common production failure mode.
Limitations
The default execution model is a typed agent loop; an explicitly authored topology requires the adjacent graph library, so control flow is less inspectable out of the box than a graph-first framework.
The strongest durability guarantees require adopting an external workflow engine — that is the right engineering call, but it is real operational weight, not a library import.
Best for
Teams that already run OpenTelemetry and want agent traces in their existing backend without adopting a vendor's observability product.
Workloads that must survive process restarts with real guarantees, where adopting Temporal, DBOS or Prefect is acceptable.
Codebases where static types are load-bearing and tool contracts should be checked rather than described.
Avoid if
You want an authored, diffable graph as the primary execution model — that lives in a separate library here rather than in the default path.
You cannot take on an external workflow engine, in which case the headline durability advantage does not apply to you.
Patterns worth stealing
Delegate durability to a workflow engine instead of reimplementing checkpoints. Attaching a durability capability to an existing object is a far smaller surface to get right than owning persistence yourself.
Make tool availability a composable toolset rather than a flat registry — approval gates, lazy loading and dynamic scoping then compose instead of being special-cased per tool.
Test your documentation against your code. A docs-parity check turns the README from marketing into a contract.
Enumerate your retry layers explicitly and state that their budgets are independent. Most runaway-cost incidents are two retry layers multiplying unnoticed.
Evidence ledger
All 20 citations behind this assessment. Each was fetched at the reviewed commit and checked for the exact text it claims.
- official-docnativedocumented
Multi-agent work is documented as agents delegating to other agents rather than as an authored topology by default.
docs/multi-agent-applications.md
pinned 679756763ab8 · blob 8010aa4c8d123 · observed 18 Aug 2026
- official-docofficial-addondocumented
A separate graph library provides explicitly authored state machines for cases where a loop is not enough.
pinned 679756763ab8 · blob 98040e4c9c67d · observed 18 Aug 2026
- examplenativedemonstrated
An official runnable example demonstrates one agent delegating to another, confirming the documented composition path executes.
examples/pydantic_ai_examples/medical_agent_delegation.py
pinned 679756763ab8 · blob fa8f382695a51 · observed 18 Aug 2026
- official-docnativedocumented
Durable execution has its own documentation section covering multiple platform integrations.
docs/durable_execution/overview.md
pinned 679756763ab8 · blob 7d846adfbd0c1 · observed 18 Aug 2026
- sourcenativeobserved
Temporal, DBOS and Prefect each expose a durability capability attached to an Agent, so recovery semantics are the host engine's rather than reimplemented in the framework.
pydantic_ai_slim/pydantic_ai/durable_exec/__init__.py — module docstring
pinned 679756763ab8 · blob d08a566eb2533 · observed 18 Aug 2026
- testnativedemonstrated
A dedicated Temporal test module exercises the durability integration, evidencing resumption against a real workflow engine rather than a claim.
pinned 679756763ab8 · blob 8780d6a6f4280 · observed 18 Aug 2026
- official-docnativedocumented
Toolsets are documented as the unit by which tool availability is composed and swapped.
pinned 679756763ab8 · blob cd10aeaf5656e · observed 18 Aug 2026
- sourcenativeobserved
An abstract toolset base allows combined, dynamic and deferred-loading implementations, making tool exposure a policy rather than a fixed list.
pydantic_ai_slim/pydantic_ai/toolsets/abstract.py — AbstractToolset
pinned 679756763ab8 · blob d4e9bfb5cfe48 · observed 18 Aug 2026
- sourcenativeobserved
Approval is implemented as a toolset wrapper, so a human gate composes with any tool source instead of being special-cased per tool.
pydantic_ai_slim/pydantic_ai/toolsets/approval_required.py
pinned 679756763ab8 · blob 7c5644822828c · observed 18 Aug 2026
- official-docnativedocumented
The docs name five separate retry layers and map each to its configuration point, addressing the usual cause of runs that retry far more or far less than expected.
pinned 679756763ab8 · blob 2e670a8517542 · observed 18 Aug 2026
- sourcenativeobserved
A dedicated SSRF module guards outbound request targets — a concrete secret/network boundary control most agent frameworks leave to the user.
pydantic_ai_slim/pydantic_ai/_ssrf.py
pinned 679756763ab8 · blob b8f0e6a3fafea · observed 18 Aug 2026
- sourcenativeobserved
Because approval is a toolset, the gate cannot be bypassed by a tool that forgot to implement it — enforcement lives at the composition point.
pydantic_ai_slim/pydantic_ai/toolsets/approval_required.py
pinned 679756763ab8 · blob 7c5644822828c · observed 18 Aug 2026
- official-docnativedocumented
Documentation describes instrumentation in terms of OpenTelemetry, with the vendor's Logfire as one consumer of those traces.
pinned 679756763ab8 · blob 63878e9e73191 · observed 18 Aug 2026
- sourcenativeobserved
Instrumentation imports OpenTelemetry directly and references the GenAI semantic-convention metrics, so traces land in any OTel backend with no adapter.
pydantic_ai_slim/pydantic_ai/_instrumentation.py
pinned 679756763ab8 · blob fb81b65ad0c4f · observed 18 Aug 2026
- official-docnativedocumented
Installation is documented in-repo, so the getting-started path pins to the reviewed revision rather than a floating site.
pinned 679756763ab8 · blob a44c986c28411 · observed 18 Aug 2026
- testnativedemonstrated
A docs-parity test runs in the suite, so documented behaviour drifting from the implementation fails CI — a maintainability guarantee, not an aspiration.
pinned 679756763ab8 · blob f51e0bebec556 · observed 18 Aug 2026
- examplenativedemonstrated
The examples package contains runnable end-to-end agents covering support, RAG and chat use cases.
examples/pydantic_ai_examples/bank_support.py
pinned 679756763ab8 · blob 72a50fbe8d1a3 · observed 18 Aug 2026
- testnativedemonstrated
A dedicated toolsets test module exercises composition and filtering, evidencing that toolsets behave as a real abstraction rather than a naming convention.
pinned 679756763ab8 · blob 7adcfc6907a25 · observed 18 Aug 2026
- testnativedemonstrated
Cancellation of an in-flight run has its own test module, evidencing an interruption path that is exercised rather than assumed.
tests/test_run_cancellation.py
pinned 679756763ab8 · blob cae4860bf8910 · observed 18 Aug 2026
- testnativedemonstrated
An OpenTelemetry test module asserts emitted spans, so the instrumentation contract is verified rather than merely imported.
pinned 679756763ab8 · blob 92e30e0d50d10 · observed 18 Aug 2026