PydanticAI

The Pydantic way for Generative AI. Type-safe agents with validated inputs/outputs, FastAPI-inspired dependency injection, and — new in 2025 — durable execution, graph-based workflows, and a first-class evals framework.

Install

pip install pydantic-ai

Version

v1.107.0 · June 2026 · Python 3.10+

Best for

Typed APIs, structured output, validated data pipelines, evals-driven agents.

Zero → Hero

1 · Philosophy & core concepts Why type safety, design principles · 10 min

2 · Installation & setup Install, first agent, LLM config · 15 min

3 · Core fundamentals Agent, Model, RunContext, tools · 20 min

4 · Your first agent Query/response, streaming, async · 20 min

5 · Type safety & validation Pydantic models for everything · 15 min

6 · Output types & validators ToolOutput/NativeOutput/PromptedOutput/TextOutput/StructuredDict · 15 min

7 · Tools & function calling @agent.tool decorator, validation · 20 min

8 · Toolsets FunctionToolset, Prefixed, Filtered, Approval, Deferred · 15 min

9 · Built-in tools WebSearch, WebFetch, CodeExec, Image, FileSearch · 10 min

10 · Dependency injection FastAPI-style deps, testing, mocking · 15 min

11 · Model providers & fallback Every provider prefix, FallbackModel, gateway · 20 min

12 · Message history & multi-turn ModelMessagesTypeAdapter, HistoryProcessor · 15 min

13 · Streaming run_stream, AgentStream, iter, events · 20 min

14 · Testing TestModel, FunctionModel, override, capture · 20 min

15 · Graph support Typed state graphs · 25 min

16 · Durable execution Checkpointing, resume, Temporal-style · 25 min

17 · Evals LLM-as-judge, regression testing · 20 min

18 · Production Deployment, observability, cost · 30 min

19 · Class deep dives AgentRun.iter, AgentRunResult, ConcurrencyLimiter, Direct API, Tool advanced params, ModelSettings, Hooks, Thinking, WebSearch · 35 min

20 · Advanced class deep dives (Part 2) AgentSpec, SkipModelRequest/SkipToolExecution/SkipToolValidation, ProcessEventStream, HandleDeferredToolCalls, PreparedToolset, DeferredLoadingToolset, InstructionPart, IncludeToolReturnSchemas · 30 min

21 · Source code deep dive — 10 classes RunContext (all fields), Hooks (all 33 events), WebSearch, WebFetch, Thinking, FilteredToolset, CombinedToolset, ApprovalRequiredToolset, ExternalToolset, UsageLimits/RunUsage · 40 min

22 · Class deep dives Vol. 2 — 10 more classes FallbackModel, ModelProfile, WrapperToolset family, InstrumentationSettings, UploadedFile, TemplateStr, ProcessHistory/ReinjectSystemPrompt, AbstractCapability, EndStrategy/AgentRetries, ModelRequestContext · 40 min

23 · Class deep dives Vol. 3 — 10 classes MCPToolset, UIAdapter/MessagesBuilder, CachePoint/CompactionPart, format_as_xml, BinaryContent/FileUrl family, DeferredToolRequests/DeferredToolResults/CallDeferred, NativeTool, NativeOrLocalTool, DynamicCapability, ToolSearch · 45 min

24 · Class deep dives Vol. 4 — 10 classes LangChainToolset, VercelAIAdapter, ToolManager/ValidatedToolCall, ThreadExecutor, PrefixTools, PrepareTools/PrepareOutputTools, ImageGeneration, XSearch, common_tools (DuckDuckGo/Tavily/Exa), FunctionSignature/TypeSignature · 45 min

25 · Class deep dives Vol. 5 — 10 classes PendingMessage/RunContext.enqueue, AgentWorker/agent_to_a2a, WrapperAgent, safe_download/SSRF protection, DBOSAgent, StreamedResponseSync, ModelResponsePartsManager, CombinedCapability, FastMCPToolset (migration), SetToolMetadata · 45 min

26 · Class deep dives Vol. 6 — 10 classes ToolReturn (structured return + metadata), TextContent (app-only tagged text), FilePart/BinaryImage (model file responses), Direct API (model_request family), ModelRequestParameters (wire format), error hierarchy (ModelHTTPError/ContentFilterError/IncompleteToolCall), ToolApproved/ToolDenied (HITL results), JsonSchemaTransformer (custom schema walk), TemporalAgent (durable execution), ToolsetTool (toolset execution wrapper) · 45 min

27 · Class deep dives Vol. 7 — 10 classes AgentEventStream/AgentRunResultEvent (event streaming + PartStartEvent/PartDeltaEvent), ThinkingPart/ThinkingPartDelta (extended thinking + provider signatures), AudioUrl/VideoUrl/DocumentUrl (multimodal URLs), OutputContext (output hook context), ModelRetry (retry mechanics + Pydantic serialisation), RequestUsage (per-request token tracking), WebSearchTool/WebSearchUserLocation (localized web search), MemoryTool (native memory), CodeExecutionTool (native code execution), AbstractNativeTool (custom native tool base) · 45 min

28 · Class deep dives Vol. 8 — 10 classes ToolOutput/NativeOutput/PromptedOutput/TextOutput/StructuredDict (output-mode toolkit), ApprovalRequiredToolset (HITL guard), DeferredLoadingToolset (lazy discovery), Embedder/EmbeddingModel/EmbeddingResult/EmbeddingSettings (vector embeddings), web_fetch_tool/WebFetchLocalTool (SSRF-safe web fetching), PrefectAgent/TaskConfig (durable Prefect integration), ImageGenerationSubagentTool (subagent image gen), ConcurrencyLimitedModel/AbstractConcurrencyLimiter (model-level rate limiting), InstructionPart/AgentInstructions (instructions architecture) · 45 min

29 · Class deep dives Vol. 9 — 10 classes ModelRequest/ModelResponse (wire-format anatomy + FinishReason/ModelResponseState), SystemPromptPart/UserPromptPart/RetryPromptPart (request-side parts), BaseToolCallPart/ToolCallPart/NativeToolCallPart (call-part family + narrow_type), BaseToolReturnPart/ToolReturnPart/NativeToolReturnPart (return-part family + outcome), GraphAgentState (run-state internals), MCPServerTool (native MCP integration), FileSearchTool (native RAG), IncludeReturnSchemasToolset (auto return-schema), ToolChoice/ToolOrOutput (tool selection control), ServiceTier/ThinkingLevel/ThinkingEffort (cross-provider config) · 45 min

30 · Class deep dives Vol. 10 — 10 classes AgentStream (full streaming API — stream_output/stream_response/stream_text/cancel/drain/validate_response_output), WrapperCapability (capability middleware with full delegation), FunctionToolset (complete toolset — all 14 params, instructions, timeout, defer_loading, id), AbstractToolset (custom toolset ABC — for_run/for_run_step/get_instructions/get_tools/call_tool), ToolCallEvent/ToolResultEvent/FunctionToolCallEvent/FunctionToolResultEvent/OutputToolCallEvent/OutputToolResultEvent (tool event taxonomy), FinalResult/FinalResultEvent (output result markers), UserError/UsageLimitExceeded/ConcurrencyLimitExceeded/UndrainedPendingMessagesError/HookTimeoutError (remaining error types), multimodal type system (AudioMediaType/ImageMediaType/DocumentMediaType/VideoMediaType + ForceDownloadMode + ProviderDetailsDelta), AbstractCapability extended (defer_loading/get_description/get_ordering/wrap hooks/WrapRunHandler family), CapabilityOrdering/CapabilityPosition/CapabilityRef/CAPABILITY_TYPES (capability topology) · 50 min

31 · Class deep dives Vol. 11 — 10 class groups UserPromptNode/ModelRequestNode/CallToolsNode (three agent graph nodes now public API), AgentCapability/AgentToolset/ToolsetFunc (dynamic callable dispatch), AgentModelSettings/AgentNativeTool (per-run callable settings + native tools), HandleResponseEvent/ModelResponseStreamEvent (typed event discriminators), ToolSearchCallPart/NativeToolSearchCallPart/ToolSearchArgs/ToolSearchMatch (two-path tool search calls), ToolSearchReturnPart/NativeToolSearchReturnPart/ToolSearchReturnContent (tool search results), LoadCapabilityCallPart/LoadCapabilityReturnPart (capability lazy-load parts), BuiltinToolCallEvent/BuiltinToolResultEvent migration, AgentInstructions/AgentMetadata, Agent 1.106.0 constructor reference · 50 min

32 · Class deep dives Vol. 12 — 10 class groups Dataset + Case (pydantic_evals — YAML/JSON datasets, add_case/add_evaluator, repeat stability testing), Evaluator + EvaluatorContext + EvaluationResult + EvaluationReason (evaluator base framework, 6 patterns, versioned evaluators), built-in evaluators Equals/EqualsExpected/Contains/IsInstance/MaxDuration/HasMatchingSpan (all params, SpanQuery in HasMatchingSpan), LLMJudge + GradingOutput + 4 judge functions (score/assertion OutputConfig, include_input/include_expected_output, set_default_judge_model), generate_dataset (AI-assisted test generation, custom_evaluator_types, save/cache guard), online evaluation evaluate decorator + OnlineEvalConfig + OnlineEvaluator (sample_rate, sampling_mode independent/correlated, disable_evaluation, wait_for_evaluations, custom EvaluationSink), SpanTree + SpanNode + SpanQuery (all query fields, any/all/find/find_all, composite queries, increment_eval_metric/set_eval_attribute), MCPSamplingModel + MCPSamplingModelSettings (MCP server sampling, ModelPreferences, default_max_tokens, streaming limitation), RetryConfig + TenacityTransport + AsyncTenacityTransport + wait_retry_after (tenacity HTTP retry, Retry-After header parsing, attach to OpenAI provider), ExternalToolset (external/deferred tool execution, approval queue pattern, id for durable execution) · 55 min

33 · Class deep dives Vol. 13 — 10 class groups Capability (@cap.tool/@cap.tool_plain/@cap.instructions decorators, defer_loading=True, callable description, role-scoped caps, shared instance), MCP capability (native=True explicit, native-only, local-only with auth, deferred, migration from MCPToolset), WebSearch (search_context_size, WebSearchUserLocation, domain allow-list, force DuckDuckGo, custom async local), WebFetch (citations, intranet allow-list, force local, combined with WebSearch, custom proxy), XSearch (xAI native, fallback_model for non-xAI, date range, handle filter, image+video understanding), Instrumentation (Logfire, privacy mode, OTel v2, from_spec(), custom span attributes), HandleDeferredToolCalls (approve_all, selective by risk, two-handler chain, async webhook), ProcessEventStream (log observer, latency observer, ThinkingPart strip processor, audit injector, combined), WebFetchTool+XSearchTool+ImageGenerationTool (all fields, provider matrix table, deprecated UrlContextTool alias, NativeTool wrapping), ToolSearch (default strategy, keywords, custom callable, max_results tuning, combined with deferred Capability) · 55 min

34 · Class deep dives Vol. 14 — 10 class groups UIAdapter/UIEventStream/StateDeps/StateHandler/OnCompleteFunc (unified UI protocol base + security policy), AGUIAdapter (dispatch_request pattern + ag_ui_version version thresholds for REASONING_* events), VercelAIAdapter updated (sdk_version=6 HITL approval streaming, server_message_id), Provider ABC + infer_provider/infer_provider_class (custom provider authoring), ModelProfile complete (all 17 fields: supports_tool_return_schema/supports_json_schema_output/supports_thinking/thinking_always_enabled/thinking_tags/ignore_streamed_leading_whitespace/supported_native_tools), AnthropicModelProfile + OpenAIModelProfile (provider-specific profile extensions: adaptive thinking, effort, openai_chat_thinking_field, openai_chat_send_back_thinking_parts), WrapperEmbeddingModel + InstrumentedEmbeddingModel (custom embedding wrappers + OTel tracing), additional embedding providers (GoogleEmbeddingModel/BedrockEmbeddingModel/CohereEmbeddingModel/VoyageAIEmbeddingModel + comparison table), BuilderCheckpoint + MessagesBuilder advanced (snapshot/diff for custom UIEventStream), OutlinesModel deprecated (constrained generation + migration guide) · 55 min

35 · Class deep dives Vol. 15 — 10 class groups CombinedToolset (multi-toolset merging + name-conflict detection), HuggingFaceModel + HuggingFaceModelSettings + HuggingFaceStreamedResponse (open-source Hub inference — DeepSeek-R1/Llama-4/Qwen3), TestEmbeddingModel (deterministic mock embeddings for unit tests), SentenceTransformerEmbeddingModel + SentenceTransformersEmbeddingSettings (on-device privacy-preserving embeddings), TemporalRunContext + deserialize_run_context (serializable RunContext across Temporal activity boundaries), PydanticAIWorkflow (Temporal Workflow base class), TemporalDynamicToolset (wraps DynamicToolset for Temporal activities), PrefectAgentInputs + DEFAULT_PYDANTIC_AI_CACHE_POLICY (Prefect cache policy for PydanticAI agents), ACIToolset + tool_from_aci (deprecated ACI.dev integration + migration guide), provider model-profile functions (GrokModelProfile/GroqModelProfile/deepseek_model_profile/qwen_model_profile/cohere_model_profile/moonshotai_model_profile) · 55 min

36 · Class deep dives Vol. 16 — 10 class groups AgentRunResult (all 6 methods: all_messages/new_messages/usage + output_tool_return_content multi-turn pattern), StreamedRunResult + StreamedRunResultSync (high-level streaming result wrappers — stream_output/stream_text/stream_response/get_output + sync CLI wrapper), Tool direct construction (all 17 params + from_schema/from_function/function_schema/prepare dynamic filtering), GenerateToolJsonSchema + DocstringFormat (schema generation pipeline — 4 docstring formats, require_parameter_descriptions, custom schema_generator), MistralModel + MistralModelSettings + MistralStreamedResponse (Mistral AI provider — json_mode_schema_prompt, PromptedOutput fallback, multimodal Pixtral), OllamaModel (self-hosted vs Cloud NativeOutput behaviour — supports_json_schema_output auto-disable, Cloud detection heuristics, ToolOutput fallback), OpenRouterModel + OpenRouterModelSettings + OpenRouterModelProfile + OpenRouterReasoning (meta-provider — fallback chain, provider routing, cache-control flags, cross-provider reasoning tokens), NamedSpec + CapabilitySpec + build_registry + load_from_registry (YAML/JSON spec-driven capability composition — short-form serialisation, custom registries, legacy alias handling), OutputSchema + OutputValidator (output validation machinery — OutputSchema.build() factory, 5 concrete subclasses, OutputValidator sync/async dispatch), GraphRun + NodeStep (v2 graph execution primitives — GraphRun state manager, fork/join coordination, NodeStep bridging v1 BaseNode into v2) · 55 min

37 · Class deep dives Vol. 17 — 10 class groups LiteLLMProvider (universal proxy routing + automatic model profiles for 12 provider families), AzureProvider (Azure AI Foundry Express Mode + ADC + api_version suppression for /v1 endpoints), DeepSeekProvider (reasoning_content wire field + send_back_thinking_parts + tool_choice restriction for reasoning models), CerebrasProvider (ultra-fast inference + zai/gpt-oss reasoning + 6 disabled settings + X-Cerebras-3rd-Party-Integration header), GitHubProvider (provider/model:tag naming + 6 provider families + GITHUB_API_KEY), FireworksProvider + TogetherProvider + NebiusProvider + SambaNovaProvider (OpenAI-compatible GPU provider quartet — endpoint URLs + model naming conventions + on-prem SAMBANOVA_BASE_URL), GraphBuilder (pydantic_graph fluent builder — step/stream decorators + join/decision helpers + add/add_edge/add_mapping_edge wiring + build()), Fork + Join + ReducerContext (parallel fan-out/fan-in + cancel_sibling_tasks early stopping + preferred_parent_fork topology), Decision + DecisionBranch + Edge + TypeExpression (type-based conditional routing + custom matches predicate + Edge Mermaid labels + TypeExpression workaround), Step + StepContext + StepNode (step execution primitives — StepContext.state/deps/inputs + Step.as_node() + streaming steps) · 55 min

38 · Class deep dives Vol. 18 — 10 class groups AlibabaProvider (DashScope + DASHSCOPE_API_KEY + Qwen omni audio URI encoding), OVHcloudProvider (European AI Endpoints + prefix-based multi-family profile routing for 6 families), HerokuProvider (Heroku Inference API + HEROKU_INFERENCE_KEY/URL), gateway_provider (Pydantic AI Gateway — multi-upstream dispatch + route override + region-encoded key auto base-URL), GoogleProvider + GoogleCloudProvider (Gemini API vs Google Cloud/Vertex AI — GOOGLE_API_KEY vs ADC), GoogleModel + GoogleModelSettings (all 9 prefixed settings — google_cached_content caveat + google_safety_settings + MediaResolution + GoogleCloudServiceTier), CohereModel + CohereProvider + CohereModelSettings (Command-R family — CO_API_KEY + AsyncClientV2 + thinking content mapping), XaiProvider + XaiModel (gRPC SDK + _LazyAsyncClient per-loop affinity + GrokModelProfile/GrokReasoningEffort + builtin-tool gate), FileStatePersistence (atomic file-lock persistence for pydantic_graph — .pydantic-graph-persistence-lock + snapshot lifecycle), SimpleStatePersistence + FullStatePersistence (in-memory graph persistence — lightweight latest-only vs full history with dump_json/load_json) · 55 min

39 · Class deep dives Vol. 19 — 10 class groups BedrockConverseModel + BedrockModelSettings (AWS Bedrock — 9 settings, caching TTL, guardrails, finish-reason map), BedrockProvider + BedrockModelProfile + BedrockJsonSchemaTransformer + 8 profile functions (credential rotation, 10 profile fields, strict-mode schema rewrites), GoogleGLAProvider + GoogleVertexProvider deprecated (migration to GoogleProvider/GoogleCloudProvider — _VertexAIAuth token refresh, 29-region VertexAiRegion), DynamicToolset (per_run_step factory — role RBAC, one-time init, feature flags), CapabilityOwnedToolset + resolve_capability_id + tool_defs_for_loaded_capabilities (capability-toolset binding, deferred stamping, wire-side filter), Web UI API create_api_app (4 Starlette routes, camelCase JSON, model dedup), OTel GenAI spec message types (9 TypedDicts — UriPart/BlobPart v4 upgrade, ToolCallPartOtelMetadata), Thinking capability (single-field ThinkingLevel, portable cross-provider reasoning), ImageGeneration capability (12-field config matrix, fallback_model subagent, action=edit), pydantic_graph persistence primitives + exception hierarchy (NodeSnapshot/EndSnapshot anatomy, BaseStatePersistence ABC, SnapshotStatus lifecycle, GraphNodeStatusError.check) · 55 min

40 · Class deep dives Vol. 20 — 10 class groups Hooks capability (decorator-based hook registration — 25+ lifecycle hooks, tools= filter, timeout= per hook, HookTimeoutError), Instrumentation capability (OpenTelemetry/Logfire — position=outermost, per-run isolation, ToolRetryError/ApprovalRequired classification), ConcurrencyLimiter + AbstractConcurrencyLimiter + ConcurrencyLimit (anyio-backed — OTel span per wait, max_queued backpressure, ConcurrencyLimitExceeded, from_limit()), Toolset composition — CombinedToolset + PrefixedToolset + RenamedToolset + FilteredToolset + PreparedToolset (composable middleware — conflict detection, async filter, prepare_func constraint), ApprovalRequiredToolset + ExternalToolset (HITL approval — ctx.tool_call_approved flag, external result injection, DeferredToolset deprecated alias), TemplateStr (Handlebars instructions — {{ trigger, deps_type compile, Union[TemplateStr,str] fallthrough), FunctionSchema (function→LLM schema — takes_ctx auto-detect, single_arg_name, return_schema, async/sync transparent), safe_download + ResolvedUrl (SSRF protection — 14 IPv4 + 7 IPv6 private ranges, 7 cloud metadata IPs always blocked, IPv6 transition decoding, per-hop redirect validation), LoadCapabilityCallPart + LoadCapabilityReturnPart + parse_loaded_capabilities (deferred capability wire protocol — capability-load discriminator, capability_id property, parse_loaded_capabilities), ModelProfile + DEFAULT_PROFILE + ModelProfileSpec (model capability declaration — 14 fields, from_profile/update merge, lazy deprecated kwarg alias installation) · 55 min

41 · Class deep dives Vol. 21 — 10 class groups TestModel + TestStreamedResponse (deterministic test doubles — call_tools/seed/custom_output_text/custom_output_args + _JsonSchemaTestData generation), FunctionModel + AgentInfo (Python-function-driven model — sync/async function+stream_function overloads, auto-profile, AgentInfo.instructions), DeltaToolCall + DeltaThinkingPart + DeltaToolCalls/DeltaThinkingCalls/BuiltinToolCallsReturns (streaming delta type system for FunctionModel stream functions), FunctionStreamedResponse (PeekableAsyncStream guard, token estimation, provider_name=None), ImageGenerationTool 1.107.0 complete (12 fields — new input_fidelity/partial_images/Google sizes '512'/'1K'/'2K'/'4K'/aspect_ratio + ImageAspectRatio + ImageGenerationModelName), WebFetchTool 1.107.0 complete (new max_content_tokens/enable_citations + allowed/blocked domain filtering + deprecated UrlContextTool alias), MCPServerTool 1.107.0 complete (new headers dict + connector_id via URL prefix + unique_id/label properties), FileSearchTool multi-provider (OpenAI vector stores/Google Gemini Files API/xAI collections — NATIVE_TOOLS_REQUIRING_CONFIG), ToolSearchStrategy types (ToolSearchNativeStrategy bm25/regex, ToolSearchLocalStrategy keywords, ToolSearchFunc custom callable, ToolSearchStrategy union + provider matrix), ToolSearchTool framework-internal (strategy bm25/regex/custom dispatch, excluded from TestModel, NATIVE_TOOLS_REQUIRING_CONFIG) · 55 min

42 · Class deep dives Vol. 22 — 10 class groups RunContext (complete field reference — deps/model/usage/messages/tool_name/conversation_id/enqueue/last_attempt), UsageLimits + RequestUsage + RunUsage (token budgets, pre-request token counting, cost extraction), DeferredToolRequests + DeferredToolResults + CallDeferred (human-in-the-loop async tool execution), ApprovalRequired + ApprovalRequiredToolset + ToolApproved + ToolDenied (interactive tool approval), ConcurrencyLimiter + AbstractConcurrencyLimiter + ConcurrencyLimit (in-process and custom distributed rate limiting), SkipModelRequest + SkipToolExecution + SkipToolValidation (hook short-circuit exceptions), ModelRetry (retry signalling from tools and validators), TemplateStr + format_as_xml (Handlebars prompt templates and XML context injection), AgentSpec (YAML/JSON-driven agent configuration with from_file/to_file), UploadedFile + BinaryContent + FilePart (cross-provider multimodal file handling) · 50 min

43 · Class deep dives Vol. 23 — 10 class groups ReinjectSystemPrompt (system prompt survival across history reconstruction — replace_existing=True for untrusted sources, dynamic prompt re-evaluation, per-run capabilities= injection), ProcessHistory + HistoryProcessorFunc (history interception before model requests — truncation, PII redaction, context-aware async processor, message compaction), RenamedToolset + WrapperToolset (toolset name mapping + delegation base — custom middleware subclass, namespace collision resolution, partial rename), SetMetadataToolset (bulk metadata injection — provider cache control, OTel attributes, middleware stacking), ThreadExecutor + Agent.using_thread_executor() (bounded thread pool for production FastAPI servers — per-agent, global lifespan, per-run scoping), PendingMessage + from_content() + priority (deep enqueue mechanics — 'asap' vs 'when_idle', direct PendingMessage construction, AgentRun.enqueue()), SystemPromptRunner (internal sync/async function dispatch — _takes_ctx/_is_async detection, dynamic= re-evaluation every step, multiple prompts concatenated), UsageBase + RunUsage.incr()/__add__() (complete 8-field token accounting incl. audio tokens — opentelemetry_attributes(), cost estimation with cache, multi-run accumulation), JsonSchemaTransformer + InlineDefsJsonSchemaTransformer (provider schema walk — transform() override, is_strict_compatible flag, $defs/$ref inline expansion, recursive type handling), GraphTaskRequest + JoinItem + EndMarker (parallel graph execution internals — fork_stack coordination, join accumulation, EndMarker.value, custom graph persistence) · 55 min

44 · Class deep dives Vol. 24 — 10 class groups WrapperModel + CompletedStreamedResponse (model wrapper base class — delegate all Model interface methods, transparent __getattr__ proxy, CompletedStreamedResponse for durable-execution stream replay in Temporal/Prefect/DBOS, ConcurrencyLimitedModel as canonical subclass pattern), FallbackModel response-handler pattern (ResponseHandler auto-detected via first-param type hint, ExceptionHandler, FallbackOn mixed sequence, ResponseRejected in FallbackExceptionGroup, async response handlers), Vercel AI SDK wire types (request UI parts: TextUIPart/ReasoningUIPart/FileUIPart/ToolApprovalRequested/ToolApprovalResponded; response SSE chunks: TextStartChunk/ReasoningStartChunk/ToolInputStartChunk/ToolApprovalRequestChunk/FinishChunk + versioned encode(sdk_version)), DeferredCapabilityLoader (deferred catalog deliberate full-relisting every turn for prompt-cache prefix stability — DEFERRED_CAPABILITY_CATALOG_PREFIX, get_ordering outermost, DeferredCapabilityLoaderToolset), ToolsetTool + SchemaValidatorProt (execution contract — args_validator_func post-schema validation, ModelRetry on failure, SchemaValidatorProt pluggable validator Protocol), EnqueueContent + PendingMessagePriority + _build_enqueue_messages (coalescing algorithm — adjacent UserContent → single UserPromptPart, ModelMessage stays separate, result must end in ModelRequest, 'asap'/'when_idle' delivery semantics), AG-UI multimodal conversion (_URL_TYPE_MAP + _MEDIA_PREFIX_TO_CONTENT dispatch tables, media_url_to_multimodal/binary_to_multimodal/multimodal_input_to_content round-trip), AgentInstructions pipeline (normalize_instructions → prepare_instructions → normalize_toolset_instructions → resolve_instructions, TemplateStr callable branch, dynamic= InstructionPart from toolsets), RunContext advanced fields (validation_context pydantic context, partial_output streaming guard, tool_call_metadata HITL approval metadata, model_settings per-step merged settings, run_id + conversation_id observability, tool_manager programmatic dispatch), AbstractAgent + EventStreamHandler + EventStreamProcessor (ABC interface — all abstract properties, AgentRetries TypedDict per-category budgets, EventStreamHandler terminal sink, EventStreamProcessor pass-through transformer for ProcessEventStream, output_json_schema) · 55 min

Jump to a topic

Agent primitive

Output types

Tools (typed)

Toolsets

Built-in tools

Dependency injection

Model providers & fallback

Message history

Streaming

Testing

Graph support

Durable execution

Evals

Integrations 2025

Advanced patterns

Error handling & testing

Hooks (lifecycle callbacks)

Concurrency limiting

Embeddings

Streaming server

Class deep dives AgentRun, AgentRunResult, ConcurrencyLimiter, Direct API, Tool advanced, ModelSettings, Hooks, Thinking, WebSearch

Advanced class deep dives (Part 2) AgentSpec, SkipModelRequest, ProcessEventStream, HandleDeferredToolCalls, PreparedToolset, DeferredLoadingToolset, InstructionPart, IncludeToolReturnSchemas

Source code deep dive — 10 classes RunContext, Hooks, WebSearch, WebFetch, Thinking, FilteredToolset, CombinedToolset, ApprovalRequiredToolset, ExternalToolset, UsageLimits/RunUsage

Class deep dives Vol. 2 — 10 more classes FallbackModel, ModelProfile, WrapperToolset family, InstrumentationSettings, UploadedFile, TemplateStr, ProcessHistory/ReinjectSystemPrompt, AbstractCapability, EndStrategy/AgentRetries, ModelRequestContext

Class deep dives Vol. 3 — 10 classes MCPToolset, UIAdapter/MessagesBuilder, CachePoint/CompactionPart, format_as_xml, BinaryContent/FileUrl family, DeferredToolRequests/DeferredToolResults/CallDeferred, NativeTool, NativeOrLocalTool, DynamicCapability, ToolSearch

Class deep dives Vol. 4 — 10 classes LangChainToolset, VercelAIAdapter, ToolManager/ValidatedToolCall, ThreadExecutor, PrefixTools, PrepareTools/PrepareOutputTools, ImageGeneration, XSearch, common_tools (DuckDuckGo/Tavily/Exa), FunctionSignature/TypeSignature

Class deep dives Vol. 5 — 10 classes PendingMessage/RunContext.enqueue, AgentWorker/agent_to_a2a, WrapperAgent, safe_download/SSRF, DBOSAgent, StreamedResponseSync, ModelResponsePartsManager, CombinedCapability, FastMCPToolset (migration), SetToolMetadata

Class deep dives Vol. 6 — 10 classes ToolReturn, TextContent, FilePart/BinaryImage, Direct API, ModelRequestParameters, error hierarchy, ToolApproved/ToolDenied, JsonSchemaTransformer, TemporalAgent, ToolsetTool

Class deep dives Vol. 7 — 10 classes AgentEventStream, ThinkingPart/ThinkingPartDelta, AudioUrl/VideoUrl/DocumentUrl, OutputContext, ModelRetry, RequestUsage, WebSearchTool/WebSearchUserLocation, MemoryTool, CodeExecutionTool, AbstractNativeTool

Class deep dives Vol. 8 — 10 classes ToolOutput/NativeOutput/PromptedOutput/TextOutput/StructuredDict, ApprovalRequiredToolset, DeferredLoadingToolset, Embedder/EmbeddingModel/EmbeddingResult, web_fetch_tool/WebFetchLocalTool, PrefectAgent/TaskConfig, ImageGenerationSubagentTool, ConcurrencyLimitedModel/AbstractConcurrencyLimiter, InstructionPart/AgentInstructions, OutputObjectDefinition

Class deep dives Vol. 9 — 10 classes ModelRequest/ModelResponse, SystemPromptPart/UserPromptPart/RetryPromptPart, BaseToolCallPart/ToolCallPart/NativeToolCallPart, BaseToolReturnPart/ToolReturnPart/NativeToolReturnPart, GraphAgentState, MCPServerTool, FileSearchTool, IncludeReturnSchemasToolset, ToolChoice/ToolOrOutput, ServiceTier/ThinkingLevel/ThinkingEffort

Class deep dives Vol. 10 — 10 classes AgentStream, WrapperCapability, FunctionToolset, AbstractToolset, tool event taxonomy, FinalResult/FinalResultEvent, error types, multimodal type system, AbstractCapability extended, CapabilityOrdering/CAPABILITY_TYPES

Class deep dives Vol. 11 — 10 class groups UserPromptNode/ModelRequestNode/CallToolsNode, AgentCapability/AgentToolset/ToolsetFunc, AgentModelSettings/AgentNativeTool, HandleResponseEvent/ModelResponseStreamEvent, ToolSearch two-path infrastructure, LoadCapabilityCallPart/LoadCapabilityReturnPart, BuiltinTool deprecation migration, AgentInstructions/AgentMetadata, Agent 1.106.0 constructor reference

Class deep dives Vol. 12 — 10 class groups Dataset/Case (pydantic_evals), Evaluator/EvaluatorContext, built-in evaluators (Equals/EqualsExpected/Contains/IsInstance/MaxDuration/HasMatchingSpan), LLMJudge + judge functions, generate_dataset, online evaluation (evaluate decorator/OnlineEvalConfig/OnlineEvaluator), SpanTree/SpanNode/SpanQuery, MCPSamplingModel, RetryConfig/TenacityTransport/AsyncTenacityTransport/wait_retry_after, ExternalToolset

Class deep dives Vol. 13 — 10 class groups Capability, MCP capability, WebSearch, WebFetch, XSearch, Instrumentation, HandleDeferredToolCalls, ProcessEventStream, native tool dataclasses (WebFetchTool/XSearchTool/ImageGenerationTool), ToolSearch

Class deep dives Vol. 14 — 10 class groups UIAdapter + UIEventStream + StateDeps + StateHandler + OnCompleteFunc, AGUIAdapter, VercelAIAdapter updated, Provider ABC + infer_provider, ModelProfile complete field reference, AnthropicModelProfile + OpenAIModelProfile, WrapperEmbeddingModel + InstrumentedEmbeddingModel, additional embedding providers, BuilderCheckpoint + MessagesBuilder advanced, OutlinesModel deprecated

Class deep dives Vol. 15 — 10 class groups CombinedToolset, HuggingFaceModel + HuggingFaceModelSettings, TestEmbeddingModel, SentenceTransformerEmbeddingModel, TemporalRunContext + deserialize_run_context, PydanticAIWorkflow, TemporalDynamicToolset, PrefectAgentInputs, ACIToolset + tool_from_aci deprecated, provider model-profile functions

Class deep dives Vol. 16 — 10 class groups AgentRunResult, StreamedRunResult + StreamedRunResultSync, Tool direct construction, GenerateToolJsonSchema + DocstringFormat, MistralModel + MistralModelSettings, OllamaModel, OpenRouterModel + OpenRouterModelSettings, NamedSpec + CapabilitySpec + build_registry, OutputSchema + OutputValidator, GraphRun + NodeStep

Class deep dives Vol. 17 — 10 class groups LiteLLMProvider, AzureProvider, DeepSeekProvider, CerebrasProvider, GitHubProvider, FireworksProvider + TogetherProvider + NebiusProvider + SambaNovaProvider, GraphBuilder, Fork + Join + ReducerContext, Decision + DecisionBranch + Edge + TypeExpression, Step + StepContext + StepNode

Class deep dives Vol. 18 — 10 class groups AlibabaProvider, OVHcloudProvider, HerokuProvider, gateway_provider, GoogleProvider/GoogleCloudProvider, GoogleModel/GoogleModelSettings, CohereModel/CohereProvider, XaiProvider/XaiModel, FileStatePersistence, SimpleStatePersistence/FullStatePersistence

Class deep dives Vol. 19 — 10 class groups BedrockConverseModel/BedrockModelSettings, BedrockProvider/BedrockModelProfile/BedrockJsonSchemaTransformer, deprecated Google providers migration, DynamicToolset, CapabilityOwnedToolset, web UI API, OTel GenAI spec types, Thinking capability, ImageGeneration capability, pydantic_graph persistence + exceptions

Class deep dives Vol. 20 — 10 class groups Hooks capability, Instrumentation capability, ConcurrencyLimiter/AbstractConcurrencyLimiter/ConcurrencyLimit, CombinedToolset/PrefixedToolset/RenamedToolset/FilteredToolset/PreparedToolset, ApprovalRequiredToolset/ExternalToolset, TemplateStr, FunctionSchema, safe_download SSRF protection, LoadCapabilityCallPart/LoadCapabilityReturnPart, ModelProfile

Class deep dives Vol. 21 — 10 class groups TestModel + TestStreamedResponse, FunctionModel + AgentInfo, DeltaToolCall/DeltaThinkingPart streaming types, FunctionStreamedResponse, ImageGenerationTool/WebFetchTool/MCPServerTool 1.107.0 complete, FileSearchTool multi-provider, ToolSearchStrategy types, ToolSearchTool

Class deep dives Vol. 22 — 10 class groups RunContext complete field reference, UsageLimits/RequestUsage/RunUsage, DeferredToolRequests/DeferredToolResults/CallDeferred, ApprovalRequired/ApprovalRequiredToolset/ToolApproved/ToolDenied, ConcurrencyLimiter, SkipModelRequest/SkipToolExecution/SkipToolValidation, ModelRetry, TemplateStr/format_as_xml, AgentSpec, UploadedFile/BinaryContent/FilePart

Class deep dives Vol. 23 — 10 class groups ReinjectSystemPrompt, ProcessHistory, RenamedToolset + WrapperToolset, SetMetadataToolset, ThreadExecutor, PendingMessage + priority, SystemPromptRunner, UsageBase + RunUsage, JsonSchemaTransformer + InlineDefsJsonSchemaTransformer, GraphTaskRequest + JoinItem + EndMarker

Class deep dives Vol. 24 — 10 class groups WrapperModel + CompletedStreamedResponse, FallbackModel response-handler pattern, Vercel AI SDK wire types, DeferredCapabilityLoader, ToolsetTool + SchemaValidatorProt, EnqueueContent + PendingMessagePriority, AG-UI multimodal conversion, AgentInstructions pipeline, RunContext advanced fields, AbstractAgent + EventStreamHandler + EventStreamProcessor

Reference

Comprehensive guide Single-page technical reference.

Output types & validators ToolOutput / NativeOutput / PromptedOutput / TextOutput / StructuredDict.

Message history & multi-turn ModelMessagesTypeAdapter, HistoryProcessor, capture_run_messages.

Streaming run_stream, run_stream_events, iter, AgentStream.

Testing TestModel, FunctionModel, agent.override().

Model providers & fallback Every provider prefix, FallbackModel, gateway routing.

Toolsets FunctionToolset, Prefixed, Filtered, Approval, Deferred, External.

Built-in tools WebSearch, WebFetch, CodeExecution, ImageGeneration, FileSearch, MCPServer, XSearch.

Class deep dives AgentRun, AgentRunResult, ConcurrencyLimiter, Direct API, Tool advanced params, ModelSettings full ref, Hooks, Thinking, WebSearch.

Advanced class deep dives (Part 2) AgentSpec, SkipModelRequest/SkipToolExecution/SkipToolValidation, ProcessEventStream, HandleDeferredToolCalls, PreparedToolset, DeferredLoadingToolset, InstructionPart, IncludeToolReturnSchemas.

Source code deep dive — 10 classes RunContext (all fields), Hooks (all 33 events + constructor kwargs), WebSearch + WebFetch (native/local/domains), Thinking (effort levels), FilteredToolset (RBAC + async), CombinedToolset, ApprovalRequiredToolset (HITL), ExternalToolset (deferred), UsageLimits + RunUsage (token budgets). All verified against 1.102.0 source.

Class deep dives Vol. 2 — 10 more classes FallbackModel + FallbackExceptionGroup, ModelProfile + ModelProfileSpec + DEFAULT_PROFILE, WrapperToolset + RenamedToolset + PrefixedToolset + SetMetadataToolset, InstrumentationSettings + InstrumentedModel, UploadedFile, TemplateStr, ProcessHistory + ReinjectSystemPrompt, AbstractCapability, EndStrategy + AgentRetries, ModelRequestContext. All verified against 1.102.0 source.

Class deep dives Vol. 3 — 10 classes MCPToolset + load_mcp_toolsets, UIAdapter + MessagesBuilder, CachePoint + CompactionPart, format_as_xml, BinaryContent + FileUrl family (ImageUrl/AudioUrl/VideoUrl/DocumentUrl), DeferredToolRequests + DeferredToolResults + CallDeferred + ApprovalRequired, NativeTool, NativeOrLocalTool, DynamicCapability, ToolSearch. All verified against 1.103.0 source.

Class deep dives Vol. 4 — 10 classes LangChainTool + LangChainToolset, VercelAIAdapter (SDK v5/v6 + HITL), ToolManager + ValidatedToolCall (parallel/sequential execution), ThreadExecutor (bounded thread pool), PrefixTools (tool namespacing), PrepareTools + PrepareOutputTools (per-step filtering), ImageGeneration (native + fallback), XSearch (xAI + non-xAI), common_tools (DuckDuckGo, Tavily, Exa), FunctionSignature + TypeSignature (Code Mode stubs). All verified against 1.104.0 source.

Class deep dives Vol. 5 — 10 classes PendingMessage + RunContext.enqueue/AgentRun.enqueue (mid-run message injection, 'asap'/'when_idle' priorities), AgentWorker + agent_to_a2a (A2A protocol bridge), WrapperAgent (agent middleware base), safe_download + SSRF protection (cloud metadata blocking, IPv6 transition decoding), DBOSAgent (durable workflow steps), StreamedResponseSync (thread-queue sync streaming), ModelResponsePartsManager (streaming event infrastructure), CombinedCapability (hook ordering + merging), FastMCPToolset (deprecated → MCPToolset migration), SetToolMetadata (Code Mode + dynamic metadata). All verified against 1.104.0 source.

Class deep dives Vol. 6 — 10 classes ToolReturn (structured return + metadata, typed return schema), TextContent (app-only metadata on user content), FilePart + BinaryImage (model file responses, provider round-trip data), Direct API — model_request/model_request_sync/model_request_stream/model_request_stream_sync (raw model calls), ModelRequestParameters (full wire-format reference), error hierarchy — ModelAPIError/ModelHTTPError/ContentFilterError/IncompleteToolCall, ToolApproved + ToolDenied (HITL approval result pair), JsonSchemaTransformer + InlineDefsJsonSchemaTransformer (custom schema walk), TemporalAgent (durable Temporal execution, activity config), ToolsetTool (toolset tool wrapper, args_validator_func). All verified against 1.104.0 source.

Class deep dives Vol. 7 — 10 classes AgentEventStream + AgentRunResultEvent (event streaming, PartStartEvent/PartDeltaEvent/PartEndEvent/FunctionToolCallEvent taxonomy), ThinkingPart + ThinkingPartDelta (extended thinking, provider signature round-trip, delta apply()), AudioUrl + VideoUrl + DocumentUrl (multimodal URL types, force_download, vendor_metadata, YouTube detection), OutputContext (output hook context, mode/output_type/tool_call/allows_* fields), ModelRetry (retry from tools/validators/hooks, Pydantic serialisation), RequestUsage (per-call token tracking, audio tokens, details, cache hit rate), WebSearchTool + WebSearchUserLocation (localized search, domain filtering, provider matrix), MemoryTool (native memory, Anthropic only, optional flag), CodeExecutionTool (native code execution, multi-provider, CSV/chart generation), AbstractNativeTool (custom native tool base, NATIVE_TOOL_TYPES registry, unique_id, optional). All verified against 1.104.0 source.

Class deep dives Vol. 8 — 10 classes ToolOutput + NativeOutput + PromptedOutput + TextOutput + StructuredDict (output-mode marker classes; per-output mode control; max_retries; template=False; StructuredDict $defs inlining), ApprovalRequiredToolset (HITL toolset-level guard; conditional filter; argument-based approval; tool_call_approved resume), DeferredLoadingToolset (lazy discovery; tool_names=None; ToolSearch pairing; FilteredToolset composition), Embedder + EmbeddingModel + EmbeddingResult + EmbeddingSettings (full embeddings API; query vs document inputs; cost(); dimensions truncation; RAG pipeline), web_fetch_tool + WebFetchLocalTool (HTML→markdown; BinaryContent fallback; domain allow/block lists), PrefectAgent + TaskConfig (Prefect durable execution; TaskConfig TypedDict; per-tool override; DEFAULT_PYDANTIC_AI_CACHE_POLICY), ImageGenerationSubagentTool (subagent with separate model; FallbackModelFunc; image-only model guard), ConcurrencyLimitedModel + AbstractConcurrencyLimiter (per-model HTTP gating; shared limiter; max_queued backpressure; distributed ABC), InstructionPart + AgentInstructions (runtime instruction dataclass; dynamic flag for prompt-caching; sorted() for stable prefixes), OutputObjectDefinition (json_schema/name/description/strict; output hook schema inspection). All verified against 1.105.0 source.

Class deep dives Vol. 9 — 10 classes ModelRequest + ModelResponse (wire-format anatomy; FinishReason/ModelResponseState aliases; run_id/conversation_id threading; ModelMessagesTypeAdapter ser/de), SystemPromptPart + UserPromptPart + RetryPromptPart (request-side parts; multi-modal UserContent; dynamic_ref OTel attribution; RetryPromptPart.model_response() error formatting), BaseToolCallPart + ToolCallPart + NativeToolCallPart (call-part family; args_as_dict raise_if_invalid; narrow_type() typed subclass promotion; ToolCallPartDelta streaming), BaseToolReturnPart + ToolReturnPart + NativeToolReturnPart (return-part family; outcome success/failed/denied; content_items mode=; files property; provider_details round-trip), GraphAgentState (run-state dataclass; message_history/usage/run_id/conversation_id; check_incomplete_tool_call; consume_output_retry), MCPServerTool (native MCP server integration; OpenAI/Anthropic/xAI; allowed_tools; connector_id prefix; vs MCPToolset), FileSearchTool (native RAG; OpenAI vector stores/Gemini Files API/xAI collections; zero-code chunking), IncludeReturnSchemasToolset (PreparedToolset subclass; auto include_return_schema=True injection; FilteredToolset composition), ToolChoice + ToolOrOutput (ToolChoiceScalar/list/ToolOrOutput/None; function-tool-only restriction with output; capability hook pattern), ServiceTier + ThinkingLevel/ThinkingEffort (cross-provider billing tier; unified thinking effort levels; provider mapping table; dynamic selection). All verified against 1.105.0 source.

Class deep dives Vol. 10 — 10 classes AgentStream (full streaming API; stream_output/stream_response/stream_text/cancel/drain/validate_response_output/get_output; run_id/conversation_id/metadata/cancelled), WrapperCapability (transparent capability middleware; __post_init__ id/defer_loading inheritance; apply() tree traversal; observer vs transformer patterns), FunctionToolset (all 14 constructor params; @tool/@tool_plain; add_function/add_tool; instructions; timeout; defer_loading; include_return_schema; requires_approval; sequential; id for durable execution), AbstractToolset (custom toolset ABC; for_run/for_run_step; get_instructions; get_tools/call_tool; __aenter__/__aexit__; stateful per-run isolation pattern), ToolCallEvent + ToolResultEvent + FunctionToolCallEvent + FunctionToolResultEvent + OutputToolCallEvent + OutputToolResultEvent (complete tool event taxonomy; args_valid; content; discriminator match patterns), FinalResult + FinalResultEvent (output result markers; tool_name/tool_call_id; text vs tool output; early-exit streaming pattern), UserError + UsageLimitExceeded + ConcurrencyLimitExceeded + UndrainedPendingMessagesError + HookTimeoutError (remaining error types; full exception hierarchy; when each fires; hook_name/func_name/timeout on HookTimeoutError), multimodal type system (AudioMediaType/ImageMediaType/DocumentMediaType/VideoMediaType; AudioFormat/ImageFormat/DocumentFormat/VideoFormat; ForceDownloadMode False/True/'allow-local'; ProviderDetailsDelta static/callable/None; MIME auto-detection), AbstractCapability extended (defer_loading with lazy load catalog; get_description() for routing; get_ordering() topology; wrap_run/wrap_node_run/wrap_model_request/wrap_tool_validate/wrap_tool_execute/wrap_output_validate/wrap_output_process hooks; WrapRunHandler family), CapabilityOrdering + CapabilityPosition + CapabilityRef + CAPABILITY_TYPES (position outermost/innermost; wraps/wrapped_by type and instance refs; requires; topological sort; cycle detection; has_capability_type utility). All verified against 1.105.0 source.

Class deep dives Vol. 11 — 10 class groups UserPromptNode + ModelRequestNode + CallToolsNode (agent graph nodes promoted to public __all__; run state machine; node-level streaming; deferred tool resume), AgentCapability + AgentToolset + ToolsetFunc (dynamic callable dispatch; per-run feature flags), AgentModelSettings + AgentNativeTool (callable model settings and conditional native tools), HandleResponseEvent + ModelResponseStreamEvent (discriminated union aliases; CallToolsNode event consumption), ToolSearchCallPart + NativeToolSearchCallPart + ToolSearchArgs + ToolSearchMatch (two-path tool search calls; cross-path detection via tool_kind), ToolSearchReturnPart + NativeToolSearchReturnPart + ToolSearchReturnContent (tool search results; discovered_tools; empty-search handling), LoadCapabilityCallPart + LoadCapabilityReturnPart (deferred capability loading parts; capability_id; instructions extraction), BuiltinToolCallEvent + BuiltinToolResultEvent deprecated migration (→ PartStartEvent/PartEndEvent with NativeToolCallPart/NativeToolReturnPart), AgentInstructions + AgentMetadata (full union forms; per-run overrides; prompt caching; OTel metadata), Agent 1.106.0 constructor reference (tool_timeout; max_concurrency; callable model_settings; capabilities; description). All verified against 1.106.0 source.

Class deep dives Vol. 12 — 10 class groups Dataset + Case (pydantic_evals dataset management; YAML/JSON round-trip; add_case/add_evaluator; repeat stability testing; retry_task/retry_evaluators), Evaluator + EvaluatorContext + EvaluationResult + EvaluationReason (base evaluator API; all five EvaluatorOutput forms; async evaluators; versioned evaluators; EvaluationResult.downcast), built-in evaluators Equals + EqualsExpected + Contains + IsInstance + MaxDuration + HasMatchingSpan (all params; case_sensitive/as_strings; timedelta for MaxDuration; SpanQuery in HasMatchingSpan), LLMJudge + GradingOutput + judge_output/judge_input_output/judge_output_expected/judge_input_output_expected (score/assertion OutputConfig; include_input/include_expected_output; set_default_judge_model), generate_dataset (schema inference from generic params; custom_evaluator_types; save/cache guard), online evaluation evaluate decorator + OnlineEvalConfig + OnlineEvaluator (sample_rate float or callable; sampling_mode independent/correlated; disable_evaluation; wait_for_evaluations; custom EvaluationSink), SpanTree + SpanNode + SpanQuery (all query fields; any/all/find/find_all; composite queries with and_/or_/not_; increment_eval_metric/set_eval_attribute), MCPSamplingModel + MCPSamplingModelSettings (MCP server sampling; ModelPreferences; default_max_tokens; streaming limitation), RetryConfig + TenacityTransport + AsyncTenacityTransport + wait_retry_after (TypedDict fields; validate_response; Retry-After header parsing; attach to OpenAI provider http client; before_sleep logging), ExternalToolset (kind 'external'; approval queue pattern; HITL comparison table vs ApprovalRequiredToolset; id for durable execution). All verified against pydantic-ai 1.106.0 / pydantic-evals 1.106.0 source.

Class deep dives Vol. 13 — 10 class groups `Capability` (`@cap.tool`/`@cap.tool_plain`/`@cap.instructions`; `defer_loading=True`; callable description; role-scoped caps; shared instance), `MCP` capability (`native=True`; native-only; local-only with auth; deferred; migration from `MCPToolset`), `WebSearch` (`search_context_size`; `WebSearchUserLocation`; domain allow-list; force DuckDuckGo; custom async local), `WebFetch` (citations; intranet allow-list; force local; combined with WebSearch; custom proxy), `XSearch` (xAI native; `fallback_model` for non-xAI; date range; handle filter; image+video understanding), `Instrumentation` (Logfire; privacy mode; OTel v2; `from_spec()`; custom span attributes), `HandleDeferredToolCalls` (`approve_all`; selective by risk; two-handler chain; async webhook), `ProcessEventStream` (log observer; latency observer; ThinkingPart strip; audit injector; combined observer+processor), `WebFetchTool`+`XSearchTool`+`ImageGenerationTool` (all fields; provider matrix; deprecated `UrlContextTool` alias; `NativeTool` wrapping), `ToolSearch` (all strategies; `max_results`; combined with deferred `Capability`). All verified against pydantic-ai 1.107.0 source.

Class deep dives Vol. 14 — 10 class groups UIAdapter + UIEventStream + StateDeps + StateHandler + OnCompleteFunc (unified UI protocol base; dispatch_request; manage_system_prompt; SSRF security policy), AGUIAdapter (new dispatch_request pattern; ag_ui_version thresholds 0.1.13/0.1.15 for REASONING_* events + typed multimodal; migration from deprecated AGUIApp), VercelAIAdapter updated (sdk_version=6 HITL approval streaming; server_message_id; dispatch_request), Provider ABC + infer_provider/infer_provider_class (abstract client base; model_profile(); context manager lifecycle; custom provider authoring), ModelProfile complete field reference (all 17 fields; StructuredOutputMode; from_profile()/update(); deprecated alias handling), AnthropicModelProfile + OpenAIModelProfile (adaptive thinking; effort support; xhigh_effort; disallows_sampling; openai_chat_thinking_field; openai_chat_send_back_thinking_parts), WrapperEmbeddingModel + InstrumentedEmbeddingModel (custom embedding wrappers; caching pattern; OTel span with usage/cost), additional embedding providers (GoogleEmbeddingModel/BedrockEmbeddingModel/CohereEmbeddingModel/VoyageAIEmbeddingModel; provider comparison table; RAG pipeline with cost()), BuilderCheckpoint + MessagesBuilder advanced (checkpoint/last_modified attribution; custom UIEventStream implementation), OutlinesModel deprecated (constrained generation; from_transformers/from_llamacpp/from_sglang/from_mlxlm/from_vllm_offline; migration to NativeOutput). All verified against pydantic-ai 1.107.0 source.

Class deep dives Vol. 15 — 10 class groups CombinedToolset (multi-toolset merging + name-conflict detection), HuggingFaceModel + HuggingFaceModelSettings + HuggingFaceStreamedResponse (open-source Hub inference), TestEmbeddingModel (deterministic mock embeddings), SentenceTransformerEmbeddingModel + SentenceTransformersEmbeddingSettings (on-device local embeddings), TemporalRunContext + deserialize_run_context (serializable RunContext for Temporal activities), PydanticAIWorkflow (Temporal Workflow base class), TemporalDynamicToolset (DynamicToolset in Temporal activities), PrefectAgentInputs + DEFAULT_PYDANTIC_AI_CACHE_POLICY (Prefect cache policy), ACIToolset + tool_from_aci (deprecated ACI.dev bridge + migration guide), provider model-profile functions (GrokModelProfile/GroqModelProfile/deepseek/qwen/cohere/moonshotai). All verified against pydantic-ai 1.107.0 source.

Class deep dives Vol. 16 — 10 class groups AgentRunResult (all_messages/new_messages/usage/output_tool_return_content multi-turn), StreamedRunResult + StreamedRunResultSync (stream_output/stream_text/stream_response/get_output + sync wrapper), Tool direct construction (all 17 params + from_schema/from_function/prepare), GenerateToolJsonSchema + DocstringFormat (4 docstring formats + require_parameter_descriptions + custom schema_generator), MistralModel + MistralModelSettings + MistralStreamedResponse (Mistral provider + json_mode_schema_prompt + Pixtral), OllamaModel (self-hosted vs Cloud NativeOutput — supports_json_schema_output auto-disable), OpenRouterModel + OpenRouterModelSettings + OpenRouterModelProfile + OpenRouterReasoning (meta-provider — fallback chain/provider routing/reasoning tokens), NamedSpec + CapabilitySpec + build_registry + load_from_registry (YAML/JSON spec-driven capability composition), OutputSchema + OutputValidator (OutputSchema.build() factory + 5 concrete subclasses + sync/async validate), GraphRun + NodeStep (v2 graph execution — state manager/fork-join/v1 BaseNode bridge). All verified against pydantic-ai 1.107.0 source.

Class deep dives Vol. 17 — 10 class groups LiteLLMProvider (universal proxy routing), AzureProvider (Azure AI Foundry + ADC), DeepSeekProvider (reasoning_content + send_back_thinking_parts), CerebrasProvider (ultra-fast inference + reasoning models), GitHubProvider (provider/model:tag naming), FireworksProvider + TogetherProvider + NebiusProvider + SambaNovaProvider (GPU provider quartet), GraphBuilder (pydantic_graph fluent builder), Fork + Join + ReducerContext (parallel fan-out/fan-in), Decision + DecisionBranch + Edge + TypeExpression (conditional routing), Step + StepContext + StepNode (step execution primitives). All verified against pydantic-ai 1.107.0 source.

Class deep dives Vol. 18 — 10 class groups AlibabaProvider (DashScope + DASHSCOPE_API_KEY + Qwen omni audio URI encoding), OVHcloudProvider (European AI Endpoints + 6-family prefix profile routing), HerokuProvider (Heroku Inference + HEROKU_INFERENCE_KEY/URL), gateway_provider (Pydantic AI Gateway — upstream dispatch + route override + region-encoded API key), GoogleProvider + GoogleCloudProvider (Gemini API vs Google Cloud/Vertex AI), GoogleModel + GoogleModelSettings (all 9 settings — google_cached_content caveat + safety + MediaResolution + GoogleCloudServiceTier), CohereModel + CohereProvider + CohereModelSettings (Command-R via AsyncClientV2), XaiProvider + XaiModel (gRPC SDK + _LazyAsyncClient + GrokModelProfile/GrokReasoningEffort), FileStatePersistence (atomic file-lock pydantic_graph persistence), SimpleStatePersistence + FullStatePersistence (in-memory graph persistence — dump_json/load_json). All verified against pydantic-ai 1.107.0 source.

Class deep dives Vol. 19 — 10 class groups BedrockConverseModel + BedrockModelSettings (9 bedrock_ settings, prompt caching TTL, guardrails, _FINISH_REASON_MAP), BedrockProvider + BedrockModelProfile + BedrockJsonSchemaTransformer + 8 profile functions (credential rotation, 10 profile fields, strict-mode schema rewrites), GoogleGLAProvider + GoogleVertexProvider deprecated (migration tables, _VertexAIAuth token refresh, 29-region VertexAiRegion), DynamicToolset (per_run_step factory pattern, role RBAC, feature flags), CapabilityOwnedToolset + resolve_capability_id + tool_defs_for_loaded_capabilities (capability-toolset binding, deferred metadata stamping), Web UI API create_api_app (4 Starlette routes, ModelInfo/BuiltinToolInfo/ConfigureFrontend/ChatRequestExtra, camelCase JSON), OTel GenAI spec message types (9 TypedDicts, UriPart/BlobPart v4, ToolCallPartOtelMetadata), Thinking capability (single-field ThinkingLevel=True, portable cross-provider), ImageGeneration capability (12-field matrix, fallback_model subagent, action=edit, fallback_model+local mutual exclusion), pydantic_graph persistence + exceptions (NodeSnapshot/EndSnapshot anatomy, BaseStatePersistence ABC, SnapshotStatus lifecycle, full exception hierarchy). All verified against pydantic-ai 1.107.0 source.

Class deep dives Vol. 20 — 10 class groups Hooks capability (decorator hook registration — 25+ hooks, tools= filter, timeout=, HookTimeoutError), Instrumentation capability (OTel/Logfire — position=outermost, per-run isolation, ToolRetryError/ApprovalRequired classified OK), ConcurrencyLimiter + AbstractConcurrencyLimiter + ConcurrencyLimit (anyio-backed — OTel span per wait, max_queued backpressure, from_limit()), CombinedToolset + PrefixedToolset + RenamedToolset + FilteredToolset + PreparedToolset (composable toolset middleware — conflict detection, async filter, prepare_func constraint), ApprovalRequiredToolset + ExternalToolset (HITL approval — ctx.tool_call_approved, external tool kind, DeferredToolset deprecated alias), TemplateStr (Handlebars instructions — {{ trigger, typed compile, Union[TemplateStr,str] fallthrough), FunctionSchema (function→LLM schema — takes_ctx auto-detect, single_arg_name, return_schema, async/sync), safe_download + ResolvedUrl (SSRF — 14 IPv4 + 7 IPv6 private ranges, 7 cloud metadata IPs always blocked, IPv6 transition decoding, per-hop redirect validation), LoadCapabilityCallPart + LoadCapabilityReturnPart + parse_loaded_capabilities (deferred capability wire protocol — capability-load discriminator, capability_id property), ModelProfile + DEFAULT_PROFILE + ModelProfileSpec (model capability — 14 fields, from_profile/update merge, lazy deprecated kwarg aliases). All verified against pydantic-ai 1.107.0 source.

Advanced patterns

Error handling & testing

Hooks Lifecycle callbacks: Hooks capability.

Concurrency ConcurrencyLimiter, backpressure, distributed limiting.

Embeddings Embedder, EmbeddingModel, similarity search.

Durable execution (2025)

Graph support (2025)

Integrations 2025

Evals (2025)

Recipes

Diagrams

Production guide

Streaming server (FastAPI)

What’s new in v1.107.0 (June 2026, Vol. 20)

v1.107.0 (June 2026, Vol. 20) — Library installed (1.107.0) and source inspected directly. Ten new class groups covering the core middleware and security infrastructure of pydantic-ai: Hooks capability (pydantic_ai.capabilities.Hooks — decorator-based hook registration via hooks.on.<hook_name>; 25+ lifecycle hooks; tools=['name'] filter restricts to specific tools; timeout= per hook raises HookTimeoutError(TimeoutError) on expiry; get_ordering() returns position='middle'), Instrumentation capability (pydantic_ai.capabilities.Instrumentation — OpenTelemetry/Logfire tracing; get_ordering() returns position='outermost'; per-run state isolation via dataclasses.replace(self) in for_run(); ToolRetryError/ApprovalRequired/CallDeferred set span status OK; from_spec(**kwargs) for YAML/JSON config), ConcurrencyLimiter + AbstractConcurrencyLimiter + ConcurrencyLimit (pydantic_ai.concurrency — anyio CapacityLimiter wrapper; fast-path acquire_nowait() first; OTel span created only when waiting; _queue_lock atomic counter prevents race on max_queued enforcement; ConcurrencyLimitExceeded on overflow; normalize_to_limiter() and get_concurrency_context() module-level helpers; AnyConcurrencyLimit type alias), toolset composition (CombinedToolset — flat-merges tools from a Sequence[AbstractToolset]; raises UserError on name conflict with hint; _CombinedToolsetTool tracks source_toolset/source_tool for correct dispatch; apply() and visit_and_replace() visitor traversal), (PrefixedToolset(wrapped, prefix) — renames every tool to {prefix}_{original}; call_tool strips prefix with removeprefix), (RenamedToolset(wrapped, name_map) — name_map = {new_name: original_name}; tools not in map pass through unchanged), (FilteredToolset(wrapped, filter_func) — accepts sync and async filter; tools where filter_func returns False are hidden), (PreparedToolset(wrapped, prepare_func) — mutates ToolDefinition fields; cannot add or rename tools; warns if prepare_func returns None), ApprovalRequiredToolset + ExternalToolset (ApprovalRequiredToolset(wrapped, approval_required_func=lambda ...: True) — raises ApprovalRequired when not ctx.tool_call_approved and approval_required_func(ctx, tool_def, tool_args); ExternalToolset(tool_defs, id=None) — forces kind='external' on all tools; call_tool() raises NotImplementedError; TOOL_SCHEMA_VALIDATOR = SchemaValidator(any_schema()) passes all args; DeferredToolset is a @deprecated alias), TemplateStr (pydantic_ai.TemplateStr — Generic[AgentDepsT]; '{{' not in value fails validation causing fallthrough to str in Union[TemplateStr, str]; deps_type known → hbs.compile(source, deps_type); unknown → untyped compile + TypeAdapter dump at render; __call__(ctx) renders against ctx.deps; serialises back to raw _source), FunctionSchema (pydantic_ai._function_schema.function_schema() factory; takes_ctx auto-detected from first param annotation; single_arg_name set for model-like or primitive single args; return_schema extracted from return annotation; sync functions wrapped with run_in_executor; docstring_format='auto'/'google'/'numpy'/'restructuredtext'; require_parameter_descriptions=True raises UserError for missing descriptions), safe_download + ResolvedUrl (pydantic_ai._ssrf — 14 IPv4 + 7 IPv6 private CIDR blocks blocked unless allow_local=True; 7 cloud metadata IPv4 + 4 IPv6 addresses always blocked including Azure 168.63.129.16 (public IP); IPv6 transition decoding for NAT64/6to4/ISATAP/Teredo/IPv4-mapped; trailing dot stripped from hostname; sensitive headers authorization/cookie/proxy-authorization stripped on cross-origin redirect; max_redirects=10, timeout=30; each redirect hop re-validated against private-IP and domain lists), LoadCapabilityCallPart + LoadCapabilityReturnPart + parse_loaded_capabilities (pydantic_ai._deferred_capabilities — tool_kind='capability-load' discriminator prevents user tools named load_capability from being promoted; DEFERRED_CAPABILITY_TOOL_METADATA_KEY = 'pydantic_ai_deferred_capability_tool'; LoadCapabilityArgs TypedDict with id: str; LoadCapabilityReturn TypedDict with instructions: NotRequired[str]; parse_loaded_capabilities(messages) walks history to collect loaded capability IDs; wire tags 'capability-load-call'/'capability-load-return'), ModelProfile + DEFAULT_PROFILE + ModelProfileSpec (pydantic_ai.profiles.ModelProfile — 14 fields: supports_tools=True, supports_tool_return_schema=False, supports_json_schema_output=False, supports_json_object_output=False, supports_image_output=False, supports_inline_system_prompts=False, default_structured_output_mode='tool', supports_thinking=False, thinking_always_enabled=False, thinking_tags=('<think>','</think>'), ignore_streamed_leading_whitespace=False, supported_native_tools=SUPPORTED_NATIVE_TOOLS, json_schema_transformer=None; from_profile(profile) class method; update(profile) merges non-default values; deprecated kwarg alias supported_builtin_tools→supported_native_tools installed lazily via __new__ MRO walk; DEFAULT_PROFILE = ModelProfile(); ModelProfileSpec = ModelProfile | Callable[[str], ModelProfile | None]). New guide pydantic_ai_class_deep_dives_v20.md created (sidebar order 46). Index updated with Zero→Hero step 40, Jump-to-topic card, Reference card.

What’s new in v1.107.0 (June 2026, Vol. 19)

v1.107.0 (June 2026, Vol. 19) — Library installed (1.107.0) and source inspected directly. Ten new class groups providing the first-ever complete coverage of the AWS Bedrock ecosystem, deprecated Google provider migration guides, and deep dives into internal toolset/capability binding infrastructure: BedrockConverseModel + BedrockModelSettings + BedrockStreamedResponse (first-ever AWS Bedrock coverage; 9 bedrock_-prefixed ModelSettings TypedDict fields; prompt caching with True/'5m'/'1h' TTL consuming up to 4 cache-point slots; _FINISH_REASON_MAP with all 9 entries; guardrail config and performance configuration; boto3 sync bridge via anyio.to_thread.run_sync), BedrockProvider + BedrockModelProfile + BedrockJsonSchemaTransformer + 8 profile functions (3 provider construction paths: own-client/bearer-token/AWS credentials; client setter for credential rotation; 10 bedrock_-prefixed ModelProfile fields with defaults; strict-mode JSON Schema rewrites stripping unsupported constraints and surfacing them in description; bedrock_anthropic_model_profile/bedrock_amazon_model_profile/bedrock_deepseek_model_profile/bedrock_mistral_model_profile/bedrock_qwen_model_profile/bedrock_google_model_profile/bedrock_minimax_model_profile/bedrock_nvidia_model_profile; _without_builtin_tools strips native tools for Converse API), GoogleGLAProvider + GoogleVertexProvider (deprecated — both deprecated in favour of GoogleProvider/GoogleCloudProvider; migration tables: project_id=→project=, region=→location=, GEMINI_API_KEY→GOOGLE_API_KEY; _VertexAIAuth token refresh on 401; _refresh_lock as @functools.cached_property for correct event-loop binding; VertexAiRegion Literal with 29 valid values), DynamicToolset (per_run_step=True default re-evaluates factory before every model call; per_run_step=False evaluates once at for_run(); transition-safe: old toolset detached before exit, new registered only after successful enter; id= for Temporal durable execution; __eq__ uses identity for toolset_func), CapabilityOwnedToolset + resolve_capability_id + tool_defs_for_loaded_capabilities (stamps capability_id on all inner tool defs; sets DEFERRED_CAPABILITY_TOOL_METADATA_KEY metadata when defer_loading is True; get_instructions returns None for deferred caps; resolve_capability_id iterates ctx.capabilities by identity; tool_defs_for_loaded_capabilities wire-side filter for ToolSearchToolset), Web UI API create_api_app + ModelInfo + BuiltinToolInfo + ConfigureFrontend + ChatRequestExtra (4 Starlette routes: POST /chat, OPTIONS /chat, GET /configure, GET /health; alias_generator=to_camel on all Pydantic models — builtinTools in JSON; validate_request_options returns error string or None; model dedup by model_id; VercelAIAdapter.dispatch_request streaming backend), OTel GenAI spec message types (9 TypedDict types: TextPart/ToolCallPart/ToolCallResponsePart/MediaUrlPart/UriPart/FilePart/BinaryDataPart/BlobPart/ThinkingPart; v4 instrumentation upgrade MediaUrlPart→UriPart with modality field; DocumentUrl omits modality; ToolCallPartOtelMetadata code_arg_name/code_arg_language for Logfire syntax highlighting; ChatMessage/OutputMessage with finish_reason), Thinking capability (single-field @dataclass; effort: ThinkingLevel = True; ThinkingLevel = bool | Literal['minimal','low','medium','high','xhigh']; get_model_settings() returns ModelSettings(thinking=self.effort); provider-specific settings take precedence), ImageGeneration capability (extends NativeOrLocalTool; 12 configuration fields; fallback_model spawns subagent for non-native models; fallback_model + local mutual exclusion raises UserError; action='edit'/'generate'/'auto'; background='transparent' only for png/webp; input_fidelity='high'/'low'; deprecated builtin= kwarg maps to native=), pydantic_graph persistence primitives + exception hierarchy (NodeSnapshot/EndSnapshot @dataclass types with kind discriminator; UNSET_SNAPSHOT_ID = '__unset__' sentinel; SnapshotStatus lifecycle 'created'→'pending'→'running'→'success'/'error'; BaseStatePersistence ABC; GraphSetupError(TypeError)/GraphBuildingError(ValueError)/GraphValidationError(ValueError)/GraphRuntimeError(RuntimeError)/GraphNodeStatusError(GraphRuntimeError) with message: str; GraphNodeStatusError.check(status) raises for non-{'created','pending'} statuses). New guide pydantic_ai_class_deep_dives_v19.md created (sidebar order 45). Index updated with Zero→Hero step 39, Jump-to-topic card, Reference card.

What’s new in v1.107.0 (June 2026, Vol. 18)

v1.107.0 (June 2026, Vol. 18) — Library installed (1.107.0) and source inspected directly. Ten new class groups covering new providers, the complete Google provider ecosystem, and pydantic_graph persistence backends: AlibabaProvider (Alibaba Cloud DashScope — ALIBABA_API_KEY/DASHSCOPE_API_KEY dual env-var; international endpoint dashscope-intl.aliyuncs.com/compatible-mode/v1; qwen_model_profile wrapped in OpenAIModelProfile; 'omni' name check forces openai_chat_audio_input_encoding='uri'), OVHcloudProvider (OVHcloud AI Endpoints oai.endpoints.kepler.ai.cloud.ovh.net/v1; six-prefix model-family dispatch: llama/meta- → meta_model_profile, deepseek → deepseek_model_profile, mistral → mistral_model_profile, gpt → harmony_model_profile, qwen → qwen_model_profile; all wrapped in OpenAIModelProfile), HerokuProvider (Heroku Inference API; HEROKU_INFERENCE_KEY + HEROKU_INFERENCE_URL; default https://us.inference.heroku.com; base_url .rstrip('/') + '/v1' normalisation; always OpenAIModelProfile), gateway_provider (Pydantic AI Gateway factory function; upstream_provider selects client type: 'openai' → Provider[AsyncOpenAI], 'anthropic' → Provider[AsyncAnthropicClient], 'bedrock' → Provider[BaseClient], 'google-cloud' → Provider[GoogleClient]; route override; PYDANTIC_AI_GATEWAY_API_KEY/PAIG_API_KEY; region-encoded key pattern pylf_v<version>_<region>_<token> auto-infers base URL; deprecated 'gemini'/'google-vertex' aliases emit PydanticAIDeprecationWarning; _request_hook injects OTel traceparent + Authorization on every request), GoogleProvider + GoogleCloudProvider (both extend BaseGoogleProvider[Client]; BaseGoogleProvider._build_http_options() pins httpx timeout from DEFAULT_HTTP_TIMEOUT to prevent SDK override; GoogleProvider — Gemini API, GOOGLE_API_KEY, vertexai=True/location/project/credentials deprecated → use GoogleCloudProvider; GoogleCloudProvider — Vertex AI / Google Cloud, Express Mode API key or ADC credentials/project/location), GoogleModel + GoogleModelSettings (nine google_-prefixed settings: google_safety_settings list[SafetySettingDict], google_thinking_config ThinkingConfigDict, google_labels dict[str,str] Vertex billing, google_video_resolution MediaResolution, google_cached_content str — strips system_instruction/tools/tool_config and emits UserWarning when dropping, google_logprobs bool Vertex non-streaming only, google_top_logprobs int, google_cloud_service_tier GoogleCloudServiceTier PT/Flex/Priority routing, google_service_tier deprecated), CohereModel + CohereProvider + CohereModelSettings (Cohere v2 API via cohere.AsyncClientV2; CO_API_KEY + CO_BASE_URL env vars; LatestCohereModelNames union: command-r-plus-08-2024/command-r-08-2024/command-r7b-12-2024/command-nightly/c4ai-aya-expanse-32b/c4ai-aya-expanse-8b; ModelSettings → Cohere params mapping: top_p→p, top_k→k; thinking content via ThinkingAssistantMessageV2ContentOneItem; CohereProvider.model_profile adds supports_inline_system_prompts=True), XaiProvider + XaiModel (xAI gRPC SDK xai_sdk.AsyncClient; _LazyAsyncClient defers construction per event-loop — recreates AsyncClient when running loop differs, fixing gRPC channel binding issue; XaiProvider.base_url is a canonical pricing label not the gRPC channel host; GrokModelProfile fields: grok_supports_builtin_tools/grok_supports_tool_choice_required/grok_reasoning_efforts frozenset[GrokReasoningEffort]; GrokReasoningEffort: Literal['none','low','medium','high']; grok-4.3 and _GROK_43_REASONING_MODELS get full {'none','low','medium','high'} effort set + builtin tools; gRPC status → HTTP code mapping; XAI_API_KEY env var), FileStatePersistence (file-based pydantic_graph persistence; json_file: Path — one file per run, reused across steps; pydantic.TypeAdapter[list[Snapshot[StateT, RunEndT]]] registered via set_types(); _lock() async context manager creates .pydantic-graph-persistence-lock sibling file using atomic anyio.open_file(mode='ab') append-check; 1 s timeout with 10 ms polling; record_run(snapshot_id) transitions 'created'→'running' then 'running'→'success'/'error' with duration; anyio thread executor for sync JSON I/O), SimpleStatePersistence + FullStatePersistence (SimpleStatePersistence is the implicit default — stores only last_snapshot; load_all() raises NotImplementedError; FullStatePersistence maintains history: list[Snapshot]; deep_copy: bool = True via copy.deepcopy on state and node.deep_copy()/end.deep_copy_data(); dump_json(indent=) / load_json(data) full round-trip via registered TypeAdapter; set_types() must be called before dump_json/load_json; deep_copy=False safe when state is frozen/immutable). New guide pydantic_ai_class_deep_dives_v18.md created (sidebar order 44). Index updated with Zero→Hero step 38, Jump-to-topic card, Reference card.

What’s new in v1.107.0 (June 2026, Vol. 17)

v1.107.0 (June 2026, Vol. 17) — Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived spanning the full provider ecosystem and the new pydantic_graph builder API: LiteLLMProvider (universal proxy provider; provider/model prefix routing dispatches to 12 provider profile functions — anthropic_model_profile/openai_model_profile/google_model_profile/mistral_model_profile/cohere_model_profile/amazon_model_profile/meta_model_profile/groq_model_profile/deepseek_model_profile/moonshotai_model_profile/grok_model_profile/qwen_model_profile; api_base + api_key='litellm-placeholder'; openai_client override; pre-built AsyncOpenAI pass-through), AzureProvider (Azure AI Foundry Express Mode; GA /v1-suffix endpoints suppress api_version; serverless model endpoints *.models.ai.azure.com skip api_version; Entra ID via AsyncAzureOpenAI with azure_ad_token_provider; six non-OpenAI model-family profiles; openai_chat_supports_document_input=False on all Azure profiles), DeepSeekProvider (reasoning_content wire field for R1 thinking tokens surfaced as ThinkingPart; openai_chat_send_back_thinking_parts='field' for multi-turn context; thinking_always_enabled=True for R1 and deepseek-reasoner; V4 models deepseek-v4-* with reasoning_effort control; tool_choice=required restriction for reasoning models and all deepseek-v4-* SKUs; DEEPSEEK_API_KEY env var), CerebrasProvider (X-Cerebras-3rd-Party-Integration: pydantic-ai integration header; zai-* and gpt-oss-* reasoning models with supports_thinking=True; 6 disabled model settings — frequency_penalty/logit_bias/presence_penalty/parallel_tool_calls/service_tier/openai_service_tier; harmony_model_profile for gpt-oss; CEREBRAS_API_KEY), GitHubProvider (GitHub Models at https://models.github.ai/inference; provider/model:tag naming — :tag suffix stripped before profile lookup; 6 provider-to-profile mappings: xai → grok, meta → meta, microsoft → openai, mistral-ai → mistral, cohere → cohere, deepseek → deepseek; prefix-free names → openai_model_profile; GITHUB_API_KEY env var), FireworksProvider + TogetherProvider + NebiusProvider + SambaNovaProvider (four OpenAI-compatible GPU providers: Fireworks strips accounts/fireworks/models/ path prefix before profile lookup; Together uses org/model naming with 5-family dispatch; Nebius uses org/model with no-slash immediate OpenAI-profile fallback and openai/ → harmony_model_profile; SambaNova adds SAMBANOVA_BASE_URL env var for on-prem deployment and validates API key at construction time; all four implement Provider[AsyncOpenAI]), GraphBuilder (new pydantic_graph fluent API replacing deprecated BaseNode subclass pattern; step(call, *, node_id, label) as bare decorator or factory; stream(call, ...) wraps async generators into AsyncIterable-returning steps; join(reducer, initial, ...) builds fan-in with plain or context-aware reducer; decision(*, note, node_id) creates conditional routing nodes; add(*edges) / add_edge(source, destination, label) / add_mapping_edge(source, map_to, ...) edge wiring; edge_from(*sources).to(dest) / .broadcast(...) / .map(...) / .label(...) path builders; build(validate_graph_structure=True) compiles to Graph; start_node/end_node implicit entry/exit nodes), Fork + Join + ReducerContext (Fork with is_map=True fans out Sequence[T] one-element-per-branch vs is_map=False broadcasts same data; Join aggregates parallel results via ReducerFunction[StateT, DepsT, InputT, OutputT] — plain 2-arg or context-aware 3-arg form; ReducerContext.cancel_sibling_tasks() for early-stopping first-match pattern; preferred_parent_fork='farthest'/'closest' for nested fork topology; Join is a MiddleNode and is wired directly via add_edge(source, join) / add_edge(join, dest) — no as_node() needed; join.as_node() produces JoinNode only for legacy BaseNode-based runners), Decision + DecisionBranch + Edge + TypeExpression (Decision.branch(DecisionBranch) immutable builder pattern; DecisionBranch.matches — None → isinstance/Literal dispatch, custom callable predicate; DecisionBranch.source type used for exhaustiveness checking; union-type routing with SuccessResult | ErrorResult; Edge(label=...) frozen annotation for Mermaid edge labels; TypeExpression[T] works around type-checker rejection of Union[...]/Literal[...]/Any in generic type positions), Step + StepContext + StepNode (StepContext[StateT, DepsT, InputT] exposes .state/.deps/.inputs as read-only properties with correct variance; Step[StateT, DepsT, InputT, OutputT] stores id/label/call; Step.as_node(inputs) produces StepNode bridge to v2 graph runner — raises NotImplementedError if run directly; @builder.stream wraps async generators into Step[..., AsyncIterable[T]]; builder.Source[T] / builder.Destination[T] type aliases for IDE-safe step signatures). New guide pydantic_ai_class_deep_dives_v17.md created (sidebar order 43). Index updated with Zero→Hero step 37, Jump-to-topic card, Reference card.

What’s new in v1.107.0 (June 2026, Vol. 16)

v1.107.0 (June 2026, Vol. 16) — Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived spanning the result layer, streaming surface, tool construction internals, three provider implementations, the YAML/JSON spec-loading system, the output validation machinery, and v2 graph execution primitives: AgentRunResult (all six public methods — output, usage(), all_messages(), new_messages(), all_messages_json(), new_messages_json(); output_tool_return_content deep-copy pattern for multi-turn structured-output conversations; _new_message_index slicing), StreamedRunResult + StreamedRunResultSync (the high-level streaming result wrappers returned by run_stream()/run_stream_sync(); stream_output(delta=, debounce_by=) cumulative vs delta mode; stream_text(delta=) plain-text streaming; stream_response() raw model-response parts; get_output() wait-and-cache; usage() / new_messages() / is_complete post-stream access; sync wrapper sync/async method table), Tool direct construction (all 17 constructor parameters: function, takes_ctx, max_retries, name, description, prepare, args_validator, docstring_format, require_parameter_descriptions, schema_generator, strict, sequential, requires_approval, metadata, timeout, defer_loading, include_return_schema; from_function() factory; from_schema() schema-driven tool; function_schema cached property; prepare dynamic tool-definition filtering), GenerateToolJsonSchema + DocstringFormat (schema generation pipeline; four docstring formats 'google'/'numpy'/'sphinx'/'auto'; require_parameter_descriptions=True raises at registration time; custom schema_generator subclass; _named_required_fields_schema title-stripping), MistralModel + MistralModelSettings + MistralStreamedResponse (Mistral AI provider; json_mode_schema_prompt template with {schema} placeholder; PromptedOutput fallback mode for older endpoints; multimodal with pixtral-large-latest; MistralEventStreamAsync streaming internals; FinishReason mapping), OllamaModel (self-hosted Ollama ≥ v0.5.0 enforces json_schema via llama.cpp grammar-constrained decoder — NativeOutput schema-valid at generation time; Ollama Cloud auto-detects via base_url containing 'ollama.com' or model name ending '-cloud' and disables supports_json_schema_output; output mode compatibility table; custom endpoint via OllamaProvider; manual profile override for Cloud migration), OpenRouterModel + OpenRouterModelSettings + OpenRouterModelProfile + OpenRouterReasoning (OpenRouter meta-provider routing to 200+ models; openrouter_models fallback chain; OpenRouterProviderConfig with order/allow_fallbacks/data_collection; OpenRouterReasoning effort vs max_tokens cross-provider thinking tokens; openrouter_usage cost inclusion; OpenRouterModelProfile cache-control capability flags openrouter_supports_cache_control/openrouter_supports_cache_ttl/openrouter_supports_tool_cache/openrouter_supports_dynamic_instruction_cache), NamedSpec + CapabilitySpec + build_registry + load_from_registry (YAML/JSON spec-driven capability composition; three short-form serialisation variants: bare string / single-arg dict / keyword-arg dict; model_validator(mode='wrap') compact-form deserialization; CapabilitySpec tagged subclass enabling JSON schema replacement with full capability union; build_registry(custom_types=, defaults=, get_name=, label=, validate=) name→class map; load_from_registry(registry, spec, legacy_aliases=, instantiate=) instantiation; YAML-driven agent config example), OutputSchema + OutputValidator (OutputSchema abstract base with allows_none/text_processor/toolset/object_def/allows_deferred_tools/allows_image; OutputSchema.build() factory resolving output_type to TextOutputSchema/ToolOutputSchema/NativeOutputSchema/PromptedOutputSchema/ImageOutputSchema/MultiOutputSchema; OutputValidator wraps user validator functions detecting sync/async and takes_ctx; validate() async dispatch via run_in_executor for sync functions; union output types and MultiOutputSchema), GraphRun + NodeStep (v2 graph execution primitives from pydantic_ai.run; GraphRun execution state manager with _active_reducers fork/join coordination; _next as EndMarker | ErrorMarker | Sequence[GraphTask]; _first_task seeding; NodeStep bridging v1 BaseNode classes into v2 — node_type validation + GraphRunContext provision; JoinItem partial results from parallel branches; GraphTaskRequest fork-stack context; agent.iter() as the public node-by-node API). New guide pydantic_ai_class_deep_dives_v16.md created. Index updated with Zero→Hero step 36, Jump-to-topic card, Reference card.

What’s new in v1.107.0 (June 2026, Vol. 15)

v1.107.0 (June 2026, Vol. 15) — Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived spanning toolset composition, open-source model inference, local embeddings, durable execution runtimes, and provider model-profile functions: CombinedToolset (union of multiple toolsets with name-conflict detection; equivalent to Agent(toolsets=[a, b]) but reusable; get_tools fails fast on name collision via tool_name_conflict_hint), HuggingFaceModel + HuggingFaceModelSettings + HuggingFaceStreamedResponse (inference against any HuggingFace Hub model — DeepSeek-R1, Llama-4, Qwen3; InferenceClient / AsyncInferenceClient; HuggingFaceModelSettings inherits OpenAIModelSettings; HuggingFaceStreamedResponse for token-level streaming), TestEmbeddingModel (deterministic mock embeddings for unit tests; fixed dimension/value output; embedding_model fixture pattern), SentenceTransformerEmbeddingModel + SentenceTransformersEmbeddingSettings (on-device embeddings via sentence-transformers; all SentenceTransformerEmbeddingSettings fields — batch_size/normalize_embeddings/device/show_progress_bar; privacy-preserving local RAG pipeline), TemporalRunContext + deserialize_run_context (serializable RunContext subclass crossing Temporal activity boundaries; JSON-serialisable .model_dump(); deserialize_run_context(data, deps_type) reconstruction; Temporal activity pattern), PydanticAIWorkflow (Temporal Workflow base class; __pydantic_ai_agents__ class-level agent registration; activity_executor thread-pool injection; workflow.run() signal/query pattern), TemporalDynamicToolset (wraps DynamicToolset factory so it runs inside a Temporal activity; toolset_factory callable; workflow-level tool registration), PrefectAgentInputs + DEFAULT_PYDANTIC_AI_CACHE_POLICY (Prefect CachePolicy strips non-deterministic RunContext fields before hashing; PrefectAgentInputs dataclass; DEFAULT_PYDANTIC_AI_CACHE_POLICY constant; @task(cache_policy=DEFAULT_PYDANTIC_AI_CACHE_POLICY) decorator), ACIToolset + tool_from_aci (deprecated ACI.dev integration bridge; tool_from_aci(aci_tool) → Tool.from_schema() migration path; deprecation warning at import), provider model-profile function family (GrokModelProfile for xAI Grok; GroqModelProfile for Groq Cloud; deepseek_model_profile/qwen_model_profile/cohere_model_profile/moonshotai_model_profile factory functions; profile composition with from_profile() merge). New guide pydantic_ai_class_deep_dives_v15.md created (sidebar order 41). Index updated with Zero→Hero step 35, Jump-to-topic card, Reference card.

What’s new in v1.107.0 (June 2026, Vol. 14)

v1.107.0 (June 2026, Vol. 14) — Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived from the UI protocol layer, provider abstraction, model profile system, and extended embeddings ecosystem: UIAdapter + UIEventStream + StateDeps + StateHandler + OnCompleteFunc (the new unified UI adapter ABC that backs AGUIAdapter and VercelAIAdapter; dispatch_request()/from_request()/run_stream() lifecycle; manage_system_prompt='server'/'client' system-prompt security; allowed_file_url_schemes SSRF guard; preserve_file_data for uploaded-file round-trip fidelity; StateDeps protocol for per-request frontend state injection; OnCompleteFunc callback after successful run), AGUIAdapter updated (ag_ui_version thresholds — < 0.1.13 emits THINKING_*, ≥ 0.1.13 emits REASONING_* with encrypted provider metadata, ≥ 0.1.15 emits typed multimodal input content; dispatch_request() replacing deprecated handle_ag_ui_request; preserve_file_data AG-UI activity round-trip; full migration guide from AGUIApp), VercelAIAdapter updated (sdk_version=6 enables tool-approval streaming for HITL workflows; server_message_id in StartChunk; dispatch_request() pattern), Provider abstract base class + infer_provider/infer_provider_class (Provider[InterfaceClient] abstract class; name/base_url/client abstract properties; model_profile() static method; async context manager lifecycle with _entered_count/_enter_lock; complete provider string table; custom provider authoring pattern), ModelProfile complete field reference (all 17 fields including new: supports_tool_return_schema, supports_json_schema_output, supports_json_object_output, supports_image_output, supports_inline_system_prompts, supports_thinking, thinking_always_enabled, thinking_tags, ignore_streamed_leading_whitespace, supported_native_tools; StructuredOutputMode enum; from_profile()/update() merge methods; deprecated supported_builtin_tools alias), AnthropicModelProfile + OpenAIModelProfile (provider-specific profile extensions with anthropic_*/openai_* prefixed fields; anthropic_supports_adaptive_thinking / anthropic_supports_effort / anthropic_supports_xhigh_effort / anthropic_disallows_budget_thinking / anthropic_disallows_sampling_settings; openai_chat_thinking_field / openai_chat_send_back_thinking_parts; custom vLLM provider example), WrapperEmbeddingModel + InstrumentedEmbeddingModel (WrapperEmbeddingModel delegate base for caching/logging/rate-limiting wrappers; infer_embedding_model() string factory; InstrumentedEmbeddingModel wraps any embedding model with OTel spans carrying inputs_count/input_type/token usage/cost; wrapper composition pattern), additional embedding providers (GoogleEmbeddingModel — Gemini API + Vertex AI; BedrockEmbeddingModel — Amazon Titan + Cohere on Bedrock; CohereEmbeddingModel; VoyageAIEmbeddingModel with code/domain specialisation; provider comparison table; RAG pipeline with EmbeddingResult.cost()), BuilderCheckpoint + MessagesBuilder advanced patterns (MessagesBuilder.add() auto-coalescing; checkpoint()/last_modified() attribution for custom UIEventStream implementations; handling both “new message created” and “existing message extended” cases), OutlinesModel deprecated (constrained text generation with grammar rules at token level; from_transformers/from_llamacpp/from_sglang/from_mlxlm/from_vllm_offline factory methods; deprecation reasoning; migration table to NativeOutput/PromptedOutput/vLLM structured-output API). New guide pydantic_ai_class_deep_dives_v14.md created. Index updated with Zero→Hero step 34, Jump-to-topic card, Reference card, and version bumped to v1.107.0 (Vol. 14).

What’s new in v1.107.0 (June 2026, Vol. 13)

v1.107.0 (June 2026, Vol. 13) — Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived from the capabilities subsystem and native-tool layer: Capability convenience class (@cap.tool/@cap.tool_plain/@cap.instructions decorators; inline capability authoring without subclassing AbstractCapability; defer_loading=True for lazy tool registration; callable description for dynamic catalog routing; role-scoped capability bundles; shared single instance across agent calls), MCP capability (native=True explicit flag; native-only MCP server with URL config; local-only MCPToolset with OAuth bearer auth; defer_loading for capability-catalog lazy fetch; full migration table from deprecated MCPToolset direct usage), WebSearch capability (all search_context_size options; WebSearchUserLocation TypedDict with city/country/region/timezone; allowed_domains/blocked_domains mutual-exclusion guard; forcing DuckDuckGo local fallback with fallback_model=False; custom async local search function), WebFetch capability (citations mode; intranet allow-list bypassing SSRF blocklist; forcing local fallback with native=False; combined with WebSearch for research agents; headers for custom proxy auth), XSearch capability (xAI native path vs non-xAI fallback_model subagent path; from_date/to_date date range filtering; allowed_x_handles/excluded_x_handles max-10 lists; enable_image_understanding/enable_video_understanding multimodal flags), Instrumentation capability (Logfire auto-configuration via configure_default_logfire(); privacy='auto' vs 'hide' for PII scrubbing; OTel v2 InstrumentationSettings; from_spec() for YAML/JSON config; custom span attribute injection via wrap_model_request hook), HandleDeferredToolCalls (approve_all() convenience; selective approval by risk tag in tool metadata; two-handler chain with different approval logic; async webhook-based HITL approval pipeline), ProcessEventStream (observer form async def → None for logging/metrics; latency observer measuring model response time; ThinkingPart strip processor as async generator; audit event injector; combined observer + processor on same stream), WebFetchTool + XSearchTool + ImageGenerationTool native tool dataclasses (all constructor fields with types; provider matrix table for each; deprecated UrlContextTool alias for WebFetchTool; wrapping with NativeTool capability), ToolSearch capability (default strategy=None; 'keywords' BM25-light; 'bm25' full BM25; 'regex' pattern; custom callable strategy; max_results tuning; combined with defer_loading=True Capability for agent-wide lazy tool catalog). New guide pydantic_ai_class_deep_dives_v13.md created. Index updated with Zero→Hero step 33, Jump-to-topic card, Reference card, and version bumped to v1.107.0.

What’s new in v1.106.0 (June 2026, Vol. 12)

v1.106.0 (June 2026, Vol. 12) — Library installed (1.106.0) and pydantic-evals (1.106.0) source inspected directly. Ten new class groups deep-dived: Dataset + Case (pydantic_evals YAML/JSON evaluation dataset management; add_case/add_evaluator imperatively build datasets; repeat for stability/variance testing; retry_task/retry_evaluators with RetryConfig; from_file/to_file/from_text round-trip; EvaluationReport.print() rich table output), Evaluator + EvaluatorContext + EvaluationResult + EvaluationReason + EvaluatorOutput (abstract evaluator base; all five output forms — bool/int/float/str/EvaluationReason/Mapping; sync and async evaluate dispatch; get_default_evaluation_name() column rename; get_evaluator_version() for dashboard filtering; EvaluationResult.downcast(bool) type-safe inspection), six built-in evaluators Equals/EqualsExpected/Contains/IsInstance/MaxDuration/HasMatchingSpan (complete parameter reference: case_sensitive/as_strings for Contains; timedelta for MaxDuration; SpanQuery typed dict in HasMatchingSpan; combining multiple evaluators per dataset), LLMJudge + GradingOutput + four judge functions (judge_output/judge_input_output/judge_output_expected/judge_input_output_expected; set_default_judge_model; OutputConfig evaluation_name/include_reason; score=False/assertion=False to suppress; include_input=True/include_expected_output=True; full pipeline with TestModel), generate_dataset (LLM-driven test case generation; dataset_type generic param for full schema inference; custom_evaluator_types surfaces custom evaluators to LLM; n_examples; extra_instructions; save + cache guard pattern), online evaluation evaluate decorator + OnlineEvalConfig + OnlineEvaluator (sample_rate float or callable; sampling_mode 'independent'/'correlated'; max_concurrency semaphore; disable_evaluation() context manager for tests; wait_for_evaluations(timeout=) flush; custom EvaluationSink.submit; on_max_concurrency/on_sampling_error/on_error hooks; emit_otel_events=False for test environments; global configure()), SpanTree + SpanNode + SpanQuery (structural OTel span inspection; all 30+ SpanQuery fields with AND logic; any/all/find/find_all; SpanNode.duration/children/parent/attributes; composite queries with and_/or_/not_; stop_recursing_when; increment_eval_metric(name, delta) + set_eval_attribute(key, value) to inject context from inside the task), MCPSamplingModel + MCPSamplingModelSettings (routes LLM calls through the MCP ServerSession.create_message(); default_max_tokens=16_384 fallback for required MCP field; mcp_model_preferences: ModelPreferences with intelligencePriority/speedPriority/costPriority; streaming raises NotImplementedError; MCP server tool example), RetryConfig + TenacityTransport + AsyncTenacityTransport + wait_retry_after (all 10 RetryConfig TypedDict fields mapping to tenacity @retry kwargs; validate_response callable converts 4xx/5xx to exceptions; Retry-After header parsed as both seconds integer and RFC 2822 date; max_wait cap; fallback_strategy; attaching AsyncTenacityTransport to OpenAIProvider(http_client=) for provider-level retry; before_sleep logging), ExternalToolset (registers ToolDefinitions with kind='external'; call_tool raises NotImplementedError; full HITL approval queue with DeferredToolResults.from_tool_call_parts; comparison table vs ApprovalRequiredToolset; id param for durable execution tracking; mixing ExternalToolset with FunctionToolset at run time; deprecated DeferredToolset alias note). New guide pydantic_ai_class_deep_dives_v12.md created. Index updated with Zero→Hero step 32, Jump-to-topic card, and Reference card.
v1.106.0 (June 2026, Vol. 11) — Library installed (1.106.0) and source inspected directly. Ten new class groups deep-dived: UserPromptNode + ModelRequestNode + CallToolsNode (the three internal agent graph nodes promoted to pydantic_ai.__all__ as a stable public API; run state machine diagram; UserPromptNode.deferred_tool_results for HITL resume; ModelRequestNode.last_request_context for post-run inspection; CallToolsNode.tool_call_results for pre-resolved deferred calls; CallToolsNode.user_prompt for attaching human context alongside approvals), AgentCapability + AgentToolset + ToolsetFunc (three new type aliases; AgentCapability = AbstractCapability | Callable[[RunContext], AbstractCapability | None]; AgentToolset = AbstractToolset | ToolsetFunc; ToolsetFunc = Callable[[RunContext], AbstractToolset | None]; per-run feature-flag pattern), AgentModelSettings + AgentNativeTool (AgentModelSettings = ModelSettings | Callable[[RunContext], ModelSettings] enables adaptive temperature/tokens; AgentNativeTool = AbstractNativeTool | Callable[[RunContext], AbstractNativeTool | None] for conditional native tool injection), HandleResponseEvent + ModelResponseStreamEvent (two new Annotated discriminated union aliases; HandleResponseEvent covers FunctionToolCallEvent | FunctionToolResultEvent | OutputToolCallEvent | OutputToolResultEvent | BuiltinToolCallEvent | BuiltinToolResultEvent for CallToolsNode.stream() consumption; ModelResponseStreamEvent covers PartStartEvent | PartDeltaEvent | PartEndEvent | FinalResultEvent for model streaming; both use Discriminator('event_kind'); typed TypeAdapter round-trip examples), ToolSearchCallPart + NativeToolSearchCallPart + ToolSearchArgs + ToolSearchMatch (two-path tool search call infrastructure; local fallback uses ToolSearchCallPart(tool_name='search_tools', tool_kind='tool-search'); native server-side uses NativeToolSearchCallPart(tool_name='tool_search', tool_kind='tool-search'); cross-path detection via part.tool_kind == 'tool-search'; ToolSearchArgs.queries normalized across providers; ToolSearchMatch.name/description), ToolSearchReturnPart + NativeToolSearchReturnPart + ToolSearchReturnContent (return counterparts; ToolSearchReturnContent.discovered_tools: list[ToolSearchMatch]; message for empty results; history analysis and empty-search detection examples), LoadCapabilityCallPart + LoadCapabilityReturnPart (ToolCallPart subclass for the load_capability hidden tool; capability_id property; LoadCapabilityReturnPart.instructions property; deferred capability loading trace pattern), BuiltinToolCallEvent + BuiltinToolResultEvent deprecated migration (both deprecated in 1.106.0; full before/after code examples; migration table; dual-version compatibility wrapper), AgentInstructions + AgentMetadata (AgentInstructions full union: TemplateStr | str | Callable[[RunContext], str | None] | zero-arg Callable | Sequence[...]; instructions vs system_prompt comparison table — InstructionPart vs SystemPromptPart, Anthropic cache semantics, per-run override; AgentMetadata = dict | Callable[[RunContext], dict]; metadata never sent to LLM; OTel billing pattern), Agent 1.106.0 constructor reference (tool_timeout: float | None global tool timeout; max_concurrency: AnyConcurrencyLimit with shared limiter pattern; callable model_settings; capabilities sequence; description: TemplateStr | str | None for OTel span; full agent.run() signature). New guide pydantic_ai_class_deep_dives_v11.md created. Index updated with Zero→Hero step 31, Jump-to-topic card, and Reference card.
v1.105.0 (June 2026, Vol. 10) — Library installed (1.105.0) and source inspected directly. Ten new class groups deep-dived: AgentStream (the streaming context manager returned by run_stream(); stream_output/stream_response/stream_text with delta and debounce_by; cancel()/drain(); validate_response_output(allow_partial=); get_output(); response snapshot; run_id/conversation_id/metadata/cancelled/usage properties), WrapperCapability (transparent capability middleware; __post_init__ inherits id/defer_loading from wrapped capability; apply() visitor propagation for leaf+container wrapping; observer pattern with anyio.create_memory_object_stream tee; full delegation of all 40+ hooks), FunctionToolset (all 14+ constructor params — max_retries, timeout, docstring_format, require_parameter_descriptions, schema_generator, strict, sequential, requires_approval, metadata, defer_loading, include_return_schema, id, instructions; per-tool override via decorator kwargs; add_function/add_tool/@tool/@tool_plain four registration forms; instructions as string/callable/sequence for toolset-level system prompt), AbstractToolset (the ABC all toolsets implement; for_run/for_run_step lifecycle hooks; __aenter__/__aexit__ context manager; get_instructions returning str/InstructionPart/None; abstract get_tools/call_tool; stateful per-run isolation with for_run → fresh instance pattern), ToolCallEvent + ToolResultEvent + FunctionToolCallEvent + FunctionToolResultEvent + OutputToolCallEvent + OutputToolResultEvent (complete 6-node tool event taxonomy; ToolCallEvent.args_valid True/False/None; FunctionToolResultEvent.content for attached user content; OutputToolCallEvent/OutputToolResultEvent for model final-answer submission; discriminator event_kind literal values; match/isinstance patterns), FinalResult + FinalResultEvent (FinalResult[OutputDataT] stores output/tool_name/tool_call_id; FinalResultEvent is the AgentStreamEvent signalling schema match before validation; distinguishing text vs tool output; early-exit streaming pattern), UserError + UsageLimitExceeded + ConcurrencyLimitExceeded + UndrainedPendingMessagesError + HookTimeoutError (full exception hierarchy completing the error taxonomy; UserError.message; UsageLimitExceeded with capture_run_messages; ConcurrencyLimitExceeded with max_queued backpressure; UndrainedPendingMessagesError — bare async for vs agent.run()/AgentRun.next(); HookTimeoutError.hook_name/func_name/timeout), multimodal type system (AudioMediaType/ImageMediaType/DocumentMediaType/VideoMediaType MIME type aliases; AudioFormat/ImageFormat/DocumentFormat/VideoFormat shorthand literals; ForceDownloadMode False/True/'allow-local' SSRF levels; ProviderDetailsDelta static dict/callable/None; custom MimeTypes registry with YAML/TOML/WebP/audio/video additions), AbstractCapability extended (defer_loading=True with lazy load_capability catalog; get_description() static and async for catalog routing; get_ordering() returning CapabilityOrdering; wrap_run/wrap_node_run/wrap_model_request/wrap_tool_validate/wrap_tool_execute/wrap_output_validate/wrap_output_process zero-argument handler pattern; WrapRunHandler/WrapNodeRunHandler/WrapModelRequestHandler/WrapToolValidateHandler/WrapToolExecuteHandler/WrapOutputValidateHandler/WrapOutputProcessHandler type reference), CapabilityOrdering + CapabilityPosition + CapabilityRef + CAPABILITY_TYPES (CapabilityOrdering dataclass with position/wraps/wrapped_by/requires; CapabilityPosition 'outermost'/'innermost'; CapabilityRef type-or-instance with issubclass/is matching semantics; CAPABILITY_TYPES registry for YAML/JSON spec loading; CycleError and missing-requirement detection; has_capability_type() utility). New guide pydantic_ai_class_deep_dives_v10.md created. Index updated with Zero→Hero step 30, Jump-to-topic card, and Reference card.
v1.105.0 (June 2026, Vol. 9) — Library installed (1.105.0) and source inspected directly. Ten new class groups deep-dived: ModelRequest + ModelResponse (wire-format anatomy; FinishReason/ModelResponseState type aliases; run_id/conversation_id threading; metadata never sent to LLM; ModelMessagesTypeAdapter round-trip), SystemPromptPart + UserPromptPart + RetryPromptPart (three request-side parts; multi-modal UserContent sequence; dynamic_ref for OTel attribution; RetryPromptPart.model_response() formats validation errors; CachePoint in user content), BaseToolCallPart + ToolCallPart + NativeToolCallPart (call-part family; args_as_dict(raise_if_invalid=) graceful/strict JSON; narrow_type() typed subclass promotion; ToolCallPartDelta streaming accumulation), BaseToolReturnPart + ToolReturnPart + NativeToolReturnPart (return-part family; outcome success/failed/denied; content_items(mode=) raw/str/jsonable; files property for multi-modal extraction; model_response_str_and_user_content() for text-only providers; provider_details round-trip), GraphAgentState (run-state dataclass; message_history/usage/run_id/conversation_id/pending_messages; check_incomplete_tool_call(); consume_output_retry() budget enforcement), MCPServerTool (native MCP server integration; OpenAI/Anthropic/xAI provider matrix; allowed_tools restriction; headers enterprise auth; OpenAI x-openai-connector: prefix; vs MCPToolset comparison table), FileSearchTool (provider-managed RAG; OpenAI vector stores/Gemini Files API/xAI collections; file_store_ids parameter; zero-code chunking + embedding; vs custom RAG comparison table), IncludeReturnSchemasToolset (auto include_return_schema=True injection; PreparedToolset subclass; FilteredToolset composition for RBAC; when-to-use guide), ToolChoice + ToolOrOutput (ToolChoiceScalar/list[str]/ToolOrOutput/None semantics; ToolOrOutput.function_tools restricts function tools while preserving output/text; capability hook pattern; dynamic callable form), ServiceTier + ThinkingLevel/ThinkingEffort (unified cross-provider billing tier mapping table; 5-level ThinkingEffort with provider-specific fallbacks; adaptive effort selection; combined cost management example). New guide pydantic_ai_class_deep_dives_v9.md created. Index updated with Zero→Hero step 29, Jump-to-topic card, and Reference card.
v1.105.0 (June 2026, Vol. 8) — Patch release. Library installed (1.105.0) and source inspected directly. Ten new class groups deep-dived: ToolOutput + NativeOutput + PromptedOutput + TextOutput + StructuredDict (four output-mode marker classes; per-output-type mode control; ToolOutput.max_retries per-output override; NativeOutput.template=False; PromptedOutput for provider compatibility; TextOutput post-processing functions; StructuredDict $defs auto-inlining), ApprovalRequiredToolset (HITL toolset wrapper; conditional filter function; argument-based approval logic; tool_call_approved resume), DeferredLoadingToolset (lazy tool discovery; tool_names=None vs partial deferral; ToolSearch capability pairing; composition with FilteredToolset), Embedder + EmbeddingModel + EmbeddingResult + EmbeddingSettings (complete embeddings API; query vs document input types; EmbeddingResult.__getitem__ lookup; EmbeddingResult.cost() via genai-prices; EmbeddingSettings.dimensions cross-provider truncation; TestEmbeddingModel for tests; RAG pipeline example), web_fetch_tool + WebFetchLocalTool (HTML→markdown via markdownify; Accept: text/markdown preference; BinaryContent fallback; max_content_length truncation; domain allow/block lists; custom headers), PrefectAgent + TaskConfig (Prefect durable execution; name requirement; TaskConfig TypedDict: retries/retry_delay_seconds/timeout/cache_policy/persist_result; per-tool override; DEFAULT_PYDANTIC_AI_CACHE_POLICY), ImageGenerationSubagentTool + image_generation_tool (dedicated subagent with separate model; ImageGenerationFallbackModelFunc per-run model selection; _check_image_only_model guard for image-only models), ConcurrencyLimitedModel + AbstractConcurrencyLimiter (per-model HTTP request gating; shared limiter pattern; ConcurrencyLimit.max_queued backpressure; AbstractConcurrencyLimiter ABC for Redis-backed distributed limiting), InstructionPart + AgentInstructions (runtime instruction dataclass; dynamic: bool Anthropic prompt-caching driver; InstructionPart.sorted() for stable cache prefixes; InstructionPart.join(); AgentInstructions type alias covering all four accepted forms), StructuredDict + OutputObjectDefinition (deep dive: json_schema/name/description/strict record; all four marker-class outputs; using in output hooks to inspect active schema). New guide pydantic_ai_class_deep_dives_v8.md created. Index updated with Zero→Hero step 28, Jump-to-topic card, and Reference card. 156 top-level exports confirmed; API surface unchanged from 1.104.0.
v1.104.0 (May 2026, Vol. 6) — Library installed (1.104.0) and source inspected directly. Ten new class groups deep-dived: ToolReturn (structured tool return separating return_value/content/metadata; parameterised generic for return schema generation; metadata never sent to LLM), TextContent (tagged string content with app-only metadata; valid UserContent item; use for RAG passage annotation and UI render hints), FilePart + BinaryImage (FilePart model-response part with id/provider_name/provider_details round-trip fields; BinaryImage validates is_image; base64 JSON serialisation via Pydantic config), Direct API — model_request/model_request_sync/model_request_stream/model_request_stream_sync (four raw-model-call functions; _ensure_instruction_parts bridge; optional ModelRequestParameters and ModelSettings; StreamedResponseSync via background threading.Thread), ModelRequestParameters (wire-format dataclass: function_tools, native_tools, output_mode/output_object/output_tools, prompted_output_template, allow_text_output, allow_image_output, instruction_parts static/dynamic split, thinking; tool_defs cached property; with_default_output_mode atomic resolver), error hierarchy — AgentRunError → ModelAPIError (adds model_name) → ModelHTTPError (adds status_code/body); UnexpectedModelBehavior → ContentFilterError (empty response from content filter) + IncompleteToolCall (truncated mid-stream tool call); production retry pattern, ToolApproved + ToolDenied (HITL approval result pair; ToolApproved.override_args replaces model args; ToolDenied.message returned to model; full ApprovalRequiredToolset pattern), JsonSchemaTransformer + InlineDefsJsonSchemaTransformer (abstract base for schema walk; transform() node callback; prefer_inlined_defs/strict/is_strict_compatible; custom transformer examples; InlineDefsJsonSchemaTransformer inlines all $ref with no-op transform), TemporalAgent (durable Temporal execution; wraps any Agent; activity_config + model_activity_config + toolset_activity_config + tool_activity_config hierarchy; tool_activity_config=False for pure-CPU tools; custom TemporalRunContext subclass; multi-model registration; PydanticAIWorkflow base class), ToolsetTool (internal toolset tool wrapper; toolset/tool_def/max_retries/args_validator/args_validator_func fields; returned from AbstractToolset.get_tools; custom args_validator_func pattern for semantic validation). New guide pydantic_ai_class_deep_dives_v6.md created. Index updated with Zero→Hero step 26, Jump-to-topic card, and Reference card.
v1.104.0 (May 2026, Vol. 5) — Library installed (1.104.0) and source inspected directly. Ten new class groups deep-dived: PendingMessage + RunContext.enqueue/AgentRun.enqueue (mid-run message injection with 'asap'/'when_idle' priorities; PendingMessageDrainCapability auto-drain), AgentWorker + agent_to_a2a (A2A protocol bridge; deprecated in 1.104.0 — migrate to fasta2a[pydantic-ai]>=0.6.1), WrapperAgent (transparent delegation base for agent middleware), safe_download + SSRF protection (ResolvedUrl; 20+ CIDR ranges; cloud metadata blocklist for 9 endpoints; IPv6 transition form decoding; per-hop redirect validation with sensitive header stripping), DBOSAgent (durable DBOS workflow wrapper; model_step_config, mcp_step_config, automatic MCPToolset/FastMCPToolset wrapping), StreamedResponseSync (sync streaming via background threading.Thread + queue.Queue; response/model_name/timestamp properties; 30s init timeout), ModelResponsePartsManager (_parts/_vendor_id_to_part_index/_tool_kind_by_name; handle_text_delta/handle_tool_call_delta/handle_tool_call_part; tool kind narrowing at first event; embedded <think> tag handling), CombinedCapability (auto-flattening; CapabilityOrdering-based sort; forward before_* / reverse after_* hook chain; dynamic ModelSettings merging with ctx.model_settings accumulation; first-come-first-served deferred tool handling), FastMCPToolset (deprecated; reference-counted AsyncExitStack + anyio.Lock; structured content unwrapping; full migration table to MCPToolset), SetToolMetadata (Code Mode + arbitrary metadata injection via ToolSelector — 'all', exact name, list, or async callable). New guide pydantic_ai_class_deep_dives_v5.md created. Index updated with Zero→Hero step 25, Jump-to-topic card, and Reference card.
v1.104.0 (May 2026, Vol. 4) — Library installed (1.104.0) and source inspected directly. Ten new class groups deep-dived: LangChainTool + LangChainToolset + tool_from_langchain (bridge any LangChain BaseTool into Pydantic AI via structural Protocol; tool_from_langchain proxy handles defaults, JSON Schema, required params), VercelAIAdapter (Vercel AI SDK v5/v6; sdk_version=6 enables tool-approval streaming HITL; deferred_tool_results parsed from approval messages; manage_system_prompt server/client mode; allowed_file_url_schemes SSRF guard), ToolManager + ValidatedToolCall (parallel_execution_mode context var with 'parallel'/'sequential'/'parallel_ordered_events'; for_run_step retry carry-over; ValidatedToolCall.args_valid separates validation from execution), ThreadExecutor (bounded ThreadPoolExecutor/ProcessPoolExecutor scoped to agent run; Agent.using_thread_executor() global alternative), PrefixTools (WrapperCapability that prefixes all wrapped-capability tool names; from_spec config deserialization; two-server namespace example), PrepareTools + PrepareOutputTools (ToolsPrepareFunc wrapped as capability; RBAC filtering; dynamic description injection; output-tool step gating), ImageGeneration (all constructor params; provider-specific setting table; action='edit'/background='transparent'; fallback_model subagent; _image_gen_kwargs override pattern), XSearch (allowed_x_handles/excluded_x_handles max-10 lists; from_date/to_date; enable_image_understanding/enable_video_understanding; no default fallback model; Grok native vs. non-xAI subagent patterns), duckduckgo_search_tool + tavily_search_tool + ExaToolset (all three third-party search factories; DuckDuckGoResult/TavilySearchResult/ExaSearchResult/ExaAnswerResult TypedDicts; ExaToolset shared client with four tools; search_type options), FunctionSignature + TypeSignature (Code Mode AST; SimpleTypeExpr/LiteralTypeExpr/GenericTypeExpr/UnionTypeExpr tree; render() with conflicting_type_names; from_schema builder; FunctionParam/TypeFieldSignature direct construction; get_conflicting_type_names dedup). New guide pydantic_ai_class_deep_dives_v4.md created. Index updated with Zero→Hero step 24, Jump-to-topic card, Reference card, version bumped to v1.104.0, and revision history entry. All core guide symbols verified with -W error::DeprecationWarning against installed pydantic-ai==1.104.0; all PASS. 178 top-level exports confirmed; API surface unchanged from 1.103.0.
v1.103.0 (May 2026, Vol. 3) — Third source-verified deep-dive batch against installed 1.103.0. Ten new class families: MCPToolset + load_mcp_toolsets (the recommended MCP server toolset; replaces deprecated MCPServer*; FastMCP-backed, all transports, OAuth, caching, process_tool_call hook, JSON config), UIAdapter + MessagesBuilder + UIEventStream (frontend UI adapter base; manage_system_prompt, allowed_file_url_schemes SSRF guard, checkpoint/last_modified), CachePoint + CompactionPart (cache boundaries with '5m'/'1h' TTL; provider compaction round-tripping), format_as_xml (Python→XML for LLMs; all parameters including include_field_info='once'), BinaryContent + FileUrl family (ImageUrl/AudioUrl/VideoUrl/DocumentUrl; force_download SSRF semantics; vendor_metadata by provider; MultiModalContent union), DeferredToolRequests + DeferredToolResults + CallDeferred + ApprovalRequired (full deferred/HITL workflow; build_results, approve_all, remaining, update), NativeTool capability (static + dynamic native tool registration; from_spec), NativeOrLocalTool capability (native/local adaptive pairing; base of WebSearch/WebFetch/ImageGeneration), DynamicCapability (per-run capability factory; async; feature flags; multi-capability combinator), ToolSearch (lazy tool discovery; defer_loading=True; strategy options None/'keywords'/'bm25'/'regex'/callable; max_results; native vs local). New guide pydantic_ai_class_deep_dives_v3.md created. Index updated with Zero→Hero step 23, Jump-to-topic card, Reference card, and revision history entry.
v1.103.0 (May 2026) — Minor release. Maintenance and dependency updates.
v1.102.0 (May 2026, Vol. 2) — Second source-verified deep-dive batch against installed 1.102.0. Ten new classes: FallbackModel + FallbackExceptionGroup (exception/response-handler fallback chains), ModelProfile + ModelProfileSpec + DEFAULT_PROFILE (all 15 capability flags, JSON-schema transformer, factory form), WrapperToolset + RenamedToolset + PrefixedToolset + SetMetadataToolset (full toolset composition family), InstrumentationSettings + InstrumentedModel (OTel versions 1–5, Logfire, aggregated usage, privacy mode), UploadedFile (cross-provider file references, media-type inference, identifier property), TemplateStr (Handlebars system-prompt templating, conditionals/loops, standalone rendering), ProcessHistory + ReinjectSystemPrompt (message-history transformation capabilities, trusted-server pattern), AbstractCapability (custom capability authoring: instructions/toolset/before_model_request/after_model_request), EndStrategy ('early'/'graceful'/'exhaustive') + AgentRetries, ModelRequestContext (mutable per-request context for capability hooks). New guide pydantic_ai_class_deep_dives_v2.md created. Index updated with Zero→Hero step 22, Jump-to-topic, and Reference entries.
v1.102.0 (May 2026) — Library installed (1.102.0) and source inspected directly. Ten classes deep-dived from source code: RunContext (all fields including conversation_id, run_id, tool_call_approved, tool_call_metadata, partial_output, metadata), Hooks (all 33 events + constructor-kwargs pattern), WebSearch (native/local, domain allow/block, location, custom fallback), WebFetch (SSRF guards, citations, content limits, local fallback), Thinking (all effort levels, cross-provider), FilteredToolset (sync + async filters, RBAC, phase-gating), CombinedToolset (merging heterogeneous sources, dynamic per-run), ApprovalRequiredToolset (full HITL workflow with metadata), ExternalToolset (full deferred execution workflow + durable ID), UsageLimits + RunUsage (token budgets, preflight counting, summing across runs, tool-call limits). New guide pydantic_ai_source_code_deep_dive.md created. Index updated with new Zero→Hero step 21 and Reference entry.
v1.101.0 (May 2026) — Minor release. Maintenance and dependency updates. All core guide symbols (Agent, RunContext, ModelRetry, AgentRunResult, StreamedRunResult, UsageLimits, RunUsage, capture_run_messages, limit_model_concurrency, ConcurrencyLimiter) verified with -W error::DeprecationWarning against installed pydantic-ai==1.101.0 (.routine-envs/check-0522-pydantic); all PASS. 178 top-level exports confirmed; API surface unchanged from 1.99.0. Library source inspected directly: ten classes deep-dived (Tool advanced params, ModelSettings complete reference, Hooks capability, Thinking capability, WebSearch capability); builtin_tools.md migrated to capabilities=[NativeTool(...)] API; toolsets guide expanded with three new end-to-end examples.
v1.100.0 (May 21) — New deep-dive guides added: Hooks (Hooks capability with decorator-based run/model/tool/output lifecycle registration), Concurrency Limiting (ConcurrencyLimiter, ConcurrencyLimit, AbstractConcurrencyLimiter, AnyConcurrencyLimit), Embeddings (Embedder, EmbeddingModel, EmbeddingResult, EmbeddingSettings, TestEmbeddingModel). Existing guides enhanced: Toolsets updated with WrapperToolset custom toolset examples, AbstractToolset from-scratch implementation, and SetMetadataToolset + FilteredToolset access-control pattern; Advanced error testing completely rewritten with exception hierarchy, ModelRetry patterns, TestModel/FunctionModel examples, and pytest fixtures; Output types updated with NativeOutput strict-mode and template=False examples; Advanced patterns extended with AgentRun.iter() node-by-node patterns.
v1.99.0 (May 2026) — Minor release. Library source verified against installed package; class deep-dives guide expanded with UsageLimits (§11) and ConcurrencyLimiter (§12) deep-dives including all constructor arguments, runtime properties, and multi-agent sharing patterns. pydantic_ai_advanced_error_testing.md rewritten with comprehensive coverage of ModelRetry, UnexpectedModelBehavior, UsageLimitExceeded, ConcurrencyLimitExceeded, UserError, and testing error paths via FunctionModel/capture_run_messages. pydantic_ai_streaming_server_fastapi.md rewritten using the actual pydantic-ai streaming APIs (run_stream, run_stream_events, AG UI adapter). All Verified against headers across all deep-dive pages updated to 1.99.0. All core guide symbols verified against installed pydantic-ai==1.99.0 (.routine-envs/check-0520-pydantic); no DeprecationWarning emissions on any non-ag_ui imports.
v1.98.0 (May 2026) — Minor release. pydantic_ai.ag_ui module deprecated — emits PydanticAIDeprecationWarning on import. Replace from pydantic_ai.ag_ui import AGUIAdapter with from pydantic_ai.ui.ag_ui import AGUIAdapter; SSE_CONTENT_TYPE and StateDeps move to from pydantic_ai.ui import .... AGUIApp remains available from pydantic_ai.ag_ui until 2.0 but should not be used in new code. New pydantic_ai.common_tools module with provider-specific tool collections (DuckDuckGo, Exa, Tavily, WebFetch, ImageGeneration); each collection requires the matching optional extra (e.g. pip install "pydantic-ai[duckduckgo]"). All core guide symbols verified against installed pydantic-ai==1.98.0 (.routine-envs/check-0519-py); no DeprecationWarning emissions on imports.
v1.97.0 (May 2026) — Minor release; maintenance and dependency updates.
v1.96.0 (May 14) — Minor release. New concurrency management API: ConcurrencyLimiter(max_running, max_queued=None) and limit_model_concurrency(model, limiter) — wraps any Model with a concurrency gate to cap parallel model requests. All guide-referenced symbols verified against installed pydantic-ai==1.96.0 (.routine-envs/check-0514-py); no DeprecationWarning emissions.
v1.95.0 (May 13) — Minor release; additional top-level exports confirmed: AgentRunResultEvent, AgentEventStream.
v1.94.0 (May 12) — Minor release; new top-level exports added: AgentRun, AgentRunResult, StreamedRunResultSync (synchronous counterpart to StreamedRunResult for CLI/notebook use). All existing guide symbols confirmed present in installed pydantic-ai==1.94.0 (.routine-envs/check-0512-py); no DeprecationWarning emissions.
v1.93.0 (May 9) — TestModel removed from the pydantic_ai top-level namespace; use from pydantic_ai.models.test import TestModel (guides already use this path). New top-level symbols: AgentSpec, UploadedFile, WebSearchUserLocation, DeferredLoadingToolset.
v1.92.0 (May 7) — Maintenance and dependency updates.
v1.91.0 (May 6) — Maintenance and dependency updates.
v1.90.0 (May 5) — DeferredToolCalls class in pydantic_ai.output marked @deprecated — use DeferredToolRequests (already the recommended API since v1.87.x).
v1.89.1 (May 2) — Patch release; maintenance and dependency updates.
v1.89.0 (May 1) — Patch release; maintenance and dependency updates.
v1.88.0 (April 29) — Patch release; maintenance and dependency updates.
v1.87.0 — Expanded Capabilities API — 9 new capability classes added to pydantic_ai.capabilities: WrapperCapability (base for decorating capabilities), ReinjectSystemPrompt (guards against system prompt being truncated away), ProcessHistory (composable history transformation), ProcessEventStream (custom event handling), HandleDeferredToolCalls (inline deferred tool resolution), IncludeToolReturnSchemas (per-tool return schema injection), PrefixTools (capability-level tool prefixing), PrepareTools (capability-level tool preparation), SetToolMetadata (capability-level metadata tagging). New type aliases: RawToolArgs, ValidatedToolArgs, CapabilityRef, CapabilityPosition, CapabilityOrdering. CAPABILITY_TYPES registry for dynamic capability construction.
Prior (v1.86.x): capabilities parameter on Agent; Hooks with decorator registration; ModelProfile/DEFAULT_PROFILE; pydantic_ai.ui module (UIAdapter, UIEventStream, MessagesBuilder).
Prior (v1.85.x): 8 built-in tools, embeddings API, AG UI adapter, ApprovalRequiredToolset HITL, DeferredLoadingToolset. UrlContextTool deprecated — use WebFetchTool.
Prior (v1.84.x): durable execution, graph support, evals framework, Logfire/OpenTelemetry.

Install, minimal example

from pydantic import BaseModel
from pydantic_ai import Agent

class Answer(BaseModel):
    value: int
    reasoning: str

agent = Agent('openai:gpt-4o', output_type=Answer)

result = agent.run_sync("What is 15 + 27?")
print(result.data)  # Answer(value=42, reasoning='...')

Ready? Start Zero → Hero Step 1 →

Revision history

Date	Framework version (installed)	Summary of changes	Reviewer
2026-06-19	pydantic-ai 1.107.0	Library installed (1.107.0) and source inspected directly. Ten new class groups covering core middleware and security infrastructure: `Hooks` capability (decorator hook registration — `hooks.on.<hook_name>`; 25+ hooks; `tools=` filter; `timeout=` per hook; `HookTimeoutError(TimeoutError)`; `position='middle'`), `Instrumentation` capability (OTel/Logfire — `position='outermost'`; per-run isolation via `dataclasses.replace`; `ToolRetryError`/`ApprovalRequired`/`CallDeferred` span status OK; `from_spec` for YAML config), `ConcurrencyLimiter` + `AbstractConcurrencyLimiter` + `ConcurrencyLimit` (anyio `CapacityLimiter` wrapper — `acquire_nowait()` fast path; OTel span only when waiting; `_queue_lock` atomic `max_queued` enforcement; `ConcurrencyLimitExceeded`; `normalize_to_limiter()`/`get_concurrency_context()` helpers), toolset composition — `CombinedToolset` (flat-merge; `UserError` on name conflict; `_CombinedToolsetTool` source tracking; `apply()`/`visit_and_replace()` visitor), `PrefixedToolset` (`{prefix}_{original}`; `removeprefix` in `call_tool`), `RenamedToolset` (`name_map={new: original}`; pass-through for unmapped), `FilteredToolset` (sync/async `filter_func`), `PreparedToolset` (`prepare_func` — cannot add/rename; warns on `None` return), `ApprovalRequiredToolset` (default all require approval; `not ctx.tool_call_approved and approval_required_func(ctx, tool_def, args)`; raises `ApprovalRequired`) + `ExternalToolset` (`kind='external'`; `call_tool` raises `NotImplementedError`; `TOOL_SCHEMA_VALIDATOR = SchemaValidator(any_schema())`; `DeferredToolset` deprecated alias), `TemplateStr` (Handlebars — `'{{' not in value` fails → fallthrough to `str` in Union; `deps_type` typed compile; untyped + `TypeAdapter.dump_python` at render; `__call__(ctx)` → `render(ctx.deps)`)，`FunctionSchema` (`takes_ctx` auto-detect; `single_arg_name` for model-like args; `return_schema` from annotation; `run_in_executor` for sync; `docstring_format` 4 values; `require_parameter_descriptions`), `safe_download` + `ResolvedUrl` (SSRF — 14 IPv4 + 7 IPv6 private CIDRs; 7 cloud metadata IPv4 + 4 IPv6 always blocked including Azure `168.63.129.16`; IPv6 transition decoding NAT64/6to4/ISATAP/Teredo; trailing-dot strip; sensitive headers stripped cross-origin; per-hop re-validation), `LoadCapabilityCallPart` + `LoadCapabilityReturnPart` + `parse_loaded_capabilities` (deferred capability wire protocol — `tool_kind='capability-load'` discriminator; `DEFERRED_CAPABILITY_TOOL_METADATA_KEY`; `LoadCapabilityArgs` TypedDict `{id}`; `LoadCapabilityReturn` TypedDict `{instructions?}`; `parse_loaded_capabilities()` message walk), `ModelProfile` + `DEFAULT_PROFILE` + `ModelProfileSpec` (14 fields; `from_profile`/`update` merge; lazy deprecated kwarg alias install via `__new__` MRO walk; `supported_builtin_tools`→`supported_native_tools` alias; `DEFAULT_PROFILE = ModelProfile()`; `ModelProfileSpec = ModelProfile \| Callable[[str], ModelProfile \| None]`). New guide `pydantic_ai_class_deep_dives_v20.md` created (sidebar order 46). Index updated with Zero→Hero step 40, Jump-to-topic card, Reference card.	Claude
2026-06-18	pydantic-ai 1.107.0	Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived spanning AWS Bedrock, deprecated Google providers, toolset/capability binding, and `pydantic_graph` persistence primitives: `BedrockConverseModel` + `BedrockModelSettings` + `BedrockStreamedResponse` (first AWS Bedrock coverage; prompt-caching TTL; boto3 sync bridge), `BedrockProvider` + `BedrockModelProfile` + 8 profile factory functions (3 provider construction paths; 10 `bedrock_`-prefixed profile fields; JSON Schema rewriter), `GoogleGLAProvider` + `GoogleVertexProvider` (deprecated — migration tables to `GoogleProvider`/`GoogleCloudProvider`; `_VertexAIAuth` token refresh), `DynamicToolset` (`per_run_step` re-evaluation; transition-safe enter/exit; Temporal `id=`), `CapabilityOwnedToolset` + `resolve_capability_id` + `tool_defs_for_loaded_capabilities` (stamps `capability_id`; deferred-capability metadata key; wire-side filter), Web UI API `create_api_app` + `ModelInfo` + `BuiltinToolInfo` + `ConfigureFrontend` + `ChatRequestExtra` (4 Starlette routes; camelCase aliases; Vercel AI streaming backend), OTel GenAI spec types (9 `TypedDict` types; `UriPart`/`ThinkingPart`; `ToolCallPartOtelMetadata`), `Thinking` capability (`effort: ThinkingLevel = True`; `get_model_settings()` provider override), `ImageGeneration` capability (12 fields; `fallback_model` subagent; `action='edit'`; `background='transparent'`), `pydantic_graph` persistence primitives + exception hierarchy (`NodeSnapshot`/`EndSnapshot`; `SnapshotStatus` lifecycle; `BaseStatePersistence` ABC; 5-class exception hierarchy). New guide `pydantic_ai_class_deep_dives_v19.md` created (sidebar order 45). Index updated with Zero→Hero step 39, Jump-to-topic card, Reference card.	Claude
2026-06-17	pydantic-ai 1.107.0	Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived spanning the provider ecosystem and `pydantic_graph` persistence layer: `AlibabaProvider` (DashScope + `DASHSCOPE_API_KEY`/`ALIBABA_API_KEY`; Qwen omni audio URI encoding), `OVHcloudProvider` (European AI Endpoints + `OVHCLOUD_API_KEY`; 6-family prefix-based profile routing), `HerokuProvider` (Heroku Inference API + `HEROKU_INFERENCE_KEY`/`HEROKU_INFERENCE_URL`), `gateway_provider` (Pydantic AI Gateway — multi-upstream dispatch; route override; region-encoded key auto base-URL inference), `GoogleProvider` + `GoogleCloudProvider` (Gemini API vs Google Cloud/Vertex AI — `GOOGLE_API_KEY` vs ADC), `GoogleModel` + `GoogleModelSettings` (all 9 prefixed settings — `google_cached_content` caveat; `google_safety_settings`; `MediaResolution`; `GoogleCloudServiceTier`), `CohereModel` + `CohereProvider` + `CohereModelSettings` (Command-R family — `CO_API_KEY`; `AsyncClientV2`; thinking content mapping), `XaiProvider` + `XaiModel` (gRPC SDK; `_LazyAsyncClient` per-loop affinity; `GrokModelProfile`/`GrokReasoningEffort`; builtin-tool gate), `FileStatePersistence` (atomic file-lock persistence for `pydantic_graph` — `.pydantic-graph-persistence-lock`; snapshot lifecycle; `iter_from_persistence` resume pattern), `SimpleStatePersistence` + `FullStatePersistence` (in-memory graph persistence — lightweight latest-only vs full history with `dump_json`/`load_json`). New guide `pydantic_ai_class_deep_dives_v18.md` created (sidebar order 44). Index updated with Zero→Hero step 38, Jump-to-topic cards for Vols. 14–18, and Reference card.	Claude
2026-06-16	pydantic-ai 1.107.0	Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived spanning the full provider ecosystem and new `pydantic_graph` builder API: `LiteLLMProvider` (universal proxy routing; 12-family provider-prefix dispatch; `api_base` + placeholder key; `openai_client` pass-through), `AzureProvider` (Express Mode `/v1`-suffix `api_version` suppression; serverless model endpoints; Entra ID via `AsyncAzureOpenAI`; 6 non-OpenAI family profiles; `openai_chat_supports_document_input=False`), `DeepSeekProvider` (`reasoning_content` → `ThinkingPart`; `send_back_thinking_parts='field'`; `thinking_always_enabled` for R1/reasoner; V4 `reasoning_effort`; `tool_choice=required` restriction for reasoning and v4 models), `CerebrasProvider` (`X-Cerebras-3rd-Party-Integration` header; `zai`/`gpt-oss` reasoning with `supports_thinking`; 6 disabled settings; `CEREBRAS_API_KEY`), `GitHubProvider` (`:tag` suffix stripping; 6-family provider routing; `GITHUB_API_KEY`), `FireworksProvider` + `TogetherProvider` + `NebiusProvider` + `SambaNovaProvider` (GPU provider quartet; Fireworks path-prefix stripping; Nebius no-slash → OpenAI fallback + `openai/` → harmony profile; SambaNova `SAMBANOVA_BASE_URL` on-prem support + constructor-time API key validation), `GraphBuilder` (replaces deprecated `BaseNode` pattern; `step()`/`stream()` decorators; `join()`/`decision()` helpers; `add()`/`add_edge()`/`add_mapping_edge()` wiring; `edge_from().to()/.broadcast()/.map()` path builders; `build(validate_graph_structure=)`), `Fork` + `Join` + `ReducerContext` (`is_map` fan-out vs broadcast; plain/context-aware reducer forms; `cancel_sibling_tasks()` early stopping; `preferred_parent_fork` nested topology; `as_node()` wiring bridge), `Decision` + `DecisionBranch` + `Edge` + `TypeExpression` (isinstance/Literal/custom-predicate dispatch; union-type routing exhaustiveness; `Edge(label=)` Mermaid annotations; `TypeExpression[T]` type-checker workaround), `Step` + `StepContext` + `StepNode` (`StepContext.state`/`deps`/`inputs` variance-correct properties; `Step.as_node(inputs)` → `StepNode` v2 bridge; streaming step via `@builder.stream`; `Source[T]`/`Destination[T]` IDE type aliases). New guide `pydantic_ai_class_deep_dives_v17.md` created (sidebar order 43). Index updated with Zero→Hero step 37, Jump-to-topic card, and Reference card.	Claude
2026-06-15	pydantic-ai 1.107.0	Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived spanning the result layer, streaming surface, tool construction internals, three provider implementations (Mistral/Ollama/OpenRouter), the YAML/JSON spec-loading system, output validation machinery, and v2 graph execution primitives: `AgentRunResult` (all methods, `output_tool_return_content` multi-turn pattern), `StreamedRunResult` + `StreamedRunResultSync` (`stream_output`/`stream_text`/`stream_response`/`get_output` + sync wrapper), `Tool` (all 17 constructor params, `from_schema`, `from_function`, `prepare`), `GenerateToolJsonSchema` + `DocstringFormat` (4 docstring formats, `require_parameter_descriptions`, custom `schema_generator`), `MistralModel` + `MistralModelSettings` + `MistralStreamedResponse` (Mistral provider, `json_mode_schema_prompt`, Pixtral multimodal), `OllamaModel` (self-hosted vs Cloud `NativeOutput` auto-disable), `OpenRouterModel` + `OpenRouterModelSettings` + `OpenRouterModelProfile` + `OpenRouterReasoning` (meta-provider — fallback chain, provider routing, cross-provider reasoning tokens), `NamedSpec` + `CapabilitySpec` + `build_registry` + `load_from_registry` (YAML/JSON spec-driven capability composition), `OutputSchema` + `OutputValidator` (`OutputSchema.build()` factory, 5 concrete subclasses, sync/async dispatch), `GraphRun` + `NodeStep` (v2 graph execution — state manager, fork/join, v1 `BaseNode` bridge). New guide `pydantic_ai_class_deep_dives_v16.md` created. Index updated with Zero→Hero step 36, Jump-to-topic card, Reference card.	Claude
2026-06-14	pydantic-ai 1.107.0	Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived spanning toolset composition, open-source model inference, local embeddings, durable execution runtimes, and provider model-profile functions: `CombinedToolset` (multi-toolset union; name-conflict detection via `tool_name_conflict_hint`), `HuggingFaceModel` + `HuggingFaceModelSettings` + `HuggingFaceStreamedResponse` (HuggingFace Hub inference; `InferenceClient` / `AsyncInferenceClient`; DeepSeek-R1/Llama-4/Qwen3), `TestEmbeddingModel` (deterministic mock embeddings for tests), `SentenceTransformerEmbeddingModel` + `SentenceTransformersEmbeddingSettings` (on-device local embeddings; all `batch_size`/`normalize_embeddings`/`device`/`show_progress_bar` fields), `TemporalRunContext` + `deserialize_run_context` (serialisable RunContext for Temporal activities), `PydanticAIWorkflow` (Temporal Workflow base class; `__pydantic_ai_agents__` registration), `TemporalDynamicToolset` (toolset factory inside Temporal activity), `PrefectAgentInputs` + `DEFAULT_PYDANTIC_AI_CACHE_POLICY` (Prefect CachePolicy for PydanticAI tasks), `ACIToolset` + `tool_from_aci` (deprecated ACI.dev bridge; migration to `Tool.from_schema`), provider model-profile family (`GrokModelProfile`/`GroqModelProfile`/`deepseek_model_profile`/`qwen_model_profile`/`cohere_model_profile`/`moonshotai_model_profile`). New guide `pydantic_ai_class_deep_dives_v15.md` created (sidebar order 41). Index updated with Zero→Hero step 35, Jump-to-topic card, and Reference card.	Claude
2026-06-13	pydantic-ai 1.107.0	Library installed (1.107.0) and source inspected directly. Ten new class groups deep-dived from the UI protocol layer, provider abstraction, model profiles, and extended embeddings ecosystem: `UIAdapter` + `UIEventStream` + `StateDeps` + `StateHandler` + `OnCompleteFunc` (unified UI adapter ABC; `dispatch_request`/`from_request`/`run_stream` lifecycle; `manage_system_prompt` security; `allowed_file_url_schemes` SSRF guard; `preserve_file_data`), `AGUIAdapter` updated (`ag_ui_version` version thresholds 0.1.13/0.1.15; REASONING_* events; typed multimodal input; `dispatch_request` replacing deprecated `handle_ag_ui_request`; `AGUIApp` migration), `VercelAIAdapter` updated (`sdk_version=6` HITL approval streaming; `server_message_id`; `dispatch_request` pattern), `Provider` ABC + `infer_provider`/`infer_provider_class` (abstract client base; `model_profile()` static method; async context manager lifecycle; custom provider pattern; all 15+ provider string keys), `ModelProfile` complete field reference (all 17 fields; `StructuredOutputMode`; `from_profile()`/`update()`; deprecated alias), `AnthropicModelProfile` + `OpenAIModelProfile` (provider-specific extensions; adaptive thinking; effort; xhigh_effort; disallows_sampling; `openai_chat_thinking_field`; `openai_chat_send_back_thinking_parts`), `WrapperEmbeddingModel` + `InstrumentedEmbeddingModel` (caching wrapper base; OTel spans with usage + cost; wrapper composition), additional embedding providers (`GoogleEmbeddingModel`/`BedrockEmbeddingModel`/`CohereEmbeddingModel`/`VoyageAIEmbeddingModel`; provider comparison table; RAG with `cost()`), `BuilderCheckpoint` + `MessagesBuilder` advanced patterns (checkpoint/last_modified attribution; custom `UIEventStream` implementation), `OutlinesModel` deprecated (constrained generation; all 5 factory methods; migration table). New guide `pydantic_ai_class_deep_dives_v14.md` created. Index updated with Zero→Hero step 34, Jump-to-topic card, and Reference card.	Claude
2026-06-12	pydantic-ai 1.107.0	Library installed (1.107.0) and source inspected directly. Minor release from 1.106.0. Ten new class groups deep-dived from capabilities subsystem and native-tool layer: `Capability` convenience class (decorator-based toolset authoring; `defer_loading`; callable description; role-scoped caps), `MCP` capability (`native=True`; native-only/local-only; deferred; MCPToolset migration), `WebSearch` capability (`search_context_size`; `WebSearchUserLocation`; domain allow-list; local fallback), `WebFetch` capability (citations; intranet allow-list; force local; custom proxy), `XSearch` capability (xAI native vs non-xAI fallback_model; date range; handle filter; image+video understanding), `Instrumentation` capability (Logfire; privacy mode; OTel v2; `from_spec()`; custom span attributes), `HandleDeferredToolCalls` (`approve_all`; selective by risk; two-handler chain; async webhook), `ProcessEventStream` (observer/processor forms; log/latency/audit/thinking-strip patterns), `WebFetchTool`+`XSearchTool`+`ImageGenerationTool` (all fields; provider matrix; `UrlContextTool` deprecation; `NativeTool` wrapping), `ToolSearch` (all strategies including custom callable; `max_results`; combined with deferred `Capability`). Also added 4 new recipes (11–14) to `pydantic_ai_recipes.md` covering role-scoped `Capability` bundles, `WebSearch`+`WebFetch` research agent, `HandleDeferredToolCalls` HITL with partial approval, and `ProcessEventStream` latency observer + thinking-strip processor. Updated `frameworks.md` — PydanticAI last updated Jun 2026, stars ~8k. New guide `pydantic_ai_class_deep_dives_v13.md` created (1816 lines). Index version bumped to v1.107.0, Zero→Hero step 33 added, Jump-to-topic and Reference cards updated.	Claude
2026-06-05	pydantic-ai 1.106.0	Library installed (1.106.0) and source inspected directly. Minor release from 1.105.0: three agent graph nodes (`UserPromptNode`, `ModelRequestNode`, `CallToolsNode`) promoted to `pydantic_ai.__all__`; five new type aliases (`AgentCapability`, `AgentToolset`, `ToolsetFunc`, `AgentModelSettings`, `AgentNativeTool`) added for dynamic callable dispatch; six new message types for two-path tool search (`ToolSearchCallPart`, `NativeToolSearchCallPart`, `ToolSearchReturnPart`, `NativeToolSearchReturnPart`) and deferred capability loading (`LoadCapabilityCallPart`, `LoadCapabilityReturnPart`); two new data typedicts (`ToolSearchArgs`, `ToolSearchMatch`, `ToolSearchReturnContent`); two discriminated union aliases (`HandleResponseEvent`, `ModelResponseStreamEvent`); `BuiltinToolCallEvent`/`BuiltinToolResultEvent` deprecated; `Agent` gains `tool_timeout`, `max_concurrency`, `description` constructor params; `model_settings` now accepts callables. New guide `pydantic_ai_class_deep_dives_v11.md` created. Index version bumped to v1.106.0, Zero→Hero step 31 added, Jump-to-topic and Reference cards updated.	Claude
2026-06-04	pydantic-ai 1.105.0	Library installed (1.105.0) and source inspected directly. Ten new class groups deep-dived: `AgentStream` (streaming context manager; `stream_output`/`stream_response`/`stream_text`/`cancel`/`drain`/`validate_response_output`/`get_output`; `run_id`/`conversation_id`/`metadata`/`cancelled`/`usage`), `WrapperCapability` (capability middleware; `__post_init__` id/defer_loading inheritance; `apply()` visitor; observer + transformer patterns), `FunctionToolset` (all 14+ constructor params; `@tool`/`@tool_plain`/`add_function`/`add_tool`; `instructions`; `timeout`; `defer_loading`; `include_return_schema`; `requires_approval`; `sequential`; `id` for durable execution), `AbstractToolset` (custom toolset ABC; `for_run`/`for_run_step`; `get_instructions`; `get_tools`/`call_tool`; stateful per-run isolation), `ToolCallEvent` + `ToolResultEvent` + `FunctionToolCallEvent` + `FunctionToolResultEvent` + `OutputToolCallEvent` + `OutputToolResultEvent` (complete 6-node event taxonomy; `args_valid`; `content`; discriminator match), `FinalResult` + `FinalResultEvent` (output markers; `tool_name`/`tool_call_id`; text vs tool output; early-exit streaming), `UserError` + `UsageLimitExceeded` + `ConcurrencyLimitExceeded` + `UndrainedPendingMessagesError` + `HookTimeoutError` (remaining error types; full exception hierarchy), multimodal type system (`AudioMediaType`/`ImageMediaType`/`DocumentMediaType`/`VideoMediaType`; format literals; `ForceDownloadMode`; `ProviderDetailsDelta`; MIME registry), `AbstractCapability` extended (`defer_loading` lazy load catalog; `get_description()`; `get_ordering()`; wrap hooks full reference; `WrapRunHandler` family), `CapabilityOrdering` + `CapabilityPosition` + `CapabilityRef` + `CAPABILITY_TYPES` (topology; `outermost`/`innermost`; type and instance refs; cycle detection; `has_capability_type()`). New guide `pydantic_ai_class_deep_dives_v10.md` created. Index updated with Zero→Hero step 30, Jump-to-topic card, and Reference card.	Claude
2026-06-03	pydantic-ai 1.105.0	Library installed (1.105.0) and source inspected directly. Ten new class groups deep-dived: `ModelRequest` + `ModelResponse` (wire-format anatomy, `FinishReason`/`ModelResponseState` type aliases, `run_id`/`conversation_id` threading, `metadata` never sent to LLM), `SystemPromptPart` + `UserPromptPart` + `RetryPromptPart` (request-side parts, multi-modal `UserContent`, `dynamic_ref`, `RetryPromptPart.model_response()`), `BaseToolCallPart` + `ToolCallPart` + `NativeToolCallPart` (call-part family, `args_as_dict`, `narrow_type()`, streaming delta), `BaseToolReturnPart` + `ToolReturnPart` + `NativeToolReturnPart` (return-part family, `outcome`, `content_items`, `files` property), `GraphAgentState` (run-state internals, `check_incomplete_tool_call`, `consume_output_retry`), `MCPServerTool` (native MCP integration, OpenAI/Anthropic/xAI, `allowed_tools`, connector_id), `FileSearchTool` (native RAG, OpenAI vector stores/Gemini Files API/xAI collections), `IncludeReturnSchemasToolset` (auto return-schema injection), `ToolChoice` + `ToolOrOutput` (tool/output selection control), `ServiceTier` + `ThinkingLevel`/`ThinkingEffort` (cross-provider config aliases). New guide `pydantic_ai_class_deep_dives_v9.md` created. Index updated with Zero→Hero step 29, Jump-to-topic and Reference cards.	Claude
2026-06-02	pydantic-ai 1.105.0	Library installed (1.105.0) and source inspected directly. Patch release from 1.104.0; API surface unchanged (156 top-level exports). Ten new class groups deep-dived: `ToolOutput` + `NativeOutput` + `PromptedOutput` + `TextOutput` + `StructuredDict` (output-mode marker classes; per-output control), `ApprovalRequiredToolset` (HITL toolset wrapper with conditional filter), `DeferredLoadingToolset` (lazy tool discovery; ToolSearch pairing), `Embedder` + `EmbeddingModel` + `EmbeddingResult` + `EmbeddingSettings` (full embeddings API + RAG pipeline), `web_fetch_tool` + `WebFetchLocalTool` (HTML→markdown; BinaryContent fallback; domain allow/block), `PrefectAgent` + `TaskConfig` (Prefect durable execution; TaskConfig TypedDict), `ImageGenerationSubagentTool` (subagent image gen; image-only model guard), `ConcurrencyLimitedModel` + `AbstractConcurrencyLimiter` (per-model HTTP gating; distributed ABC), `InstructionPart` + `AgentInstructions` (dynamic flag for prompt-caching; sorted() for stable cache prefixes), `OutputObjectDefinition` (output hook schema inspection). New guide `pydantic_ai_class_deep_dives_v8.md` incorporated from PR #143. Index updated with Zero→Hero step 28, Jump-to-topic card, and Reference card. Version card bumped to v1.105.0. All core symbols verified with `-W error::DeprecationWarning` against installed `pydantic-ai==1.105.0` (`.routine-envs/py-0602`); 156 exports confirmed — PASS. crewai discrepancy (was 1.6.1 vs claimed 1.14.6) resolved; 1.14.6 now installs correctly.	Claude routine
2026-06-01	pydantic-ai 1.104.0	Library installed (1.104.0) and source inspected directly. Ten new class groups deep-dived: `AgentEventStream` + `AgentRunResultEvent` (event streaming from `run_stream_events()`; full event taxonomy: `PartStartEvent`/`PartDeltaEvent`/`PartEndEvent`/`FunctionToolCallEvent`/`FunctionToolResultEvent`; `async with` required; deprecated standalone iteration), `ThinkingPart` + `ThinkingPartDelta` (extended thinking response parts; `signature`/`id`/`provider_name`/`provider_details` round-trip semantics; `ThinkingPartDelta.apply()`; multi-provider support table), `AudioUrl` + `VideoUrl` + `DocumentUrl` (multimodal URL types; `force_download` SSRF levels; `vendor_metadata` by provider; `is_youtube` + auto mp4 for YouTube; `format` property; MIME inference), `OutputContext` (output hook context dataclass; `mode`/`output_type`/`object_def`/`has_function`/`function_name`/`tool_call`/`tool_def`/`allows_*` fields; `before_output_validate` / `after_output_validate` / `before_output_process` / `after_output_process` hook patterns), `ModelRetry` (retry exception from tools, output validators, and capability hooks; Pydantic serialisation to `{'kind': 'model-retry'}`; `max_retries` interaction; retry in hooks), `RequestUsage` (per-request token tracking; all 8 token fields including audio; `details` for provider extras like reasoning tokens; `__add__` within-response safe; `cache_hit_rate` pattern; differs from `RunUsage` for pricing), `WebSearchTool` + `WebSearchUserLocation` (full parameter reference with provider compatibility matrix; `search_context_size`; domain allow/block with mutual-exclusion note; `WebSearchUserLocation` TypedDict with city/country/region/timezone; `NativeOrLocalTool` fallback pattern), `MemoryTool` (native persistent memory; Anthropic only; `optional=True` for cross-provider agents; `BuiltinToolCallEvent`/`BuiltinToolResultEvent` in stream), `CodeExecutionTool` (native code execution; Anthropic/OpenAI/Google/Bedrock Nova 2.0/xAI; data analysis; `FilePart` file generation; combining with `WebSearchTool`), `AbstractNativeTool` (base dataclass for all native tools; `optional` flag; `NATIVE_TOOL_TYPES` auto-registry via `__init_subclass__`; `unique_id` for multiple instances; custom native tool implementation). New guide `pydantic_ai_class_deep_dives_v7.md` created. Index updated with Zero→Hero step 27, Jump-to-topic card, and Reference card.	Claude
2026-05-31	pydantic-ai 1.104.0	Library installed (1.104.0) and source inspected directly. Ten new class groups deep-dived: `ToolReturn` (structured return + metadata; parameterised generic), `TextContent` (app-only tagged text, never sent to LLM), `FilePart` + `BinaryImage` (model file responses; provider round-trip data; base64 JSON), Direct API — `model_request`/`model_request_sync`/`model_request_stream`/`model_request_stream_sync` (raw model calls; `StreamedResponseSync`), `ModelRequestParameters` (full wire-format reference; `tool_defs`; `with_default_output_mode`), error hierarchy — `ModelAPIError`/`ModelHTTPError`/`ContentFilterError`/`IncompleteToolCall`, `ToolApproved` + `ToolDenied` (HITL result pair; `override_args`), `JsonSchemaTransformer` + `InlineDefsJsonSchemaTransformer` (schema walk + transform pattern), `TemporalAgent` (Temporal durable execution; activity config hierarchy), `ToolsetTool` (internal toolset tool wrapper; `args_validator_func`). New guide `pydantic_ai_class_deep_dives_v6.md` created. Index updated with Zero→Hero step 26, Jump-to-topic and Reference cards.	Claude
2026-05-30	pydantic-ai 1.104.0	Library installed (1.104.0) and source inspected directly. Ten new class groups deep-dived: `PendingMessage` + `RunContext.enqueue`/`AgentRun.enqueue` (mid-run message injection with `'asap'`/`'when_idle'` priorities and `PendingMessageDrainCapability`), `AgentWorker` + `agent_to_a2a` (A2A protocol bridge; deprecated, migrate to `fasta2a.pydantic_ai`), `WrapperAgent` (agent middleware base class), `safe_download` + SSRF protection (full CIDR blocklists, cloud metadata guard, IPv6 transition decoding, cross-origin redirect stripping), `DBOSAgent` (durable DBOS workflow wrapper; `model_step_config`, `mcp_step_config`, automatic toolset wrapping), `StreamedResponseSync` (sync streaming via `threading.Thread` + `queue.Queue`), `ModelResponsePartsManager` (streaming event engine; vendor ID tracking, tool kind narrowing, embedded `<think>` tag handling), `CombinedCapability` (capability composition; flattening, forward/reverse hook ordering, dynamic `ModelSettings` merging), `FastMCPToolset` (deprecated; full migration guide to `MCPToolset`), `SetToolMetadata` (Code Mode + arbitrary metadata injection via `ToolSelector`). New guide `pydantic_ai_class_deep_dives_v5.md` created. Index updated with Zero→Hero step 25, Jump-to-topic card, and Reference card.	Claude
2026-05-29	pydantic-ai 1.104.0	Library installed (1.104.0) and source inspected directly. Ten new class groups deep-dived: `LangChainTool` + `LangChainToolset`, `VercelAIAdapter` (SDK v5/v6), `ToolManager` + `ValidatedToolCall`, `ThreadExecutor`, `PrefixTools`, `PrepareTools` + `PrepareOutputTools`, `ImageGeneration`, `XSearch`, `duckduckgo_search_tool` + `tavily_search_tool` + `ExaToolset`, `FunctionSignature` + `TypeSignature`. New guide `pydantic_ai_class_deep_dives_v4.md` created. Index updated with Zero→Hero step 24, Jump-to-topic, Reference entries, and version bumped to v1.104.0. All core guide symbols verified with `-W error::DeprecationWarning`; 178 top-level exports confirmed.	Claude
2026-05-28	pydantic-ai 1.103.0	Library installed (1.103.0) and source inspected directly. Ten new class families deep-dived: `MCPToolset` + `load_mcp_toolsets`, `UIAdapter` + `MessagesBuilder`, `CachePoint` + `CompactionPart`, `format_as_xml`, `BinaryContent` + `FileUrl` family, `DeferredToolRequests` + `DeferredToolResults` + `CallDeferred` + `ApprovalRequired`, `NativeTool`, `NativeOrLocalTool`, `DynamicCapability`, `ToolSearch`. New guide `pydantic_ai_class_deep_dives_v3.md` created. Index updated with Zero→Hero step 23, Jump-to-topic, and Reference entries. Version card updated to v1.103.0.	Claude
2026-05-26	pydantic-ai 1.102.0	Library installed (1.102.0) and source inspected directly. Ten new classes deep-dived: `FallbackModel` + `FallbackExceptionGroup`, `ModelProfile` + `ModelProfileSpec` + `DEFAULT_PROFILE`, `WrapperToolset` + `RenamedToolset` + `PrefixedToolset` + `SetMetadataToolset`, `InstrumentationSettings` + `InstrumentedModel`, `UploadedFile`, `TemplateStr`, `ProcessHistory` + `ReinjectSystemPrompt`, `AbstractCapability`, `EndStrategy` + `AgentRetries`, `ModelRequestContext`. New guide `pydantic_ai_class_deep_dives_v2.md` created. Index updated with Zero→Hero step 22, Jump-to-topic, and Reference entries.	Claude
2026-05-25	pydantic-ai 1.102.0	Library installed (1.102.0) and source inspected directly. Ten classes deep-dived: `RunContext` (all 22 fields including newer `conversation_id`, `tool_call_approved`, `tool_call_metadata`, `partial_output`, `metadata`), `Hooks` (all 33 events + constructor-kwargs pattern), `WebSearch` (native/local/domain-control/location/custom-fallback), `WebFetch` (SSRF guards, citations, content limits), `Thinking` (all effort levels, cross-provider), `FilteredToolset` (sync + async RBAC + phase-gating), `CombinedToolset` (heterogeneous sources, dynamic per-run), `ApprovalRequiredToolset` (full HITL workflow + metadata passthrough), `ExternalToolset` (deferred execution workflow + durable ID), `UsageLimits` + `RunUsage` (all fields, token budgets, preflight counting, aggregation across runs). New guide `pydantic_ai_source_code_deep_dive.md` created (with production-grade capstone example). Index updated with Zero→Hero step 21, Jump-to-topic, and Reference entries.	Claude
2026-05-24	pydantic-ai 1.102.0	Library installed (1.102.0) and source inspected directly. Ten classes deep-dived: `AgentSpec`, `SkipModelRequest`, `SkipToolExecution`, `SkipToolValidation`, `ProcessEventStream`, `HandleDeferredToolCalls`, `PreparedToolset`, `DeferredLoadingToolset`, `InstructionPart`, `IncludeToolReturnSchemas`. New guide `pydantic_ai_advanced_classes_part2.md` created. Hooks guide enhanced with Skip exceptions section. Output types guide enhanced with NativeOutput/PromptedOutput/TextOutput advanced patterns. Embeddings guide updated to 1.102.0 with VoyageAI, Cohere, batch processing, and RAG pipeline examples. Toolsets guide extended with PreparedToolset i18n, phase-gated, and DeferredLoadingToolset mixed-visibility patterns. Index updated with new nav entries.	Claude
2026-05-23	pydantic-ai 1.102.0	Version bumped 1.101.0 → 1.102.0; “What’s new” heading updated to v1.102.0; v1.102.0 bullet added. All core guide symbols verified with `-W error::DeprecationWarning` against installed `pydantic-ai==1.102.0` (`.routine-envs/check-0523-pydantic`); all PASS. 179 top-level exports confirmed; API surface unchanged.	Claude routine
2026-05-22	pydantic-ai 1.101.0	Version bumped 1.99.0 → 1.101.0 (two minor releases: 1.100.0, 1.101.0); “What’s new” heading updated to v1.101.0; v1.100.0 and v1.101.0 bullets added. All core guide symbols verified with `-W error::DeprecationWarning` against installed `pydantic-ai==1.101.0` (`.routine-envs/check-0522-pydantic`); all PASS. 178 top-level exports confirmed.	Claude routine
2026-05-22	pydantic-ai 1.101.0	Library installed (1.101.0) and source inspected directly. Ten classes deep-dived: `Tool` (§13), `ModelSettings` (§14), `Hooks` (§15), `Thinking` (§16), `WebSearch` (§17). `builtin_tools.md` migrated to `capabilities=[NativeTool(...)]` API. Toolsets guide: 3 new end-to-end examples. `index.mdx` and all `Verified against` headers updated to 1.101.0.	Claude
2026-05-21	pydantic-ai 1.100.0	3 new deep-dive pages added (Hooks, Concurrency Limiting, Embeddings); 5 existing guides substantially enhanced (Toolsets — WrapperToolset/AbstractToolset/SetMetadataToolset; Advanced error testing — full rewrite with exception hierarchy, TestModel, FunctionModel, pytest fixtures; Output types — NativeOutput strict mode and template=False; Advanced patterns — AgentRun.iter() patterns); index updated with new nav entries. 10 classes inspected from installed pydantic-ai==1.100.0 source: Hooks, ConcurrencyLimiter, FilteredToolset, ApprovalRequiredToolset, DeferredLoadingToolset, Embedder, AgentRun, NativeOutput, SetMetadataToolset, WrapperToolset.	Claude
2026-05-20	pydantic-ai 1.99.0	Version bumped 1.98.0 → 1.99.0; “What’s new” heading updated to v1.99.0; v1.99.0 bullet added. All core guide symbols verified against installed `pydantic-ai==1.99.0` (`.routine-envs/check-0520-pydantic`) with `-W error::DeprecationWarning`; all PASS.	Claude routine
2026-05-20	pydantic-ai 1.99.0	Library installed and source inspected directly. Twelve classes deep-dived from source: `Agent`, `RunContext`, `UsageLimits`, `ConcurrencyLimiter`, `FunctionToolset`, `AgentRunResult`, `ToolDefinition`, `ModelRetry`, `TestModel`, `FunctionModel` (all ten inspected at source), plus `UsageLimits` (§11) and `ConcurrencyLimiter` (§12) added as full deep-dive sections to the class deep-dives guide. `pydantic_ai_advanced_error_testing.md` fully rewritten (was 32 lines stub). `pydantic_ai_streaming_server_fastapi.md` fully rewritten with correct pydantic-ai streaming APIs. All `Verified against` headers updated to 1.99.0.	Claude
2026-05-19	pydantic-ai 1.98.0	Version bumped 1.96.0 → 1.98.0; “What’s new” updated with `pydantic_ai.ag_ui` deprecation and new `common_tools` module; comprehensive guide updated with ag_ui deprecation note; revision history entries added. All core guide symbols verified against installed `pydantic-ai==1.98.0` (`.routine-envs/check-0519-py`); no `DeprecationWarning` emissions on imports.	Claude routine
2026-05-14	pydantic-ai 1.96.0	Version bumped 1.95.0 → 1.96.0; “What’s new” updated with concurrency management API (`ConcurrencyLimiter`, `limit_model_concurrency`); comprehensive guide header updated; revision history entry added. All guide-referenced symbols verified against installed `pydantic-ai==1.96.0` (`.routine-envs/check-0514-py`); no `DeprecationWarning` emissions.	Claude routine
2026-05-13	pydantic-ai 1.95.0	Version bumped 1.94.0 → 1.95.0; “What’s new” updated; comprehensive guide header updated; revision history entry added. All guide-referenced symbols (`Agent`, `RunContext`, `ModelRetry`, `AgentRunResult`, `StreamedRunResult`, `UsageLimits`, `RunUsage`, `capture_run_messages`) verified with `-W error::DeprecationWarning` against installed `pydantic-ai==1.95.0` (`.routine-envs/check-0513-py`); no warnings. Additional exports `AgentRunResultEvent`, `AgentEventStream` confirmed.	Claude routine
2026-05-12	pydantic-ai 1.94.0	Version bumped 1.93.0 → 1.94.0; “What’s new” updated; comprehensive guide header updated; revision history entry added. New exports `AgentRun`, `AgentRunResult`, `StreamedRunResultSync` confirmed present in installed 1.94.0 (`.routine-envs/check-0512-py`). All guide-referenced symbols (`Agent`, `RunContext`, `ModelRetry`, `AgentRunResult`, `StreamedRunResult`, `UsageLimits`, `RunUsage`, `capture_run_messages`) verified with `-W error::DeprecationWarning`; no warnings.	Claude routine
2026-05-09	pydantic-ai 1.93.0	Version bumped 1.90.0 → 1.93.0 (three minor releases: 1.91.0, 1.92.0, 1.93.0); “What’s new” updated; comprehensive guide header updated; revision history entry added. Breaking change: `TestModel` removed from `pydantic_ai` top-level — guide already uses `from pydantic_ai.models.test import TestModel` (correct path). New symbols `AgentSpec`, `UploadedFile`, `WebSearchUserLocation`, `DeferredLoadingToolset` all confirmed present in installed 1.93.0 (`.routine-envs/check-0509-py`).	Claude routine
2026-05-05	pydantic-ai 1.90.0	Version bumped 1.89.1 → 1.90.0; “What’s new” updated (DeferredToolCalls deprecated in favour of DeferredToolRequests); comprehensive guide header updated; revision history entry added. `Agent`, `TestModel`, `FunctionToolset`, `DeferredToolRequests`, `HandleDeferredToolCalls`, `ImageGenerationTool`, `MemoryTool`, `XSearchTool`, `RenamedToolset`, `WrapperToolset`, `IncludeReturnSchemasToolset`, `SetMetadataToolset`, `PreparedToolset` imports verified against installed 1.90.0 (`.routine-envs/check-0505`).	Claude routine
2026-05-02	pydantic-ai 1.89.1	Version bumped 1.89.0 → 1.89.1; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. `Agent`, `OpenAIModel` imports verified against installed 1.89.1 (`.routine-envs/check-pydantic-0502`).	Claude routine
2026-05-01	pydantic-ai 1.89.0	Version bumped 1.88.0 → 1.89.0; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. `Agent`, `OpenAIModel` imports verified against installed 1.89.0 (`.routine-envs/check-pydantic-0501`).	Claude routine
2026-04-29	pydantic-ai 1.88.0	Version bumped 1.87.0 → 1.88.0; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. `Agent`, `OpenAIModel` imports verified against installed 1.88.0 (`.routine-envs/main-py-0429`).	Claude routine
2026-04-25	pydantic-ai 1.87.0	Version bumped 1.86.1 → 1.87.0; “What’s new” updated for v1.87.0 (9 new capability classes); new Capabilities API (v1.87.x) section added to comprehensive guide documenting `WrapperCapability`, `ReinjectSystemPrompt`, `ProcessHistory`, `ProcessEventStream`, `HandleDeferredToolCalls`, `IncludeToolReturnSchemas`, `PrefixTools`, `PrepareTools`, `SetToolMetadata`. All symbols verified against installed 1.87.0.	Claude routine
2026-04-24	pydantic-ai 1.86.1	Version bumped 1.85.1 → 1.86.1; “What’s new” updated for v1.86.x (Capabilities API, Hooks, ModelProfile, UI module); Capabilities API section added to comprehensive guide with verified snippets.	Claude routine
2026-04-22	pydantic-ai 1.85.1	Added 7 new deep-dive pages, all verified against installed 1.85.1 source: Output types & validators (ToolOutput / NativeOutput / PromptedOutput / TextOutput / StructuredDict + output_validator), Message history (ModelMessagesTypeAdapter, HistoryProcessor, capture_run_messages), Testing (TestModel, FunctionModel, Agent.override), Model providers & fallback (every prefix in `providers/__init__.py`, FallbackModel with custom handlers, gateway), Streaming (run_stream, run_stream_events, iter, AgentStream), Toolsets (FunctionToolset, Combined/Prefixed/Filtered/Prepared/Approval/Deferred/External), Built-in tools (WebSearch, WebFetch, CodeExecution, ImageGeneration, FileSearch, Memory, MCPServer, XSearch). Index re-ordered into an 18-step Zero → Hero reading order; Jump-to-topic and Reference grids re-indexed.	Claude routine
2026-04-22	pydantic-ai 1.85.1	Version bumped 1.85.0 → 1.85.1; “What’s new” section updated for v1.85.x (8 built-in tools, embeddings API, AG UI adapter, ApprovalRequiredToolset HITL, DeferredLoadingToolset); fabricated `pydantic_ai.common_tools` imports replaced with correct `pydantic_ai.builtin_tools` API; `UrlContextTool` deprecation noted. Snippets verified against installed 1.85.1.	Claude routine
2026-04-21	pydantic-ai 1.84.1	Index redesigned with Zero → Hero + Jump-to-topic grid.	—
2026-04-18	pydantic-ai 1.84.1	Patch; bug fixes.	—
2026-04-17	pydantic-ai 1.84.0	Evals framework; graph support improvements.	—
November 2025	pydantic-ai 1.14.x	Initial 2025 guide with durable execution, graphs, integrations.	—