docs/examples/ag-ui.md
Example of using Pydantic AI agents with the AG-UI Dojo example app.
See the AG-UI docs for more information about the AG-UI integration.
Demonstrates:
With dependencies installed and environment variables set you will need two command line windows.
Setup your OpenAI API Key
export OPENAI_API_KEY=<your api key>
Start the Pydantic AI AG-UI example backend.
python/uv-run -m pydantic_ai_examples.ag_ui
Next run the AG-UI Dojo example frontend.
Clone the AG-UI repository
git clone https://github.com/ag-ui-protocol/ag-ui.git
Change into to the ag-ui/typescript-sdk directory
cd ag-ui/sdks/typescript
Run the Dojo app following the official instructions
Select View Pydantic AI from the sidebar
This demonstrates a basic agent interaction including Pydantic AI server side tools and AG-UI client side tools.
If you've run the example, you can view it at http://localhost:3000/pydantic-ai/feature/agentic_chat.
time - Pydantic AI tool to check the current time for a time zonebackground - AG-UI tool to set the background color of the client windowWhat is the time in New York?
Change the background to blue
A complex example which mixes both AG-UI and Pydantic AI tools:
Perform the following steps, waiting for the response of each step before continuing:
1. Get the time
2. Set the background to red
3. Get the time
4. Report how long the background set took by diffing the two times
snippet {path="/examples/pydantic_ai_examples/ag_ui/api/agentic_chat.py"}
Demonstrates a long running task where the agent sends updates to the frontend to let the user know what's happening.
If you've run the example, you can view it at http://localhost:3000/pydantic-ai/feature/agentic_generative_ui.
Create a plan for breakfast and execute it
snippet {path="/examples/pydantic_ai_examples/ag_ui/api/agentic_generative_ui.py"}
Demonstrates simple human in the loop workflow where the agent comes up with a plan and the user can approve it using checkboxes.
generate_task_steps - AG-UI tool to generate and confirm stepsGenerate a list of steps for cleaning a car for me to review
snippet {path="/examples/pydantic_ai_examples/ag_ui/api/human_in_the_loop.py"}
Demonstrates how to use the predictive state updates feature to update the state of the UI based on agent responses, including user interaction via user confirmation.
If you've run the example, you can view it at http://localhost:3000/pydantic-ai/feature/predictive_state_updates.
write_document - AG-UI tool to write the document to a windowdocument_predict_state - Pydantic AI tool that enables document state
prediction for the write_document toolThis also shows how to use custom instructions based on shared state information.
Starting document text
Bruce was a good dog,
Agent prompt
Help me complete my story about bruce the dog, is should be no longer than a sentence.
snippet {path="/examples/pydantic_ai_examples/ag_ui/api/predictive_state_updates.py"}
Demonstrates how to use the shared state between the UI and the agent.
State sent to the agent is detected by a function based instruction. This then validates the data using a custom pydantic model before using to create the instructions for the agent to follow and send to the client using a AG-UI tool.
If you've run the example, you can view it at http://localhost:3000/pydantic-ai/feature/shared_state.
display_recipe - AG-UI tool to display the recipe in a graphical formatImprove with AIsnippet {path="/examples/pydantic_ai_examples/ag_ui/api/shared_state.py"}
Demonstrates customised rendering for tool output with used confirmation.
If you've run the example, you can view it at http://localhost:3000/pydantic-ai/feature/tool_based_generative_ui.
generate_haiku - AG-UI tool to display a haiku in English and JapaneseGenerate a haiku about formula 1
snippet {path="/examples/pydantic_ai_examples/ag_ui/api/tool_based_generative_ui.py"}