Source: Pydantic AI documentation
Official Pydantic AI docs: the typed Agent, dependency injection via RunContext, output modes, tools, usage limits, capabilities, durable execution, testing and the V2 changelog.
Contents
- What: official documentation for Pydantic AI (pages: Agents, Dependencies, Output, Function Tools, Models and Providers, Capabilities, Durable Execution, Unit testing, Upgrade guide/changelog)
- Publisher: Pydantic (the team behind the Pydantic validation library and Logfire)
- Date: living docs, read 2026-11-14; latest release v2.68.0 (2026-11-12)
- Original: pydantic.dev/docs/ai (formerly ai.pydantic.dev; source in pydantic/pydantic-ai/docs)
Summary
Pydantic AI is a Python agent framework built around one class, Agent, generic in its dependency type and output type (Agent[Deps, Output]), so type checkers catch mismatches. An agent bundles instructions, tools/toolsets, an output type, a deps type, a default model and settings, and “capabilities” (reusable bundles of tools, hooks, instructions and settings). It is model-agnostic: "<provider>:<model>" strings select OpenAI, Anthropic, Gemini, Bedrock, Vertex, Azure and many others.
Key claims
- Five ways to run:
run()(async),run_sync(),run_stream(),run_stream_events(), anditer(), which iterates the nodes of the underlying graph step by step. - Dependency injection: any Python type (usually a dataclass) passed as
deps=at run time and reached by tools, dynamic instructions and output validators throughRunContext[Deps];Agent.overrideswaps deps, model or toolsets in tests. - Tools:
@agent.tool(getsRunContext) and@agent.tool_plain; parameter schema comes from the signature, and descriptions from the docstring (Google, NumPy, Sphinx styles parsed via griffe).ModelRetryraised in a tool sends the error back to the model to try again. - Output:
output_typeaccepts scalars, TypedDicts, dataclasses, Pydantic models, unions, and output functions. Default Tool Output mode exposes each output type as a separate output tool; NativeOutput uses the provider’s JSON-schema response format (not all models; with restrictions); PromptedOutput puts the schema in instructions and validates, the least reliable but universal mode. Validation failures are sent back to the model to retry. @agent.output_validatorhandles async/IO validation; eachModelRetryconsumes the output retry budget, which defaults to 1 (retries={'output': N}).UsageLimitsbound runs:request_limit(model turns),tool_calls_limit(checked before executing, so an over-limit parallel batch runs none), token limits. Exceeding raisesUsageLimitExceededrather than returning output.- With
run_stream()/run_stream_sync(), the first output matching the output type is final: if the model returns text plus tool calls and output type isstr, those “dangling” tool calls are not executed unlessend_strategyis'graceful'or'exhaustive', and even then their results are not sent back to the model. - Capabilities are “the primary extension point” (memory, guardrails, cost tracking, approvals); a separate Harness package ships prebuilt ones and complete
CoderandResearcheragents. - Durable execution through nine engines (Temporal, DBOS, Prefect, Restate, AWS Lambda, Absurd, pgtask, Azure Durable Task, Airflow), which journal model and tool calls and replay completed ones after a crash. The docs separate this from persistence (saving and resuming runs), which needs no engine.
- Testing:
TestModel/FunctionModelreplace real LLMs;ALLOW_MODEL_REQUESTS=Falseblocks accidental real calls. - v2.60.0 (2026-10-22 per the changelog) deprecated
RetryPromptPartand stopped emitting it, soisinstance(part, RetryPromptPart)silently matches nothing; useis_retry(part). - Versions: V1 shipped September 2025 with an API-stability promise; V2.0.0 stable on 2026-06-23 (forked from v1.107.0); deprecations in V2 keep working until V3.