feat: AG-UI adapter

AG-UI adapter enabling integration with the AG-UI protocol via
the Agent.to_ag_ui() method.

This includes a full example for all features in the AG-UI dojo.

Fixes: ag-ui-protocol/ag-ui/issues/5

Author: stevenh

docs/ag-ui.md

@@ -0,0 +1,313 @@
+# Agent User Interaction (AG-UI) Protocol
+
+The [Agent User Interaction (AG-UI) Protocol](https://docs.ag-ui.com/introduction)
+is an open standard introduced by the
+[CopilotKit](https://webflow.copilotkit.ai/blog/introducing-ag-ui-the-protocol-where-agents-meet-users)
+team that standardises how frontend applications connect to AI agents through
+an open protocol. Think of it as a universal translator for AI-driven systems
+no matter what language an agent speaks: AG-UI ensures fluent communication.
+
+The team at [Rocket Science](https://www.rocketscience.gg/), contributed the
+[pydantic-ai-ag-ui](#ag-ui-adapter) package to make it easy to implement the
+AG-UI protocol with PydanticAI agents.
+
+This also includes an [`Agent.to_ag_ui`][pydantic_ai.Agent.to_ag_ui] convenience
+method which simplifies the creation of [`Adapter`][pydantic_ai_ag_ui.Adapter]
+for PydanticAI agents, which can then be used by as part of a
+[fastapi](https://fastapi.tiangolo.com/) app.
+
+## AG-UI Adapter
+
+The [Adapter][pydantic_ai_ag_ui.Adapter] class is an adapter between
+PydanticAI agents and the AG-UI protocol written in Python. It provides support
+for all aspects of spec including:
+
+- [Events](https://docs.ag-ui.com/concepts/events)
+- [Messages](https://docs.ag-ui.com/concepts/messages)
+- [State Management](https://docs.ag-ui.com/concepts/state)
+- [Tools](https://docs.ag-ui.com/concepts/tools)
+
+Let's have a quick look at how to use it:
+
+### Installation
+
+[Adapter][pydantic_ai_ag_ui.Adapter] is available on PyPI as
+[`pydantic-ai-ag-ui`](https://pypi.org/project/pydantic-ai-ag-ui/) so installation is as
+simple as:
+
+```bash
+pip/uv-add pydantic-ai-ag-ui
+```
+
+The only dependencies are:
+
+- [ag-ui-protocol](https://docs.ag-ui.com/introduction): to provide the AG-UI
+  types and encoder.
+- [pydantic](https://pydantic.dev): to validate the request/response messages
+- [pydantic-ai](https://ai.pydantic.dev/): to provide the agent framework
+
+To run the examples you'll also need:
+
+- [fastapi](https://fastapi.tiangolo.com/): to provide ASGI compatible server
+
+```bash
+pip/uv-add 'fastapi'
+```
+
+You can install PydanticAI with the `ag-ui` extra to include **Adapter**:
+
+```bash
+pip/uv-add 'pydantic-ai-slim[ag-ui]'
+```
+
+### Quick start
+
+```py {title="agent_to_ag_ui.py" py="3.10" hl_lines="17-28"}
+"""Basic example for AG-UI with FastAPI and Pydantic AI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
+
+from fastapi import FastAPI, Header
+from fastapi.responses import StreamingResponse
+from pydantic_ai_ag_ui import SSE_CONTENT_TYPE
+
+from pydantic_ai import Agent
+
+if TYPE_CHECKING:
+    from ag_ui.core import RunAgentInput
+
+agent = Agent('openai:gpt-4.1', instructions='Be fun!')
+adapter = agent.to_ag_ui()
+app = FastAPI(title='AG-UI Endpoint')
+
+
+@app.post('/')
+async def root(
+    input_data: RunAgentInput, accept: Annotated[str, Header()] = SSE_CONTENT_TYPE
+) -> StreamingResponse:
+    return StreamingResponse(
+        adapter.run(input_data, accept),
+        media_type=SSE_CONTENT_TYPE,
+    )
+```
+
+You can run the example with:
+
+```shell
+uvicorn agent_to_ag_ui:app --host 0.0.0.0 --port 8000
+```
+
+This will expose the agent as an AG-UI server, and you can start sending
+requests to it.
+
+### Design
+
+The adapter receives messages in the form of a
+[`RunAgentInput`](https://docs.ag-ui.com/sdk/js/core/types#runagentinput)
+which describes the details of a request being passed to the agent including
+messages and state. These are then converted to PydanticAI types, passed to the
+agent which then process the request.
+
+Results from the agent are converted from PydanticAI types to AG-UI events and
+streamed back to the caller as Server-Sent Events (SSE).
+
+A user request may require multiple round trips between client UI and PydanticAI
+server, depending on the tools and events needed.
+
+[Adapter][pydantic_ai_ag_ui.Adapter] can be used with any ASGI server.
+
+### Features
+
+To expose a PydanticAI agent as an AG-UI server including state support, you can
+use the [`to_ag_ui`][pydantic_ai.agent.Agent.to_ag_ui] method in combination
+with [fastapi](https://fastapi.tiangolo.com/).
+
+In the example below we have document state which is shared between the UI and
+server using the [`StateDeps`][pydantic_ai_ag_ui.StateDeps] which implements the
+[`StateHandler`][pydantic_ai_ag_ui.StateHandler] that can be used to automatically
+decode state contained in [`RunAgentInput.state`](https://docs.ag-ui.com/sdk/js/core/types#runagentinput)
+when processing requests.
+
+#### State management
+
+The adapter provides full support for
+[AG-UI state management](https://docs.ag-ui.com/concepts/state), which enables
+real-time synchronization between agents and frontend applications.
+
+```python {title="ag_ui_state.py" py="3.10" hl_lines="18-40"}
+"""State example for AG-UI with FastAPI and Pydantic AI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
+
+from fastapi import FastAPI, Header
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from pydantic_ai_ag_ui import SSE_CONTENT_TYPE, StateDeps
+
+from pydantic_ai import Agent
+
+if TYPE_CHECKING:
+    from ag_ui.core import RunAgentInput
+
+
+class DocumentState(BaseModel):
+    """State for the document being written."""
+
+    document: str
+
+
+agent = Agent(
+    'openai:gpt-4.1',
+    instructions='Be fun!',
+    deps_type=StateDeps[DocumentState],
+)
+adapter = agent.to_ag_ui()
+app = FastAPI(title='AG-UI Endpoint')
+
+
+@app.post('/')
+async def root(
+    input_data: RunAgentInput, accept: Annotated[str, Header()] = SSE_CONTENT_TYPE
+) -> StreamingResponse:
+    return StreamingResponse(
+        adapter.run(input_data, accept, deps=StateDeps(state_type=DocumentState)),
+        media_type=SSE_CONTENT_TYPE,
+    )
+```
+
+Since `app` is an ASGI application, it can be used with any ASGI server.
+
+```bash
+uvicorn agent_to_ag_ui:app --host 0.0.0.0 --port 8000
+```
+
+Since the goal of [`to_ag_ui`][pydantic_ai.agent.Agent.to_ag_ui] is to be a
+convenience method, it accepts the same arguments as the
+[`Adapter`][pydantic_ai_ag_ui.Adapter] constructor.
+
+#### Tools
+
+AG-UI tools are seamlessly provided to the PydanticAI agent, enabling rich
+use experiences with frontend user interfaces.
+
+#### Events
+
+The adapter provides the ability for PydanticAI tools to send
+[AG-UI events](https://docs.ag-ui.com/concepts/events) simply by defining a tool
+which returns a type based off
+[`BaseEvent`](https://docs.ag-ui.com/sdk/js/core/events#baseevent) this allows
+for custom events and state updates.
+
+```python {title="ag_ui_tool_events.py" py="3.10" hl_lines="34-55"}
+"""Tool events example for AG-UI with FastAPI and Pydantic AI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
+
+from ag_ui.core import CustomEvent, EventType, StateSnapshotEvent
+from fastapi import FastAPI, Header
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from pydantic_ai_ag_ui import SSE_CONTENT_TYPE, StateDeps
+
+from pydantic_ai import Agent, RunContext
+
+if TYPE_CHECKING:
+    from ag_ui.core import RunAgentInput
+
+
+class DocumentState(BaseModel):
+    """State for the document being written."""
+
+    document: str
+
+
+agent = Agent(
+    'openai:gpt-4.1',
+    instructions='Be fun!',
+    deps_type=StateDeps[DocumentState],
+)
+adapter = agent.to_ag_ui()
+app = FastAPI(title='AG-UI Endpoint')
+
+
+@agent.tool
+def update_state(ctx: RunContext[StateDeps[DocumentState]]) -> StateSnapshotEvent:
+    return StateSnapshotEvent(
+        type=EventType.STATE_SNAPSHOT,
+        snapshot=ctx.deps.state,
+    )
+
+
+@agent.tool_plain
+def custom_events() -> list[CustomEvent]:
+    return [
+        CustomEvent(
+            type=EventType.CUSTOM,
+            name='count',
+            value=1,
+        ),
+        CustomEvent(
+            type=EventType.CUSTOM,
+            name='count',
+            value=2,
+        ),
+    ]
+
+
+@app.post('/')
+async def root(
+    input_data: RunAgentInput, accept: Annotated[str, Header()] = SSE_CONTENT_TYPE
+) -> StreamingResponse:
+    return StreamingResponse(
+        adapter.run(input_data, accept, deps=StateDeps(state_type=DocumentState)),
+        media_type=SSE_CONTENT_TYPE,
+    )
+```
+
+### Examples
+
+For more examples of how to use [`Adapter`][pydantic_ai_ag_ui.Adapter] see
+[`pydantic_ai_ag_ui_examples`](https://github.com/pydantic/pydantic-ai/tree/main/examples/pydantic_ai_ag_ui_examples),
+which includes working server for the with the
+[AG-UI Dojo](https://docs.ag-ui.com/tutorials/debugging#the-ag-ui-dojo) which
+can be run from a clone of the repo or with the `pydantic-ai-examples` package
+installed with either of the following:
+
+```bash
+pip/uv-add pydantic-ai-examples
+```
+
+Direct, which supports command line flags:
+
+```shell
+python -m pydantic_ai_ag_ui_examples.dojo_server --help
+usage: dojo_server.py [-h] [--port PORT] [--reload] [--no-reload] [--log-level {critical,error,warning,info,debug,trace}]
+
+PydanticAI AG-UI Dojo server
+
+options:
+  -h, --help            show this help message and exit
+  --port PORT, -p PORT  Port to run the server on (default: 9000)
+  --reload              Enable auto-reload (default: True)
+  --no-reload           Disable auto-reload
+  --log-level {critical,error,warning,info,debug,trace}
+                        Agent log level (default: info)
+```
+
+Run with adapter debug logging:
+
+```shell
+python -m pydantic_ai_ag_ui_examples.dojo_server --log-level debug
+```
+
+Using uvicorn:
+
+```shell
+uvicorn pydantic_ai_ag_ui_examples.dojo_server:app --port 9000
+```

docs/api/pydantic_ai_ag_ui.md

@@ -0,0 +1,3 @@
+# `pydantic_ai_ag_ui`
+
+::: pydantic_ai_ag_ui

docs/install.md

@@ -56,6 +56,7 @@ pip/uv-add "pydantic-ai-slim[openai]"
 * `cohere` - installs `cohere` [PyPI ↗](https://pypi.org/project/cohere){:target="_blank"}
 * `duckduckgo` - installs `duckduckgo-search` [PyPI ↗](https://pypi.org/project/duckduckgo-search){:target="_blank"}
 * `tavily` - installs `tavily-python` [PyPI ↗](https://pypi.org/project/tavily-python){:target="_blank"}
+* `ag-ui` - installs `pydantic-ai-ag-ui` [PyPI ↗](https://pypi.org/project/pydantic-ai-ag-ui){:target="_blank"}
 
 See the [models](models/index.md) documentation for information on which optional dependencies are required for each model.