pypi pydantic-ai 2.69.0
v2.69.0 (2026-11-16)

34 minutes ago

What's Changed

⚠️ Compatibility Notes

  • Fold RequestInput into HandleDeferredToolCalls, whose handler can take a resume token by @DouweM in #13285
  • Support Gemini 4 Hydrogen (gemini-4-hydrogen) on GoogleModel by @dsfaccini in #13299
  • Generalize response-scoped tool call IDs into the tool_call_ids_are_response_scoped profile flag by @DouweM in #13128
  • Add service_tier support to GroqModel by @dsfaccini in #13521
  • Detect loops in streamed thinking, text and tool call arguments in DetectLoops by @mpfaffenberger in #12222
  • Make Advisor accept native= and local= like the other NativeOrLocalTool capabilities, deprecating mode by @adtyavrdhn in #13149
  • Treat nested CodeMode ToolFailed calls as failed results by @pydanty in #13076
  • Keep settled sub-agent task histories in their saved files instead of in every DelegationTasks owner's memory by @DouweM in #13221
  • Raise ModelQuotaExceededError for Anthropic's tier spend cap and user-set spend limits by @dsfaccini in #13269
  • Send structured tool return items next to a file to the model as JSON, not as escaped JSON strings by @dsfaccini in #13271
  • Raise a gave-up transport status or connection error from Google embeddings, image generation and GoogleModel.count_tokens as ModelAPIError by @dsfaccini in #13312
  • Raise a Gemini API error from GoogleImageGenerationModel.generate as its error category, like ModelRateLimitError by @dsfaccini in #13335
  • Raise an error status a retrying transport gave up on during a streamed Gemini long decode as ModelHTTPError by @dsfaccini in #13356
  • Raise a gave-up transport status from OpenAI and Cohere embeddings, OpenAI image generation and GoogleModel batch methods as ModelHTTPError by @dsfaccini in #13327
  • Cache opaque Prefect run IDs across retries by @dsfaccini in #11896
  • Reject a TextOutput function that takes a model, dataclass or TypedDict when the agent is created by @dsfaccini in #13422
  • Keep the body of an error status that HTTPX2TenacityTransport and AsyncHTTPX2TenacityTransport gave up on by @dsfaccini in #13411
  • Raise OpenAI API and connection errors from OpenAIImageGenerationModel.generate as their error category, like ModelRateLimitError by @dsfaccini in #13433
  • Raise realtime connection errors with an HTTP status as their error category, like ModelRateLimitError by @dsfaccini in #13436
  • Keep Bedrock GPT-5.6 and GPT-6 encrypted reasoning out of Claude-on-Bedrock requests by @pydanty in #12943
  • Raise ModelContextWindowExceededError for Mistral 3059 prompt-too-long errors, not for other 3051 invalid-argument errors by @pydanty in #12882
  • Raise a status a retrying transport gave up on as the error category its body names, like ModelQuotaExceededError by @dsfaccini in #13485
  • Stop counting OpenRouter's is_byok flag as a usage detail by @pydanty in #13025
  • Map Gemini IMAGE_RECITATION and TOO_MANY_TOOL_CALLS finish reasons to content_filter and error by @pydanty in #10918
  • Make TestModel integers satisfy mixed inclusive and exclusive bounds, and fractional bounds by @pydanty in #13298
  • Add minimax_model_profile and use it for MiniMax models on Bedrock, OpenAICompatibleProvider, LiteLLMProvider and TogetherProvider by @pydanty in #12693
  • Map Mistral Large 4 thinking levels to its low/medium/high reasoning_effort values by @pydanty in #12876
  • Apply FunctionToolset's strict, sequential, defer_loading and include_return_schema defaults to Tool instances by @pydanty in #12572
  • Make TestModel streamed usage match run() for tool calls and text by @pydanty in #11877
  • Run the token count count_tokens_before_request asks for in its own durable unit by @dsfaccini in #13460
  • Skip a failing TieredCompaction tier on model errors, and let tiers omit their trigger by @mpfaffenberger in #13660
  • Rename harness subagents, filesystem and spend packages to their capability names and align store, ACP* and *Error class names by @mpfaffenberger in #13401
  • Rename the DockerSandbox harness capability to DockerContainer, keeping DockerSandbox as a deprecated alias by @adtyavrdhn in #13245
  • Rename BubblewrapSandbox to BubblewrappedWorkspace and clarify its docs by @mpfaffenberger in #13179

🚀 Features

  • Trim Coder's default instructions and add Coder(autonomy=...) by @mpfaffenberger in #12542
  • Fold RequestInput into HandleDeferredToolCalls, whose handler can take a resume token by @DouweM in #13285
  • Support Gemini 4 Hydrogen (gemini-4-hydrogen) on GoogleModel by @dsfaccini in #13299
  • Add is_retry to find retries in message history and list the v2.60.0 RetryPromptPart change as breaking by @DouweM in #11404
  • Move benchmark-only Coder instructions into opt-in BenchmarkInstructions by @mpfaffenberger in #13395
  • Generalize response-scoped tool call IDs into the tool_call_ids_are_response_scoped profile flag by @DouweM in #13128
  • Add peer messaging with Peers in pydantic-ai-harness by @dsfaccini in #11671
  • Add an anthropic_inference_geo setting for Anthropic data residency by @rscholz98 in #12769
  • Add opt-in recursive node registration with GraphBuilder.add_reachable() by @dsfaccini in #12706
  • Add WindowsWorkspace, a PowerShell workspace for Windows hosts by @mpfaffenberger in #13475
  • Add service_tier support to GroqModel by @dsfaccini in #13521
  • Add KubernetesSandbox for kubernetes-sigs/agent-sandbox pods by @adtyavrdhn in #10612
  • Add E2BSandbox(network=), passing E2B's network options through to a new sandbox by @adtyavrdhn in #13587
  • Add BoxdSandbox(secrets=), naming the boxd secrets a new machine gets by @adtyavrdhn in #13589
  • Add pin(source=) so harness compaction re-injects tool- and model-written pins as framed data, not the user's words by @mpfaffenberger in #13615
  • Let Advisor.max_uses take a callable so a consultation budget can span several runs by @mpfaffenberger in #13617
  • Add DynamicWorkflowToolset.create_executor so subclasses can customize how sub-agent calls are scheduled by @mpfaffenberger in #13623
  • Detect loops in streamed thinking, text and tool call arguments in DetectLoops by @mpfaffenberger in #12222
  • Add openai_safety_identifier model setting by @pydanty in #12258
  • Add DaytonaSandbox(secrets=), mounting Daytona secrets in a new sandbox by @adtyavrdhn in #13590
  • Add OpenSandbox(network_policy=) and OpenSandboxBackend(credential_proxy=), passing OpenSandbox's egress options through by @adtyavrdhn in #13591
  • Wait a model error's retry_after durably before DBOS retries a model request, via a shared model_error_retry_after helper by @DouweM in #13270
  • Add CapabilityCreation.load_active(workspace), which refuses a store directory below 'operator' authority before loading it by @mpfaffenberger in #13641
  • Report pydantic-ai-harness in MongoDB handshake driver metadata by @pydanty in #13394
  • Add Reminder(skip_unchanged=True) so SystemReminders stops re-recording an unchanged lasting reminder by @mpfaffenberger in #13618
  • Add ToolBudgets to answer over-budget and repeated tool calls instead of raising by @mpfaffenberger in #13646
  • Add DynamicWorkflow(call_scheduler=) to decide when sub-agent calls start by @mpfaffenberger in #13668
  • Add pin_accepted_files, capping the authority of accepted instruction files that have changed by @mpfaffenberger in #13677
  • Add SubAgent(keep_partial_output=), passing a sub-agent's last text to the parent when its own timeout or usage budget stops it by @mpfaffenberger in #13696
  • Make Advisor accept native= and local= like the other NativeOrLocalTool capabilities, deprecating mode by @adtyavrdhn in #13149
  • Add authority and path_authority to the sandbox and SSHWorkspace capabilities by @DouweM in #13213
  • Render when_to_use in the Skills catalog by @mpfaffenberger in #13619

🐛 Bug Fixes

  • Keep SmolSandbox commands' env variables named p or q from being overwritten by the launcher by @adtyavrdhn in #13248
  • Treat nested CodeMode ToolFailed calls as failed results by @pydanty in #13076
  • Keep settled sub-agent task histories in their saved files instead of in every DelegationTasks owner's memory by @DouweM in #13221
  • Run DynamicWorkflow sub-agents durably: in parallel under AWSLambdaDurability, and one at a time under DBOSDurability by @mpfaffenberger in #12710
  • Add CodeMode(os_policy=...) to set the sandbox clock and time zone by @mpfaffenberger in #13277
  • Preserve multimodal tool return values in ToolOutputLimits by @mpfaffenberger in #13281
  • Preserve memory content containing NUL in SqliteMemoryStore by @mpfaffenberger in #13278
  • Keep non-object tool arguments invalid in BaseToolCallPart.args_as_dict under python -O by @dsfaccini in #13268
  • Keep ConversationStore.save from re-storing a serialized output tool conversation as a new branch every turn by @dsfaccini in #13272
  • Raise ModelQuotaExceededError for Anthropic's tier spend cap and user-set spend limits by @dsfaccini in #13269
  • Keep OpenAIResponsesModel runs from failing on a web_search_call without action, and read the reported web search count on newer openai SDKs by @dsfaccini in #13304
  • Send structured tool return items next to a file to the model as JSON, not as escaped JSON strings by @dsfaccini in #13271
  • Fix MCPSamplingModel system prompt separator and conditional <system> announcement by @pydanty in #12488
  • Raise a gave-up transport status or connection error from Google embeddings, image generation and GoogleModel.count_tokens as ModelAPIError by @dsfaccini in #13312
  • Offer each on-demand capability as a route of its own on a DecisionModel, and keep the capability catalog out of its question framing by @DouweM in #8759
  • Count a nested FallbackModel's rejected responses when an outer fallback handles the error it raises by @dsfaccini in #13325
  • Save keyword-only evaluator arguments by name in Dataset files, and drop the positional spec schema form for keyword-only parameters by @dsfaccini in #13332
  • Raise a Gemini API error from GoogleImageGenerationModel.generate as its error category, like ModelRateLimitError by @dsfaccini in #13335
  • Keep output functions with a single aliased parameter from raising KeyError, and pass **kwargs and SkipJsonSchema argument values through by @dsfaccini in #13323
  • Raise an error status a retrying transport gave up on during a streamed Gemini long decode as ModelHTTPError by @dsfaccini in #13356
  • Return an empty task list from GraphRun.next_task after a map over an empty list by @adtyavrdhn in #13357
  • Spell IPv6 hosts with - in the MCP capability's derived id by @adtyavrdhn in #13358
  • Start the SpritesSandbox command timeout once its exec socket is open by @adtyavrdhn in #13360
  • Retry Advisor and SubAgents child runs without inherited count_tokens_before_request when their model cannot count tokens by @mpfaffenberger in #10139
  • Resolve ctx.tracer from the worker agent inside Temporal activities so Memory tools run by @mpfaffenberger in #10199
  • Raise ModelRequestRejectedError for HTTP 413 by @adtyavrdhn in #13366
  • Load the {SetToolMetadata: [...]} and {SetToolMetadata: 'all'} agent spec short forms instead of failing by @dsfaccini in #13380
  • Inline $defs in zai.glm-5.3 tool and output schemas on Bedrock by @dsfaccini in #13187
  • Raise a gave-up transport status from OpenAI and Cohere embeddings, OpenAI image generation and GoogleModel batch methods as ModelHTTPError by @dsfaccini in #13327
  • Drop register_tag's late-registration UserWarning by @dsfaccini in #12450
  • Drain many delegated children on DelegationTasks close without crashing on a cleanup timeout by @mpfaffenberger in #12972
  • Cache opaque Prefect run IDs across retries by @dsfaccini in #11896
  • Reject a TextOutput function that takes a model, dataclass or TypedDict when the agent is created by @dsfaccini in #13422
  • Make the Dataset and AgentSpec JSON schemas match how a single dict- or model-typed spec parameter loads by @dsfaccini in #13423
  • Keep the body of an error status that HTTPX2TenacityTransport and AsyncHTTPX2TenacityTransport gave up on by @dsfaccini in #13411
  • Call a TextOutput function by its aliased str parameter's Python name next to a SkipJsonSchema or **kwargs parameter by @dsfaccini in #13350
  • Reveal deferred tools that an OpenAI tool_search_output returns wrapped in a NamespaceTool by @dsfaccini in #13473
  • Raise OpenAI API and connection errors from OpenAIImageGenerationModel.generate as their error category, like ModelRateLimitError by @dsfaccini in #13433
  • Raise realtime connection errors with an HTTP status as their error category, like ModelRateLimitError by @dsfaccini in #13436
  • Add GPT-6.1 Terra to the Bedrock Converse profile gate by @pydanty in #12731
  • Run durable function tools with aliased parameters instead of failing revalidation with Field required by @dsfaccini in #13434
  • Make the AgentSpec JSON schema accept the NativeTool flat form {NativeTool: {kind: ...}} by @dsfaccini in #13469
  • Keep Bedrock GPT-5.6 and GPT-6 encrypted reasoning out of Claude-on-Bedrock requests by @pydanty in #12943
  • Send a request-side CompactionPart from OpenAIDecisionsModel as framed user text by @dsfaccini in #13478
  • Reuse the run's workspace for durable workspace calls made while a run is prepared under DBOSDurability and PrefectDurability by @adtyavrdhn in #13466
  • Make the AgentSpec and Dataset JSON schemas reject empty entries and string-keyed short forms that fail to load by @dsfaccini in #13453
  • Delete the input file batch_create uploaded when a retrying transport gives up on the job's 4xx by @dsfaccini in #13479
  • Leave capabilities and evaluators that no spec entry can load out of the AgentSpec and Dataset JSON schemas by @dsfaccini in #13483
  • Raise ModelContextWindowExceededError for Mistral 3059 prompt-too-long errors, not for other 3051 invalid-argument errors by @pydanty in #12882
  • Don't take text streamed before a tool call as a durable run's final output when output_type is structured by @pydanty in #13241
  • Raise a status a retrying transport gave up on as the error category its body names, like ModelQuotaExceededError by @dsfaccini in #13485
  • Make the AgentSpec and Dataset JSON schemas accept keyword-only parameters of **kwargs targets only by name by @dsfaccini in #13494
  • [cache] Set a 30-minute default_cache_retention for GPT-6 and GPT-6.1 models on Bedrock Converse by @dsfaccini in #13495
  • Register @dataclass(slots=True) native tool subclasses under their kind by @dsfaccini in #13499
  • Require ipykernel>=6.30.0 for pydantic-ai-harness[ipython] on Python 3.15 by @dsfaccini in #13503
  • Await any awaitable returned by Evaluator.evaluate and ReportEvaluator.evaluate, not just coroutines by @pydanty in #13441
  • Raise ModelConnectionError when the connection drops while the openai SDK reads a streamed error body by @pydanty in #12333
  • Evaluate ISO-8601 duration strings in MaxDuration and SpanQuery duration bounds by @pydanty in #12780
  • Stop LocalWorkspaceBackend.run raising a bare PermissionError when neither the process group nor the command can be killed by @pydanty in #12651
  • Raise ModelContextWindowExceededError when Ollama Cloud reports exceeded max context length by @pydanty in #12112
  • Map Cohere TIMEOUT finish reason to error by @pydanty in #11299
  • Apply DeepSeek V4 thinking support and Together's forced-tool-choice restriction to V4.1 ids like deepseek-v4.1-flash and deepseek-v4p1-flash by @pydanty in #12566
  • Stop counting OpenRouter's is_byok flag as a usage detail by @pydanty in #13025
  • Map Gemini IMAGE_RECITATION and TOO_MANY_TOOL_CALLS finish reasons to content_filter and error by @pydanty in #10918
  • Make TestModel integers satisfy mixed inclusive and exclusive bounds, and fractional bounds by @pydanty in #13298
  • Drop Gemini's interim thought images from non-streaming GoogleModel responses by @pydanty in #8644
  • [thinking-profiles] Route Kimi model ids through the Moonshot family profile on FireworksProvider, VercelProvider, OllamaProvider and CerebrasProvider by @pydanty in #12383
  • Fix TestModel tool-args generation for schemas with list-form type by @pydanty in #13097
  • Add minimax_model_profile and use it for MiniMax models on Bedrock, OpenAICompatibleProvider, LiteLLMProvider and TogetherProvider by @pydanty in #12693
  • Skip an empty ThinkingPart instead of sending bare think tags when replaying assistant history to OpenAI and Bedrock by @pydanty in #13396
  • Map Mistral Large 4 thinking levels to its low/medium/high reasoning_effort values by @pydanty in #12876
  • Send Ollama max_tokens setting as max_tokens, not max_completion_tokens by @pydanty in #12552
  • Apply FunctionToolset's strict, sequential, defer_loading and include_return_schema defaults to Tool instances by @pydanty in #12572
  • Accept a UTF-8 byte order mark in Dataset.from_file and AgentSpec.from_file by @pydanty in #8317
  • Make NativeTool specs and request telemetry use native tool types defined after import by @dsfaccini in #13559
  • Make TestModel streamed usage match run() for tool calls and text by @pydanty in #11877
  • Run the token count count_tokens_before_request asks for in its own durable unit by @dsfaccini in #13460
  • Pair replayed tool-search calls and results where the API rejects unpaired ones, with ModelProfile.rejects_unpaired_tool_calls by @dsfaccini in #13489
  • Treat a response that reuses a still-open tool_call_id as unpaired by @gouyu-hou in #12352
  • Refuse a sandboxed tool named after a Python builtin in IPythonCodeMode too, not just CodeMode by @gouyu-hou in #12767
  • Match write_memory old_text copied from the snapshot against a MEMORY.md with \r\n line endings by @mpfaffenberger in #13613
  • Keep every change when the model calls several Planning tools in one response by @mpfaffenberger in #13614
  • Keep UI events in a list ToolReturn.metadata when ToolOutputLimits spills by @beriki770-ship-it in #12565
  • Skip a failing TieredCompaction tier on model errors, and let tiers omit their trigger by @mpfaffenberger in #13660
  • [thinking-profiles] Support thinking on Gemma 4 in the Google model profile by @pydanty in #12135
  • Close the SqlitePlanStore connection when its schema setup fails on a locked database by @mpfaffenberger in #13626
  • Confine LocalFileOverflowStore writes to the store root, as reads already are by @dsfaccini in #13632
  • Accept an async api_key callable in OpenAIProvider by @pydanty in #7886
  • Run FileSystem's write_file, edit_file and create_directory in the order the model sent them by @mpfaffenberger in #13625
  • Skip CREATE TABLE in the harness Postgres media, memory, planning and step stores when their tables exist by @mpfaffenberger in #13675

📦 Dependencies

  • Document how google-genai 2.31.0 and later re-send a failed streamed long-decode continuation request by @pydanty in #13449

New Contributors

Full Changelog: v2.68.0...v2.69.0

Don't miss a new pydantic-ai release

NewReleases is sending notifications on new releases.