Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit828d92d

Browse files
committed
feat: AG-UI adapter
AG-UI adapter enabling integration with the AG-UI protocol viathe 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
1 parent4193208 commit828d92d

27 files changed

+2970
-34
lines changed

‎docs/ag-ui.md

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
#Agent User Interaction (AG-UI) Protocol
2+
3+
The[Agent User Interaction (AG-UI) Protocol](https://docs.ag-ui.com/introduction)
4+
is an open standard introduced by the
5+
[CopilotKit](https://webflow.copilotkit.ai/blog/introducing-ag-ui-the-protocol-where-agents-meet-users)
6+
team that standardises how frontend applications connect to AI agents through
7+
an open protocol. Think of it as a universal translator for AI-driven systems
8+
no matter what language an agent speaks: AG-UI ensures fluent communication.
9+
10+
The team at[Rocket Science](https://www.rocketscience.gg/), contributed the
11+
initial version of AG-UI integration to make it easy to implement the AG-UI
12+
protocol with PydanticAI agents.
13+
14+
This also includes an[`Agent.to_ag_ui`][pydantic_ai.Agent.to_ag_ui] convenience
15+
method which simplifies the creation of[`AGUIApp`][pydantic_ai.ag_ui.AGUIApp]
16+
for PydanticAI agents, which is built on top of[Starlette](https://www.starlette.io/),
17+
meaning it's fully compatible with any ASGI server.
18+
19+
##Installation
20+
21+
The only dependencies are:
22+
23+
-[ag-ui-protocol](https://docs.ag-ui.com/introduction): to provide the AG-UI
24+
types and encoder.
25+
-[pydantic](https://pydantic.dev): to validate the request/response messages
26+
-[pydantic-ai](https://ai.pydantic.dev/): to provide the agent framework
27+
28+
To run the examples you'll also need:
29+
30+
-[uvicorn](https://www.uvicorn.org/) or another ASGI compatible server
31+
32+
```bash
33+
pip/uv-add'uvicorn'
34+
```
35+
36+
You can install PydanticAI with the`ag-ui` extra to ensure you have all the
37+
required AG-UI dependencies:
38+
39+
```bash
40+
pip/uv-add'pydantic-ai-slim[ag-ui]'
41+
```
42+
43+
##Quick start
44+
45+
```py {title="agent_to_ag_ui.py" py="3.10" hl_lines="17-28"}
46+
"""Basic example for AG-UI with FastAPI and Pydantic AI."""
47+
48+
from__future__import annotations
49+
50+
from pydantic_aiimport Agent
51+
52+
agent= Agent('openai:gpt-4.1',instructions='Be fun!')
53+
app= agent.to_ag_ui()
54+
```
55+
56+
You can run the example with:
57+
58+
```shell
59+
uvicorn agent_to_ag_ui:app --host 0.0.0.0 --port 8000
60+
```
61+
62+
This will expose the agent as an AG-UI server, and you can start sending
63+
requests to it.
64+
65+
##Design
66+
67+
The solution provides and adapter layer between the AG-UI protocol and
68+
PydanticAI agents written in Python, including support for all aspects of spec
69+
including:
70+
71+
-[Events](https://docs.ag-ui.com/concepts/events)
72+
-[Messages](https://docs.ag-ui.com/concepts/messages)
73+
-[State Management](https://docs.ag-ui.com/concepts/state)
74+
-[Tools](https://docs.ag-ui.com/concepts/tools)
75+
76+
The adapter receives messages in the form of a
77+
[`RunAgentInput`](https://docs.ag-ui.com/sdk/js/core/types#runagentinput)
78+
which describes the details of a request being passed to the agent including
79+
messages and state. These are then converted to PydanticAI types, passed to the
80+
agent which then process the request.
81+
82+
Results from the agent are converted from PydanticAI types to AG-UI events and
83+
streamed back to the caller as Server-Sent Events (SSE).
84+
85+
A user request may require multiple round trips between client UI and PydanticAI
86+
server, depending on the tools and events needed.
87+
88+
This is exposed via the[AGUIApp][pydantic_ai.ag_ui.AGUIApp] which is slim
89+
wrapper around[Starlette](https://www.starlette.io/) providing easy access to
90+
run a PydanticAI server with AG-UI support with any ASGI server.
91+
92+
##Features
93+
94+
To expose a PydanticAI agent as an AG-UI server including state support, you
95+
use the[`to_ag_ui`][pydantic_ai.agent.Agent.to_ag_ui] method create an ASGI
96+
compatible server.
97+
98+
In the example below we have document state which is shared between the UI and
99+
server using the[`StateDeps`][pydantic_ai.ag_ui.StateDeps] which implements the
100+
[`StateHandler`][pydantic_ai.ag_ui.StateHandler] that can be used to automatically
101+
decode state contained in[`RunAgentInput.state`](https://docs.ag-ui.com/sdk/js/core/types#runagentinput)
102+
when processing requests.
103+
104+
###State management
105+
106+
The adapter provides full support for
107+
[AG-UI state management](https://docs.ag-ui.com/concepts/state), which enables
108+
real-time synchronization between agents and frontend applications.
109+
110+
```python {title="ag_ui_state.py" py="3.10" hl_lines="18-40"}
111+
"""State example for AG-UI with FastAPI and Pydantic AI."""
112+
113+
from__future__import annotations
114+
115+
from pydanticimport BaseModel
116+
117+
from pydantic_aiimport Agent
118+
from pydantic_ai.ag_uiimport StateDeps
119+
120+
121+
classDocumentState(BaseModel):
122+
"""State for the document being written."""
123+
124+
document:str=''
125+
126+
127+
agent= Agent(
128+
'openai:gpt-4.1',
129+
instructions='Be fun!',
130+
deps_type=StateDeps[DocumentState],
131+
)
132+
app= agent.to_ag_ui(deps=StateDeps(DocumentState()))
133+
```
134+
135+
Since`app` is an ASGI application, it can be used with any ASGI server e.g.
136+
137+
```bash
138+
uvicorn agent_to_ag_ui:app --host 0.0.0.0 --port 8000
139+
```
140+
141+
Since the goal of[`to_ag_ui`][pydantic_ai.agent.Agent.to_ag_ui] is to be a
142+
convenience method, it accepts the same a combination of the arguments require
143+
for:
144+
145+
-[`AGUIApp`][pydantic_ai.ag_ui.AGUIApp] constructor
146+
-[`Agent.iter`][pydantic_ai.agent.Agent.iter] method
147+
148+
###Tools
149+
150+
AG-UI tools are seamlessly provided to the PydanticAI agent, enabling rich
151+
use experiences with frontend user interfaces.
152+
153+
###Events
154+
155+
The adapter provides the ability for PydanticAI tools to send
156+
[AG-UI events](https://docs.ag-ui.com/concepts/events) simply by defining a tool
157+
which returns a type based off
158+
[`BaseEvent`](https://docs.ag-ui.com/sdk/js/core/events#baseevent) this allows
159+
for custom events and state updates.
160+
161+
```python {title="ag_ui_tool_events.py" py="3.10" hl_lines="34-55"}
162+
"""Tool events example for AG-UI with FastAPI and Pydantic AI."""
163+
164+
from__future__import annotations
165+
166+
from ag_ui.coreimport CustomEvent, EventType, StateSnapshotEvent
167+
from pydanticimport BaseModel
168+
169+
from pydantic_aiimport Agent, RunContext
170+
from pydantic_ai.ag_uiimport StateDeps
171+
172+
173+
classDocumentState(BaseModel):
174+
"""State for the document being written."""
175+
176+
document:str=''
177+
178+
179+
agent= Agent(
180+
'openai:gpt-4.1',
181+
instructions='Be fun!',
182+
deps_type=StateDeps[DocumentState],
183+
)
184+
app= agent.to_ag_ui(deps=StateDeps(DocumentState()))
185+
186+
187+
@agent.tool
188+
defupdate_state(ctx: RunContext[StateDeps[DocumentState]]) -> StateSnapshotEvent:
189+
return StateSnapshotEvent(
190+
type=EventType.STATE_SNAPSHOT,
191+
snapshot=ctx.deps.state,
192+
)
193+
194+
195+
@agent.tool_plain
196+
defcustom_events() -> list[CustomEvent]:
197+
return [
198+
CustomEvent(
199+
type=EventType.CUSTOM,
200+
name='count',
201+
value=1,
202+
),
203+
CustomEvent(
204+
type=EventType.CUSTOM,
205+
name='count',
206+
value=2,
207+
),
208+
]
209+
```
210+
211+
##Examples
212+
213+
For more examples of how to use[`to_ag_ui`][pydantic_ai.Agent.to_ag_ui] see
214+
[`pydantic_ai_ag_ui_examples`](https://github.com/pydantic/pydantic-ai/tree/main/examples/pydantic_ai_ag_ui_examples),
215+
which includes working server for the with the
216+
[AG-UI Dojo](https://docs.ag-ui.com/tutorials/debugging#the-ag-ui-dojo) which
217+
can be run from a clone of the repo or with the`pydantic-ai-examples` package
218+
installed with either of the following:
219+
220+
```bash
221+
pip/uv-add pydantic-ai-examples
222+
```
223+
224+
Direct, which supports command line flags:
225+
226+
```shell
227+
python -m pydantic_ai_ag_ui_examples.dojo_server --help
228+
usage: dojo_server.py [-h] [--port PORT] [--reload] [--no-reload] [--log-level {critical,error,warning,info,debug,trace}]
229+
230+
PydanticAI AG-UI Dojo server
231+
232+
options:
233+
-h, --help show thishelp message andexit
234+
--port PORT, -p PORT Port to run the server on (default: 9000)
235+
--reload Enable auto-reload (default: True)
236+
--no-reload Disable auto-reload
237+
--log-level {critical,error,warning,info,debug,trace}
238+
Agent log level (default: info)
239+
```
240+
241+
Run with dojo server with debug logging:
242+
243+
```shell
244+
python -m pydantic_ai_ag_ui_examples.dojo_server --log-level debug
245+
```
246+
247+
Using uvicorn:
248+
249+
```shell
250+
uvicorn pydantic_ai_ag_ui_examples.dojo_server:app --port 9000
251+
```
252+
253+
There is also a simplified basic example:
254+
255+
```shell
256+
python -m pydantic_ai_ag_ui_examples.basic
257+
```

‎docs/api/ag_ui.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#`pydantic_ai.ag_ui`
2+
3+
::: pydantic_ai.ag_ui

‎docs/install.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ pip/uv-add "pydantic-ai-slim[openai]"
5656
*`cohere` - installs`cohere`[PyPI ↗](https://pypi.org/project/cohere){:target="_blank"}
5757
*`duckduckgo` - installs`ddgs`[PyPI ↗](https://pypi.org/project/ddgs){:target="_blank"}
5858
*`tavily` - installs`tavily-python`[PyPI ↗](https://pypi.org/project/tavily-python){:target="_blank"}
59+
*`ag-ui` - installs`ag-ui-protocol`[PyPI ↗](https://pypi.org/project/ag-ui-protocol){:target="_blank"}
5960

6061
See the[models](models/index.md) documentation for information on which optional dependencies are required for each model.
6162

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp