Merge branch 'main' into examples/medical-triage-delegation

Author: sijanonly

.github/workflows/after-ci.yml

@@ -45,6 +45,10 @@ jobs:
       name: deploy-docs-preview
 
     steps:
+      - run: echo "$GITHUB_EVENT_JSON"
+        env:
+          GITHUB_EVENT_JSON: ${{ toJSON(github.event) }}
+
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
@@ -57,7 +61,8 @@ jobs:
           enable-cache: true
           cache-suffix: deploy-docs-preview
 
-      - uses: dawidd6/action-download-artifact@v6
+      - id: download-artifact
+        uses: dawidd6/action-download-artifact@v6
         with:
           workflow: ci.yml
           name: site
@@ -69,6 +74,7 @@ jobs:
 
       - uses: cloudflare/wrangler-action@v3
         id: deploy
+        if: steps.download-artifact.outputs.found_artifact == 'true'
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           environment: previews
@@ -78,12 +84,9 @@ jobs:
             --var GIT_COMMIT_SHA:${{ github.event.workflow_run.head_sha }}
             --var GIT_BRANCH:${{ github.event.workflow_run.head_branch }}
 
-      - run: echo "$GITHUB_EVENT_JSON"
-        env:
-          GITHUB_EVENT_JSON: ${{ toJSON(github.event) }}
-
       - name: Set preview URL
         run: uv run --no-project --with httpx .github/set_docs_pr_preview_url.py
+        if: steps.deploy.outcome == 'success'
         env:
           DEPLOY_OUTPUT: ${{ steps.deploy.outputs.command-output }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/changelog.md

@@ -1,7 +1,6 @@
 # Upgrade Guide
 
-In September 2025, Pydantic AI reached V1, which means we're committed to API stability: we will not introduce changes that break your code until V2 (if we do, you can shout at us as it's definitely a mistake).
-Once we release V2, in April 2026 at the earliest, we'll continue to provide security fixes for V1 for another 6 months minimum, so you have time to upgrade your applications.
+In September 2025, Pydantic AI reached V1, which means we're committed to API stability: we will not introduce changes that break your code until V2. For more information, review our [Version Policy](version-policy.md).
 
 ## Breaking Changes
 

docs/version-policy.md

@@ -0,0 +1,29 @@
+## Version Policy
+
+We will not intentionally make breaking changes in minor releases of V1. V2 will be released in April 2026 at the earliest, 6 months after the release of V1 in September 2025.
+
+Once we release V2, we'll continue to provide security fixes for V1 for another 6 months minimum, so you have time to upgrade your applications.
+
+Functionality marked as deprecated will not be removed until V2.
+
+Of course, some apparently safe changes and bug fixes will inevitably break some users' code — obligatory link to [xkcd](https://xkcd.com/1172/).
+
+The following changes will **NOT** be considered breaking changes, and may occur in minor releases:
+
+* Bug fixes that may result in existing code breaking, provided that such code was relying on undocumented features/constructs/assumptions.
+* Adding new [message parts][pydantic_ai.messages], [stream events][pydantic_ai.messages.AgentStreamEvent], or optional fields on existing message (part) and event types. Always code defensively when consuming message parts or event streams, and use the [`ModelMessagesTypeAdapter`][pydantic_ai.messages.ModelMessagesTypeAdapter] to (de)serialize message histories.
+* Changing OpenTelemetry span attributes. Because different [observability platforms](logfire.md#using-opentelemetry) support different versions of the [OpenTelemetry Semantic Conventions for Generative AI systems](https://opentelemetry.io/docs/specs/semconv/gen-ai/), Pydantic AI lets you configure the [instrumentation version](logfire.md#configuring-data-format), but the default version may change in a minor release. Span attributes for [Pydantic Evals](evals.md) may also change as we iterate on Evals support in [Pydantic Logfire](https://logfire.pydantic.dev/docs/guides/web-ui/evals/).
+* Changing how `__repr__` behaves, even of public classes.
+
+In all cases we will aim to minimize churn and do so only when justified by the increase of quality of Pydantic AI for users.
+
+## Beta Features
+
+At Pydantic, we like to move quickly and innovate! To that end, minor releases may introduce beta features (indicated by a `beta` module) that are active works in progress. While in its beta phase, a feature's API and behaviors may not be stable, and it's very possible that changes made to the feature will not be backward-compatible. We aim to move beta features out of beta within a few months after initial release, once users have had a chance to provide feedback and test the feature in production.
+
+## Support for Python versions
+
+Pydantic will drop support for a Python version when the following conditions are met:
+
+* The Python version has reached its [expected end of life](https://devguide.python.org/versions/).
+* less than 5% of downloads of the most recent minor release are using that version.

mkdocs.yml

@@ -14,7 +14,6 @@ nav:
   - install.md
   - help.md
   - troubleshooting.md
-  - changelog.md
 
   - Documentation:
       - Core Concepts:
@@ -191,6 +190,8 @@ nav:
 
   - Project:
       - contributing.md
+      - changelog.md
+      - version-policy.md
 
 extra:
   # hide the "Made with Material for MkDocs" message
@@ -333,7 +334,6 @@ plugins:
           - install.md
           - help.md
           - troubleshooting.md
-          - changelog.md
         Concepts documentation:
           - a2a.md
           - ag-ui.md
@@ -365,11 +365,15 @@ plugins:
           - durable_execution/*.md
         MCP:
           - mcp/*.md
+        UI Event Streams:
+          - ui/*.md
         Optional:
           - testing.md
           - cli.md
           - logfire.md
           - contributing.md
+          - changelog.md
+          - version-policy.md
         Examples:
           - examples/*.md
 

pydantic_ai_slim/pydantic_ai/models/google.py

@@ -471,11 +471,9 @@ def _process_response(self, response: GenerateContentResponse) -> ModelResponse:
                 raise UnexpectedModelBehavior(
                     f'Content filter {raw_finish_reason.value!r} triggered', response.model_dump_json()
                 )
-            else:
-                raise UnexpectedModelBehavior(
-                    'Content field missing from Gemini response', response.model_dump_json()
-                )  # pragma: no cover
-        parts = candidate.content.parts or []
+            parts = []  # pragma: no cover
+        else:
+            parts = candidate.content.parts or []
 
         usage = _metadata_as_usage(response)
         return _process_response_from_parts(
@@ -649,17 +647,12 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
             #     )
 
             if candidate.content is None or candidate.content.parts is None:
-                if self.finish_reason == 'stop':  # pragma: no cover
-                    # Normal completion - skip this chunk
-                    continue
-                elif self.finish_reason == 'content_filter' and raw_finish_reason:  # pragma: no cover
+                if self.finish_reason == 'content_filter' and raw_finish_reason:  # pragma: no cover
                     raise UnexpectedModelBehavior(
                         f'Content filter {raw_finish_reason.value!r} triggered', chunk.model_dump_json()
                     )
                 else:  # pragma: no cover
-                    raise UnexpectedModelBehavior(
-                        'Content field missing from streaming Gemini response', chunk.model_dump_json()
-                    )
+                    continue
 
             parts = candidate.content.parts
             if not parts:

pydantic_ai_slim/pydantic_ai/ui/_adapter.py

@@ -2,7 +2,7 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Sequence
-from dataclasses import KW_ONLY, Field, dataclass, replace
+from dataclasses import KW_ONLY, Field, dataclass
 from functools import cached_property
 from http import HTTPStatus
 from typing import (
@@ -238,7 +238,7 @@ def run_stream_native(
             else:
                 state = raw_state
 
-            deps = replace(deps, state=state)
+            deps.state = state
         elif self.state:
             raise UserError(
                 f'State is provided but `deps` of type `{type(deps).__name__}` does not implement the `StateHandler` protocol: it needs to be a dataclass with a non-optional `state` field.'

pydantic_ai_slim/pydantic_ai/ui/ag_ui/app.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping, Sequence
+from dataclasses import replace
 from typing import Any, Generic
 
 from typing_extensions import Self
@@ -18,7 +19,7 @@
 from pydantic_ai.toolsets import AbstractToolset
 from pydantic_ai.usage import RunUsage, UsageLimits
 
-from .. import OnCompleteFunc
+from .. import OnCompleteFunc, StateHandler
 from ._adapter import AGUIAdapter
 
 try:
@@ -121,6 +122,12 @@ def __init__(
 
         async def run_agent(request: Request) -> Response:
             """Endpoint to run the agent with the provided input data."""
+            # `dispatch_request` will store the frontend state from the request on `deps.state` (if it implements the `StateHandler` protocol),
+            # so we need to copy the deps to avoid different requests mutating the same deps object.
+            nonlocal deps
+            if isinstance(deps, StateHandler):  # pragma: no branch
+                deps = replace(deps)
+
             return await AGUIAdapter[AgentDepsT, OutputDataT].dispatch_request(
                 request,
                 agent=agent,

tests/test_ag_ui.py

@@ -1154,15 +1154,21 @@ async def store_state(
         ),
     ]
 
-    deps = StateDeps(StateInt(value=0))
+    seen_deps_states: list[int] = []
 
     for run_input in run_inputs:
         events = list[dict[str, Any]]()
-        async for event in run_ag_ui(agent, run_input, deps=deps):
+        deps = StateDeps(StateInt(value=0))
+
+        async def on_complete(result: AgentRunResult[Any]):
+            seen_deps_states.append(deps.state.value)
+
+        async for event in run_ag_ui(agent, run_input, deps=deps, on_complete=on_complete):
             events.append(json.loads(event.removeprefix('data: ')))
 
         assert events == simple_result()
     assert seen_states == snapshot([41, 0, 0, 42])
+    assert seen_deps_states == snapshot([42, 1, 1, 43])
 
 
 async def test_request_with_state_without_handler() -> None:
@@ -1275,8 +1281,10 @@ async def get_state(ctx: RunContext[StateDeps[StateInt]]) -> int:
 async def test_to_ag_ui() -> None:
     """Test the agent.to_ag_ui method."""
 
-    agent = Agent(model=FunctionModel(stream_function=simple_stream))
-    app = agent.to_ag_ui()
+    agent = Agent(model=FunctionModel(stream_function=simple_stream), deps_type=StateDeps[StateInt])
+
+    deps = StateDeps(StateInt(value=0))
+    app = agent.to_ag_ui(deps=deps)
     async with LifespanManager(app):
         transport = httpx.ASGITransport(app)
         async with httpx.AsyncClient(transport=transport) as client:
@@ -1286,6 +1294,7 @@ async def test_to_ag_ui() -> None:
                     id='msg_1',
                     content='Hello, world!',
                 ),
+                state=StateInt(value=42),
             )
             async with client.stream(
                 'POST',
@@ -1301,6 +1310,9 @@ async def test_to_ag_ui() -> None:
 
             assert events == simple_result()
 
+    # Verify the state was not mutated by the run
+    assert deps.state.value == 0
+
 
 async def test_callback_sync() -> None:
     """Test that sync callbacks work correctly."""