Add convenience functions to handle AG-UI requests with request-specific deps (#2397)

Author: DouweM

docs/ag-ui.md

@@ -4,17 +4,15 @@ The [Agent User Interaction (AG-UI) Protocol](https://docs.ag-ui.com/introductio
 [CopilotKit](https://webflow.copilotkit.ai/blog/introducing-ag-ui-the-protocol-where-agents-meet-users)
 team that standardises how frontend applications communicate with AI agents, with support for streaming, frontend tools, shared state, and custom events.
 
-Any Pydantic AI agent can be exposed as an AG-UI server using the [`Agent.to_ag_ui()`][pydantic_ai.Agent.to_ag_ui] convenience method.
-
 !!! note
     The AG-UI integration was originally built by the team at [Rocket Science](https://www.rocketscience.gg/) and contributed in collaboration with the Pydantic AI and CopilotKit teams. Thanks Rocket Science!
 
 ## Installation
 
 The only dependencies are:
 
-- [ag-ui-protocol](https://docs.ag-ui.com/introduction): to provide the AG-UI types and encoder
-- [starlette](https://www.starlette.io): to expose the AG-UI server as an [ASGI application](https://asgi.readthedocs.io/en/latest/)
+- [ag-ui-protocol](https://docs.ag-ui.com/introduction): to provide the AG-UI types and encoder.
+- [starlette](https://www.starlette.io): to handle [ASGI](https://asgi.readthedocs.io/en/latest/) requests from a framework like FastAPI.
 
 You can install Pydantic AI with the `ag-ui` extra to ensure you have all the
 required AG-UI dependencies:
@@ -31,9 +29,95 @@ To run the examples you'll also need:
 pip/uv-add uvicorn
 ```
 
-## Quick start
+## Usage
+
+There are three ways to run a Pydantic AI agent based on AG-UI run input with streamed AG-UI events as output, from most to least flexible. If you're using a Starlette-based web framework like FastAPI, you'll typically want to use the second method.
+
+1. [`run_ag_ui()`][pydantic_ai.ag_ui.run_ag_ui] takes an agent and an AG-UI [`RunAgentInput`](https://docs.ag-ui.com/sdk/python/core/types#runagentinput) object, and returns a stream of AG-UI events encoded as strings. It also takes optional [`Agent.iter()`][pydantic_ai.Agent.iter] arguments including `deps`. Use this if you're using a web framework not based on Starlette (e.g. Django or Flask) or want to modify the input or output some way.
+2. [`handle_ag_ui_request()`][pydantic_ai.ag_ui.handle_ag_ui_request] takes an agent and a Starlette request (e.g. from FastAPI) coming from an AG-UI frontend, and returns a streaming Starlette response of AG-UI events that you can return directly from your endpoint. It also takes optional [`Agent.iter()`][pydantic_ai.Agent.iter] arguments including `deps`, that you can vary for each request (e.g. based on the authenticated user).
+3. [`Agent.to_ag_ui()`][pydantic_ai.Agent.to_ag_ui] returns an ASGI application that handles every AG-UI request by running the agent. It also takes optional [`Agent.iter()`][pydantic_ai.Agent.iter] arguments including `deps`, but these will be the same for each request, with the exception of the AG-UI state that's injected as described under [state management](#state-management). This ASGI app can be [mounted](https://fastapi.tiangolo.com/advanced/sub-applications/) at a given path in an existing FastAPI app.
+
+### Handle run input and output directly
+
+This example uses [`run_ag_ui()`][pydantic_ai.ag_ui.run_ag_ui] and performs its own request parsing and response generation.
+This can be modified to work with any web framework.
+
+```py {title="run_ag_ui.py"}
+from ag_ui.core import RunAgentInput
+from fastapi import FastAPI
+from http import HTTPStatus
+from fastapi.requests import Request
+from fastapi.responses import Response, StreamingResponse
+from pydantic import ValidationError
+import json
+
+from pydantic_ai import Agent
+from pydantic_ai.ag_ui import run_ag_ui, SSE_CONTENT_TYPE
+
+
+agent = Agent('openai:gpt-4.1', instructions='Be fun!')
+
+app = FastAPI()
+
+
+@app.post("/")
+async def run_agent(request: Request) -> Response:
+    accept = request.headers.get('accept', SSE_CONTENT_TYPE)
+    try:
+        run_input = RunAgentInput.model_validate(await request.json())
+    except ValidationError as e:  # pragma: no cover
+        return Response(
+            content=json.dumps(e.json()),
+            media_type='application/json',
+            status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
+        )
+
+    event_stream = run_ag_ui(agent, run_input, accept=accept)
+
+    return StreamingResponse(event_stream, media_type=accept)
+```
+
+Since `app` is an ASGI application, it can be used with any ASGI server:
+
+```shell
+uvicorn run_ag_ui:app
+```
+
+This will expose the agent as an AG-UI server, and your frontend can start sending requests to it.
+
+### Handle a Starlette request
+
+This example uses [`handle_ag_ui_request()`][pydantic_ai.ag_ui.run_ag_ui] to directly handle a FastAPI request and return a response. Something analogous to this will work with any Starlette-based web framework.
+
+```py {title="handle_ag_ui_request.py"}
+from fastapi import FastAPI
+from starlette.requests import Request
+from starlette.responses import Response
+
+from pydantic_ai import Agent
+from pydantic_ai.ag_ui import handle_ag_ui_request
+
+
+agent = Agent('openai:gpt-4.1', instructions='Be fun!')
+
+app = FastAPI()
+
+@app.post("/")
+async def run_agent(request: Request) -> Response:
+    return await handle_ag_ui_request(agent, request)
+```
+
+Since `app` is an ASGI application, it can be used with any ASGI server:
 
-To expose a Pydantic AI agent as an AG-UI server, you can use the [`Agent.to_ag_ui()`][pydantic_ai.Agent.to_ag_ui] method:
+```shell
+uvicorn handle_ag_ui_request:app
+```
+
+This will expose the agent as an AG-UI server, and your frontend can start sending requests to it.
+
+### Stand-alone ASGI app
+
+This example uses [`Agent.to_ag_ui()`][pydantic_ai.Agent.to_ag_ui] to turn the agent into a stand-alone ASGI application:
 
 ```py {title="agent_to_ag_ui.py" py="3.10" hl_lines="4"}
 from pydantic_ai import Agent
@@ -45,13 +129,11 @@ app = agent.to_ag_ui()
 Since `app` is an ASGI application, it can be used with any ASGI server:
 
 ```shell
-uvicorn agent_to_ag_ui:app --host 0.0.0.0 --port 9000
+uvicorn agent_to_ag_ui:app
 ```
 
 This will expose the agent as an AG-UI server, and your frontend can start sending requests to it.
 
-The `to_ag_ui()` method accepts the same arguments as the [`Agent.iter()`][pydantic_ai.agent.Agent.iter] method as well as arguments that let you configure the [Starlette](https://www.starlette.io)-based ASGI app.
-
 ## Design
 
 The Pydantic AI AG-UI integration supports all features of the spec:
@@ -61,14 +143,11 @@ The Pydantic AI AG-UI integration supports all features of the spec:
 - [State Management](https://docs.ag-ui.com/concepts/state)
 - [Tools](https://docs.ag-ui.com/concepts/tools)
 
-The app 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 Pydantic AI types and passed to the
-agent which then process the request.
+The integration receives messages in the form of a
+[`RunAgentInput`](https://docs.ag-ui.com/sdk/python/core/types#runagentinput) object
+that describes the details of the requested agent run including message history, state, and available tools.
 
-Events from the agent, including tool calls, are converted to AG-UI events and
-streamed back to the caller as Server-Sent Events (SSE).
+These are converted to Pydantic AI types and passed to the agent's run method. Events from the agent, including tool calls, are converted 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 Pydantic AI
 server, depending on the tools and events needed.
@@ -77,7 +156,7 @@ server, depending on the tools and events needed.
 
 ### State management
 
-The adapter provides full support for
+The integration 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.