Docs

Author: DouweM

README.md

@@ -50,8 +50,8 @@ Designed to give your IDE or AI coding agent as much context as possible for aut
 5. **Powerful Evals**:
 Enables you to systematically test and [evaluate](https://ai.pydantic.dev/evals) the performance and accuracy of the agentic systems you build, and monitor the performance over time in Pydantic Logfire.
 
-6. **MCP, A2A, and AG-UI**:
-Integrates the [Model Context Protocol](https://ai.pydantic.dev/mcp/client), [Agent2Agent](https://ai.pydantic.dev/a2a), and [AG-UI](https://ai.pydantic.dev/ag-ui) standards to give your agent access to external tools and data, let it interoperate with other agents, and build interactive applications with streaming event-based communication.
+6. **MCP, A2A, and UI**:
+Integrates the [Model Context Protocol](https://ai.pydantic.dev/mcp/overview), [Agent2Agent](https://ai.pydantic.dev/a2a), and various [UI event stream](https://ai.pydantic.dev/ui/overview) standards to give your agent access to external tools and data, let it interoperate with other agents, and build interactive applications with streaming event-based communication.
 
 7. **Human-in-the-Loop Tool Approval**:
 Easily lets you flag that certain tool calls [require approval](https://ai.pydantic.dev/deferred-tools#human-in-the-loop-tool-approval) before they can proceed, possibly depending on tool call arguments, conversation history, or user preferences.

docs-site/src/index.ts

@@ -55,6 +55,7 @@ const redirect_lookup: Record<string, string> = {
   '/examples': 'examples/setup/',
   '/mcp': '/mcp/overview/',
   '/models': '/models/overview/',
+  '/ag-ui': '/ui/ag-ui/'
 }
 
 function redirect(pathname: string): string | null {

docs/api/ui.md

@@ -0,0 +1,13 @@
+# `pydantic_ai.ui`
+
+::: pydantic_ai.ui
+
+::: pydantic_ai.ui.app
+
+::: pydantic_ai.ui.ag_ui
+
+::: pydantic_ai.ui.ag_ui.app
+
+::: pydantic_ai.ui.vercel_ai
+
+::: pydantic_ai.ui.vercel_ai.app

docs/examples/ag-ui.md

@@ -2,11 +2,11 @@
 
 Example of using Pydantic AI agents with the [AG-UI Dojo](https://github.com/ag-ui-protocol/ag-ui/tree/main/typescript-sdk/apps/dojo) example app.
 
-See the [AG-UI docs](../ag-ui.md) for more information about the AG-UI integration.
+See the [AG-UI docs](../ui/ag-ui.md) for more information about the AG-UI integration.
 
 Demonstrates:
 
-- [AG-UI](../ag-ui.md)
+- [AG-UI](../ui/ag-ui.md)
 - [Tools](../tools.md)
 
 ## Prerequisites

docs/index.md

@@ -25,8 +25,8 @@ Designed to give your IDE or AI coding agent as much context as possible for aut
 5. **Powerful Evals**:
 Enables you to systematically test and [evaluate](evals.md) the performance and accuracy of the agentic systems you build, and monitor the performance over time in Pydantic Logfire.
 
-6. **MCP, A2A, and AG-UI**:
-Integrates the [Model Context Protocol](mcp/client.md), [Agent2Agent](a2a.md), and [AG-UI](ag-ui.md) standards to give your agent access to external tools and data, let it interoperate with other agents, and build interactive applications with streaming event-based communication.
+6. **MCP, A2A, and UI**:
+Integrates the [Model Context Protocol](mcp/overview.md), [Agent2Agent](a2a.md), and various [UI event stream](ui/overview.md) standards to give your agent access to external tools and data, let it interoperate with other agents, and build interactive applications with streaming event-based communication.
 
 7. **Human-in-the-Loop Tool Approval**:
 Easily lets you flag that certain tool calls [require approval](deferred-tools.md#human-in-the-loop-tool-approval) before they can proceed, possibly depending on tool call arguments, conversation history, or user preferences.

docs/ag-ui.md renamed to docs/ui/ag-ui.md

@@ -52,7 +52,8 @@ from fastapi.responses import Response, StreamingResponse
 from pydantic import ValidationError
 
 from pydantic_ai import Agent
-from pydantic_ai.ui.ag_ui import AGUIAdapter, SSE_CONTENT_TYPE
+from pydantic_ai.ui import SSE_CONTENT_TYPE
+from pydantic_ai.ui.ag_ui import AGUIAdapter
 
 agent = Agent('openai:gpt-4.1', instructions='Be fun!')
 
@@ -63,23 +64,24 @@ app = FastAPI()
 async def run_agent(request: Request) -> Response:
     accept = request.headers.get('accept', SSE_CONTENT_TYPE)
     try:
-        run_input = AGUIAdapter.build_run_input(await request.json())  # (1)
-    except ValidationError as e:  # pragma: no cover
+        run_input = AGUIAdapter.build_run_input(await request.body())  # (1)
+    except ValidationError as e:
         return Response(
             content=json.dumps(e.json()),
             media_type='application/json',
             status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
         )
 
     adapter = AGUIAdapter(agent=agent, run_input=run_input, accept=accept)
-    events = adapter.run_stream() # (2)
+    event_stream = adapter.run_stream() # (2)
 
-    return StreamingResponse(adapter.encode_stream(events), media_type=accept) # (3)
+    sse_event_stream = adapter.encode_stream(event_stream)
+    return StreamingResponse(sse_event_stream, media_type=accept) # (3)
 ```
 
-1. You can also use the [`AGUIAdapter.from_request()`][pydantic_ai.ui.ag_ui.AGUIAdapter.from_request] class method to build an adapter directly from a request.
-2. You can also use the [`AGUIAdapter.run_stream_native()`][pydantic_ai.ui.ag_ui.AGUIAdapter.run_stream_native] method to run the agent and return a stream of Pydantic AI events instead of AG-UI events. These can then be transformed into AG-UI events using the [`AGUIAdapter.transform_stream()`][pydantic_ai.ui.ag_ui.AGUIAdapter.transform_stream] method.
-3. The [`AGUIAdapter.encode_stream()`][pydantic_ai.ui.ag_ui.AGUIAdapter.encode_stream] method encodes the stream of AG-UI events as strings according to the accept header value. You can also use the [`AGUIAdapter.streaming_response()`][pydantic_ai.ui.ag_ui.AGUIAdapter.streaming_response] method to generate a streaming response directly from the AG-UI event stream returned by `run_stream()`.
+1. [`AGUIAdapter.build_run_input()`][pydantic_ai.ui.ag_ui.AGUIAdapter.build_run_input] takes the request body as bytes and returns an AG-UI [`RunAgentInput`](https://docs.ag-ui.com/sdk/python/core/types#runagentinput) object. You can also use the [`AGUIAdapter.from_request()`][pydantic_ai.ui.ag_ui.AGUIAdapter.from_request] class method to build an adapter directly from a request.
+2. [`AGUIAdapter.run_stream()`][pydantic_ai.ui.ag_ui.AGUIAdapter.run_stream] runs the agent and returns a stream of AG-UI events. It supports the same optional arguments as [`Agent.run_stream_events()`](../agents.md#running-agents), including `deps`. You can also use [`AGUIAdapter.run_stream_native()`][pydantic_ai.ui.ag_ui.AGUIAdapter.run_stream_native] to run the agent and return a stream of Pydantic AI events instead, which can then be transformed into AG-UI events using [`AGUIAdapter.transform_stream()`][pydantic_ai.ui.ag_ui.AGUIAdapter.transform_stream].
+3. [`AGUIAdapter.encode_stream()`][pydantic_ai.ui.ag_ui.AGUIAdapter.encode_stream] encodes the stream of AG-UI events as strings according to the accept header value. You can also use [`AGUIAdapter.streaming_response()`][pydantic_ai.ui.ag_ui.AGUIAdapter.streaming_response] to generate a streaming response directly from the AG-UI event stream returned by `run_stream()`.
 
 Since `app` is an ASGI application, it can be used with any ASGI server:
 
@@ -167,7 +169,7 @@ The integration provides full support for
 real-time synchronization between agents and frontend applications.
 
 In the example below we have document state which is shared between the UI and
-server using the [`StateDeps`][pydantic_ai.ag_ui.StateDeps] [dependencies type](./dependencies.md) that can be used to automatically
+server using the [`StateDeps`][pydantic_ai.ag_ui.StateDeps] [dependencies type](../dependencies.md) that can be used to automatically
 validate state contained in [`RunAgentInput.state`](https://docs.ag-ui.com/sdk/js/core/types#runagentinput) using a Pydantic `BaseModel` specified as a generic parameter.
 
 !!! note "Custom dependencies type with AG-UI state"
@@ -182,7 +184,7 @@ from pydantic import BaseModel
 
 from pydantic_ai import Agent
 from pydantic_ai.ui import StateDeps
-from pydantic_ai.ui.ag_ui import AGUIApp
+from pydantic_ai.ui.ag_ui.app import AGUIApp
 
 
 class DocumentState(BaseModel):
@@ -213,7 +215,7 @@ user experiences with frontend user interfaces.
 ### Events
 
 Pydantic AI tools can send [AG-UI events](https://docs.ag-ui.com/concepts/events) simply by returning a
-[`ToolReturn`](tools-advanced.md#advanced-tool-returns) object with a
+[`ToolReturn`](../tools-advanced.md#advanced-tool-returns) object with a
 [`BaseEvent`](https://docs.ag-ui.com/sdk/python/core/events#baseevent) (or a list of events) as `metadata`,
 which allows for custom events and state updates.
 
@@ -223,7 +225,7 @@ from pydantic import BaseModel
 
 from pydantic_ai import Agent, RunContext, ToolReturn
 from pydantic_ai.ui import StateDeps
-from pydantic_ai.ui.ag_ui import AGUIApp
+from pydantic_ai.ui.ag_ui.app import AGUIApp
 
 
 class DocumentState(BaseModel):

docs/ui/overview.md

@@ -0,0 +1,84 @@
+# UI Event Streams
+
+If you're building a chat app or other interactive frontend for an AI agent, your backend will need to receive agent run input (like a chat message or full message history) from the frontend, and will need to stream the [agent's events](../agents.md#streaming-all-events) (like text, thinking, and tool calls) to the frontend so that the user knows what's happening in real time.
+
+While your frontend could use Pydantic AI's [`ModelRequest`s](../message-history.md) and [`AgentStreamEvent`s][pydantic_ai.messages.AgentStreamEvent] directly, you'll typically want to use a UI event stream protocol that's natively supported by your frontend framework.
+
+Pydantic AI natively supports two UI event stream protocols:
+
+- [Agent User Interaction (AG-UI) Protocol](./ag-ui.md)
+- [Vercel AI Data Stream Protocol](./vercel-ai.md)
+
+These integrations are implemented as subclasses of the abstract [`UIAdapter`][pydantic_ai.ui.UIAdapter] class, so they also serve as a reference for integrating with other UI event stream protocols.
+
+## Usage
+
+The protocol-specific [`UIAdapter`][pydantic_ai.ui.UIAdapter] subclass (i.e. [`AGUIAdapter`][pydantic_ai.ui.ag_ui.AGUIAdapter] or [`VercelAIAdapter`][pydantic_ai.ui.vercel_ai.VercelAIAdapter]) is responsible for transforming agent run input received from the frontend into arguments for [`Agent.run_stream_events()`](../agents.md#running-agents), running the agent, and then transforming Pydantic AI events into protocol-specific events. The event stream transformation is handled by a protocol-specific [`UIEventStream`][pydantic_ai.ui.UIEventStream] subclass, but you typically won't use this directly.
+
+If you're using a Starlette-based web framework like FastAPI, you can use the [`UIAdapter.dispatch_request()`][pydantic_ai.ui.UIAdapter.dispatch_request] class method from an endpoint function to directly handle a request and return a streaming response of protocol-specific events. Besides the request, this method takes the agent and supports the same optional arguments as [`Agent.run_stream_events()`](../agents.md#running-agents), including `deps`.
+
+!!! note
+    These examples use the `VercelAIAdapter`, but the same patterns apply to all `UIAdapter` subclasses.
+
+```py {title="dispatch_request.py"}
+from fastapi import FastAPI
+from starlette.requests import Request
+from starlette.responses import Response
+
+from pydantic_ai import Agent
+from pydantic_ai.ui.vercel_ai import VercelAIAdapter
+
+agent = Agent('openai:gpt-5')
+
+app = FastAPI()
+
+@app.post('/chat')
+async def chat(request: Request) -> Response:
+    return await VercelAIAdapter.dispatch_request(request, agent=agent)
+```
+
+If you're using a web framework not based on Starlette (e.g. Django or Flask) or want fine-grained control over the input or output, you can create and use a `UIAdapter` instance directly.
+
+!!! note
+    This example uses FastAPI, but can be modified to work with any web framework.
+
+```py {title="run_stream.py"}
+import json
+from http import HTTPStatus
+
+from fastapi import FastAPI
+from fastapi.requests import Request
+from fastapi.responses import Response, StreamingResponse
+from pydantic import ValidationError
+
+from pydantic_ai import Agent
+from pydantic_ai.ui import SSE_CONTENT_TYPE
+from pydantic_ai.ui.vercel_ai import VercelAIAdapter
+
+agent = Agent('openai:gpt-5')
+
+app = FastAPI()
+
+
+@app.post('/chat')
+async def chat(request: Request) -> Response:
+    accept = request.headers.get('accept', SSE_CONTENT_TYPE)
+    try:
+        run_input = VercelAIAdapter.build_run_input(await request.body())  # (1)
+    except ValidationError as e:
+        return Response(
+            content=json.dumps(e.json()),
+            media_type='application/json',
+            status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
+        )
+
+    adapter = VercelAIAdapter(agent=agent, run_input=run_input, accept=accept)
+    event_stream = adapter.run_stream() # (2)
+
+    sse_event_stream = adapter.encode_stream(event_stream)
+    return StreamingResponse(sse_event_stream, media_type=accept) # (3)
+```
+
+1. [`UIAdapter.build_run_input()`][pydantic_ai.ui.UIAdapter.build_run_input] takes the request body as bytes and returns a protocol-specific run input object. You can also use the [`UIAdapter.from_request()`][pydantic_ai.ui.UIAdapter.from_request] class method to build an adapter directly from a request.
+2. [`UIAdapter.run_stream()`][pydantic_ai.ui.UIAdapter.run_stream] runs the agent and returns a stream of protocol-specific events. It supports the same optional arguments as [`Agent.run_stream_events()`](../agents.md#running-agents), including `deps`. You can also use [`UIAdapter.run_stream_native()`][pydantic_ai.ui.UIAdapter.run_stream_native] to run the agent and return a stream of Pydantic AI events instead, which can then be transformed into protocol-specific events using [`UIAdapter.transform_stream()`][pydantic_ai.ui.UIAdapter.transform_stream].
+3. [`UIAdapter.encode_stream()`][pydantic_ai.ui.UIAdapter.encode_stream] encodes the stream of protocol-specific events as strings according to the accept header value. You can also use [`UIAdapter.streaming_response()`][pydantic_ai.ui.UIAdapter.streaming_response] to generate a streaming response directly from the protocol-specific event stream returned by `run_stream()`.

docs/ui/vercel-ai.md

@@ -92,7 +92,10 @@ nav:
         - Temporal: durable_execution/temporal.md
         - DBOS: durable_execution/dbos.md
         - Prefect: durable_execution/prefect.md
-      - Agent-User Interaction (AG-UI): ag-ui.md
+      - UI Event Streams:
+        - Overview: ui/overview.md
+        - AG-UI: ui/ag-ui.md
+        - Vercel AI: ui/vercel-ai.md
       - Agent2Agent (A2A): a2a.md
 
   - Related Packages:
@@ -160,6 +163,7 @@ nav:
           - api/providers.md
           - api/retries.md
           - api/run.md
+          - api/ui.md
       - pydantic_evals:
           - api/pydantic_evals/dataset.md
           - api/pydantic_evals/evaluators.md

mkdocs.yml

@@ -1040,7 +1040,7 @@ def to_ag_ui(
         uvicorn app:app --host 0.0.0.0 --port 8000
         ```
 
-        See [AG-UI docs](../ag-ui.md) for more information.
+        See [AG-UI docs](../ui/ag-ui.md) for more information.
 
         Args:
             output_type: Custom output type to use for this run, `output_type` may only be used if the agent has