docs(ag-ui): improve layout and structure

Author: stevenh

docs/ag-ui.md

@@ -14,10 +14,55 @@ 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. Let's have a quick look at how to
-use it:
+[fastapi](https://fastapi.tiangolo.com/) app.
 
-```py {title="agent_to_ag_ui.py" py="3.10" hl_lines="17-27"}
+## 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
@@ -33,9 +78,9 @@ from pydantic_ai import Agent
 if TYPE_CHECKING:
     from ag_ui.core import RunAgentInput
 
-app = FastAPI(title='AG-UI Endpoint')
 agent = Agent('openai:gpt-4.1', instructions='Be fun!')
 adapter = agent.to_ag_ui()
+app = FastAPI(title='AG-UI Endpoint')
 
 
 @app.post('/')
@@ -57,17 +102,6 @@ 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.
 
-## 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)
-
 ### Design
 
 The adapter receives messages in the form of a
@@ -84,42 +118,11 @@ server, depending on the tools and events needed.
 
 [Adapter][pydantic_ai_ag_ui.Adapter] can be used with any ASGI server.
 
-### 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]'
-```
-
-### Usage
+### 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.
+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
@@ -133,7 +136,7 @@ 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-21,28,38"}
+```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
@@ -157,13 +160,13 @@ class DocumentState(BaseModel):
     document: str
 
 
-app = FastAPI(title='AG-UI Endpoint')
 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('/')
@@ -199,7 +202,7 @@ 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="35-56"}
+```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
@@ -224,13 +227,13 @@ class DocumentState(BaseModel):
     document: str
 
 
-app = FastAPI(title='AG-UI Endpoint')
 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

pydantic_ai_ag_ui/README.md

@@ -1,4 +1,4 @@
-# AG-UI Adapter
+# PydanticAI AG-UI Adapter
 
 [![CI](https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml?query=branch%3Amain)
 [![Coverage](https://coverage-badge.samuelcolvin.workers.dev/pydantic/pydantic-ai.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/pydantic/pydantic-ai)