fix: Relax UserError into a warning when state deps is not provided with AG-UI (#3510)

Co-authored-by: Douwe Maan <[email protected]>

Author: MikeRyanDev

docs/ui/ag-ui.md

@@ -178,6 +178,8 @@ validate state contained in [`RunAgentInput.state`](https://docs.ag-ui.com/sdk/j
 
     If the `state` field's type is a Pydantic `BaseModel` subclass, the raw state dictionary on the request is automatically validated. If not, you can validate the raw value yourself in your dependencies dataclass's `__post_init__` method.
 
+    If AG-UI state is provided but your dependencies do not implement [`StateHandler`][pydantic_ai.ag_ui.StateHandler], Pydantic AI will emit a warning and ignore the state. Use [`StateDeps`][pydantic_ai.ag_ui.StateDeps] or a custom [`StateHandler`][pydantic_ai.ag_ui.StateHandler] implementation to receive and validate the incoming state.
+
 
 ```python {title="ag_ui_state.py"}
 from pydantic import BaseModel

pydantic_ai_slim/pydantic_ai/ui/_adapter.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Sequence
 from dataclasses import KW_ONLY, Field, dataclass
@@ -21,7 +22,6 @@
 from pydantic_ai.agent import AbstractAgent
 from pydantic_ai.agent.abstract import Instructions
 from pydantic_ai.builtin_tools import AbstractBuiltinTool
-from pydantic_ai.exceptions import UserError
 from pydantic_ai.messages import ModelMessage
 from pydantic_ai.models import KnownModelName, Model
 from pydantic_ai.output import OutputDataT, OutputSpec
@@ -243,8 +243,10 @@ def run_stream_native(
 
             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.'
+            warnings.warn(
+                f'State was provided but `deps` of type `{type(deps).__name__}` does not implement the `StateHandler` protocol, so the state was ignored. Use `StateDeps[...]` or implement `StateHandler` to receive AG-UI state.',
+                UserWarning,
+                stacklevel=2,
             )
 
         return self.agent.run_stream_events(

tests/test_ag_ui.py

@@ -39,7 +39,6 @@
 from pydantic_ai._run_context import RunContext
 from pydantic_ai.agent import Agent, AgentRunResult
 from pydantic_ai.builtin_tools import WebSearchTool
-from pydantic_ai.exceptions import UserError
 from pydantic_ai.models.function import (
     AgentInfo,
     BuiltinToolCallsReturns,
@@ -1206,12 +1205,15 @@ async def test_request_with_state_without_handler() -> None:
         state=StateInt(value=41),
     )
 
-    with pytest.raises(
-        UserError,
-        match='State is provided but `deps` of type `NoneType` does not implement the `StateHandler` protocol: it needs to be a dataclass with a non-optional `state` field.',
+    with pytest.warns(
+        UserWarning,
+        match='State was provided but `deps` of type `NoneType` does not implement the `StateHandler` protocol, so the state was ignored. Use `StateDeps\\[\\.\\.\\.\\]` or implement `StateHandler` to receive AG-UI state.',
     ):
-        async for _ in run_ag_ui(agent, run_input):
-            pass
+        events = list[dict[str, Any]]()
+        async for event in run_ag_ui(agent, run_input):
+            events.append(json.loads(event.removeprefix('data: ')))
+
+    assert events == simple_result()
 
 
 async def test_request_with_empty_state_without_handler() -> None: