feat: AG-UI adapter (toolsets) #2101

stevenh · 2025-06-30T21:27:20Z

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

This includes examples for all features in the AG-UI dojo.

hyperlint-ai · 2025-06-30T21:28:02Z

PR Change Summary

Implemented the AG-UI adapter for seamless integration with the AG-UI protocol, enhancing user interaction capabilities for PydanticAI agents.

Added comprehensive documentation for the AG-UI adapter and its features.
Introduced examples demonstrating the integration of PydanticAI agents with the AG-UI protocol.
Updated installation instructions to include AG-UI dependencies.

Modified Files

docs/install.md

Added Files

docs/ag-ui.md
docs/api/ag_ui.md
examples/pydantic_ai_ag_ui_examples/README.md

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

dorukgezici · 2025-07-02T08:30:52Z

Hey! I know this is still a draft, but have been following the development of ag-ui support since I wish to build my MVP with pydantic-ai & ag-ui. Did a test run today on this branch, dropping my findings in case they are helpful:

If there are mcp_servers defined in the agent, .to_ag_ui() doesn't handle running the servers, so any request errors out
I noticed if the model is trying to chain tool calls, it errors out with a similar error to this even when parallel_tool_calls is disabled:
pydantic_ai.exceptions.ModelHTTPError: status_code: 400, model_name: gpt-4.1-mini, body: {'message': "Invalid parameter: messages with role 'tool' must be a response to a preceeding message with 'tool_calls'.", 'type': 'invalid_request_error', 'param': 'messages.[13].role', 'code': None}

stevenh · 2025-07-03T01:11:11Z

Great info, keep it coming!

stevenh · 2025-07-03T13:34:23Z

Hey! I know this is still a draft, but have been following the development of ag-ui support since I wish to build my MVP with pydantic-ai & ag-ui. Did a test run today on this branch, dropping my findings in case they are helpful:

If there are mcp_servers defined in the agent, .to_ag_ui() doesn't handle running the servers, so any request errors out

I noticed if the model is trying to chain tool calls, it errors out with a similar error to this even when parallel_tool_calls is disabled:
pydantic_ai.exceptions.ModelHTTPError: status_code: 400, model_name: gpt-4.1-mini, body: {'message': "Invalid parameter: messages with role 'tool' must be a response to a preceeding message with 'tool_calls'.", 'type': 'invalid_request_error', 'param': 'messages.[13].role', 'code': None}

There's been some changes on toolset PR, which this depends on and has been updated, can you retest to see if these are fixed now @dorukgezici

dorukgezici · 2025-07-04T15:02:47Z

@stevenh concurrent tool calls worked well now!
I also tried a streamable HTTP MCP server (used the new toolsets=[] param on the agent) and the agent worked, but wasn't aware of the tool so it was not registered. That's probably an issue that belongs to the ongoing toolsets PR you are basing off?

stevenh · 2025-07-04T19:29:09Z

@stevenh concurrent tool calls worked well now!

I also tried a streamable HTTP MCP server (used the new toolsets=[] param on the agent) and the agent worked, but wasn't aware of the tool so it was not registered. That's probably an issue that belongs to the ongoing toolsets PR you are basing off?

Could you clarify what you mean by wasn't aware of the tool? Do you mean an AG-UI tool wasn't available?

DouweM

@stevenh Looking good! Left some questions and suggestions

.github/workflows/ci.yml

pyproject.toml

tests/conftest.py

pydantic_ai_slim/pydantic_ai/agent.py

pydantic_ai_slim/pydantic_ai/ag_ui.py

DouweM · 2025-07-04T22:32:44Z

pydantic_ai_slim/pydantic_ai/ag_ui.py

+
+# Enums.
+# TODO(steve): Remove this and all uses once https://github.com/ag-ui-protocol/ag-ui/pull/49 is merged.
+class Role(str, Enum):


I think we can drop this and just hard-code string values, they're defined as Literals on the event classes so they're type-checked for validity anyway

We could but that results in repeated values, which is less efficient. I was hoping we could get these eliminated before we merge.

If we get them eliminated even better, but if not we prefer literals as @Viicos explained here: #2024 (comment)

examples/pydantic_ai_ag_ui_examples/api/agentic_generative_ui.py

examples/pydantic_ai_ag_ui_examples/api/agent.py

examples/pydantic_ai_ag_ui_examples/api/agentic_generative_ui.py

examples/pydantic_ai_ag_ui_examples/api/predictive_state_updates.py

pydantic_ai_slim/pydantic_ai/ag_ui.py

pydantic_ai_slim/pydantic_ai/models/test.py

examples/pydantic_ai_ag_ui_examples/api/agentic_generative_ui.py

examples/pydantic_ai_ag_ui_examples/api/shared_state.py

examples/pydantic_ai_ag_ui_examples/cli/__init__.py

tests/test_ag_ui.py

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

Move pydantic_ai_ag_ui to pydantic_ai_slim as ag_ui, updating references and documentation accordingly.

Refactor to_ag_ui so it now returns a ASGI compatible server based off starlette. This makes it easier for users setup apps with minimal code. Fix some invalid references missed in the package refactor for cli and examples. Made enums, and exceptions private to the package, so they are not exposed in the public API.

Eliminate the use of match statement and dataclass(kw_only=True) to ensure compatibility with Python 3.9. Remove duplicate import of starlette outside try block, causing tests to fail when it's not installed.

Disable the deprecation warning for model_fields in Mistral.

Remove invalid no cover comment from Mistral model flagged by strict-no-cover check.

Add support for the new tool call returns and thinking parts to the AG UI adapter. This eliminates the need to build a message snapshot while sill providing the necessary information for the UI.

Allow the agent path to be specified when using to_ag_ui.

Reduce the log level for the request done message in the AG-UI adapter to debug level.

Add missing `from __future__ import annotations` imports to ensure ensure that only relevant type annotations are processed at runtime. Fix incorrect import of `dataclass` in `args.py`.

Switch from additional tools to the new toolset system.

* Update examples to use `to_ag_ui` * Use relative imports where appropriate * Remove `path` and `logger` parameters from `to_ag_ui` and dependencies * Clean up import failure messages * Improve FastAGUI doc comment * Use `PrefixedToolset` eliminating manual tool prefixing * Use CallToolsNode to handle tool calls Also make StateDeps more strict, to avoid runtime failures.

Add some no cover pragmas in existing code to avoid coverage check failure. Correct raise to avoid resetting traceback in `AgentGraph`.

* Split out coverage fixes to separate PRs * Rename FastAGUI to AGUIApp * Add thinking part delta test * Remove example agent helper * Use dedent to help create clean instructions * Remove logging from examples * Restore explicit re-raise variable * Eliminate agent_to_ag_ui * Ensure user toolsets are not overwritten incorrectly * Use temporary vars to reduce repetitive indirection * Raise ToolCallNotFoundError if tool result without matching call

Update to support the new `toolsets` behaviour which is now additional instead of replacing the existing toolsets.

* Remove logging * Remove load_dotenv * Make Agent private * Remove unnecessary type hints * Use 422 instead of 400 for validation errors

Switch the tests from TestModel to FunctionModel, which only needs less changes to provide the same functionality. Also use `IsStr`` and `snapshot`` to improve test readability and maintainability. This adds `ThinkingPart`` support to the `FunctionModel` via the new `DeltaThinkingCall` class.

stevenh force-pushed the feat/ag-ui-adapter-toolset branch 2 times, most recently from caddcc0 to 6671164 Compare July 1, 2025 12:35

DouweM self-assigned this Jul 1, 2025

stevenh force-pushed the feat/ag-ui-adapter-toolset branch 3 times, most recently from a391a93 to 2995d59 Compare July 3, 2025 09:03

stevenh mentioned this pull request Jul 3, 2025

feat: AG-UI adapter #2044

Closed

stevenh force-pushed the feat/ag-ui-adapter-toolset branch from 2995d59 to 78da22f Compare July 4, 2025 18:46

DouweM force-pushed the feat/ag-ui-adapter-toolset branch from 78da22f to 1bad3e5 Compare July 4, 2025 22:00

DouweM requested changes Jul 4, 2025

View reviewed changes

stevenh mentioned this pull request Jul 6, 2025

feat: PydanticAI support ag-ui-protocol/ag-ui#133

Draft

stevenh force-pushed the feat/ag-ui-adapter-toolset branch 4 times, most recently from 1db1afb to 639d60b Compare July 7, 2025 18:04

stevenh marked this pull request as ready for review July 7, 2025 18:27

stevenh mentioned this pull request Jul 8, 2025

PydanticAI support ag-ui-protocol/ag-ui#5

Open

stevenh force-pushed the feat/ag-ui-adapter-toolset branch from 639d60b to d8c6cb5 Compare July 8, 2025 16:01

DouweM requested changes Jul 8, 2025

View reviewed changes

DouweM added the awaiting author revision label Jul 8, 2025

stevenh force-pushed the feat/ag-ui-adapter-toolset branch 2 times, most recently from 633ee32 to 5170a39 Compare July 9, 2025 17:02

stevenh requested a review from DouweM July 9, 2025 18:28

DouweM requested changes Jul 9, 2025

View reviewed changes

stevenh force-pushed the feat/ag-ui-adapter-toolset branch 3 times, most recently from caefce5 to f33c0c5 Compare July 10, 2025 15:21

stevenh added 17 commits July 10, 2025 16:34

feat: AG-UI adapter

fb0cb12

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

refactor(ag-ui): move AG-UI to pydantic_ai_slim

81a7b4f

Move pydantic_ai_ag_ui to pydantic_ai_slim as ag_ui, updating references and documentation accordingly.

chore(ag-ui): python 3.9 support

220ca79

Eliminate the use of match statement and dataclass(kw_only=True) to ensure compatibility with Python 3.9. Remove duplicate import of starlette outside try block, causing tests to fail when it's not installed.

chore(mistral): disable model_fields deprecation warning

f263349

Disable the deprecation warning for model_fields in Mistral.

chore(mistral): remove invalid no cover

1728677

Remove invalid no cover comment from Mistral model flagged by strict-no-cover check.

feat(ag-ui): Tool call returns and thinking parts

6783ab3

Add support for the new tool call returns and thinking parts to the AG UI adapter. This eliminates the need to build a message snapshot while sill providing the necessary information for the UI.

feat(ag-ui): expose agent path in adapter

d6d5a25

Allow the agent path to be specified when using to_ag_ui.

chore(ag-ui): reduce log level for request done

531d320

Reduce the log level for the request done message in the AG-UI adapter to debug level.

chore(ag-ui): add missing __future__ imports

bf7d717

Add missing `from __future__ import annotations` imports to ensure ensure that only relevant type annotations are processed at runtime. Fix incorrect import of `dataclass` in `args.py`.

chore(ag-ui): use toolsets

571d92c

Switch from additional tools to the new toolset system.

chore: fix coverage failure

4b74087

Add some no cover pragmas in existing code to avoid coverage check failure. Correct raise to avoid resetting traceback in `AgentGraph`.

chore(ag-ui): support additional toolsets

62d975a

Update to support the new `toolsets` behaviour which is now additional instead of replacing the existing toolsets.

chore(ag-ui): address PR feedback

7c5c49d

* Remove logging * Remove load_dotenv * Make Agent private * Remove unnecessary type hints * Use 422 instead of 400 for validation errors

stevenh force-pushed the feat/ag-ui-adapter-toolset branch from f33c0c5 to cc1b6cb Compare July 10, 2025 15:34

sirianni mentioned this pull request Jul 11, 2025

Extracting new_messages() in the middle of an Agent.iter run to support user-in-the-loop approval of tool calls #1995

Open

feat: AG-UI adapter (toolsets) #2101

Are you sure you want to change the base?

feat: AG-UI adapter (toolsets) #2101

Uh oh!

Conversation

stevenh commented Jun 30, 2025

Uh oh!

hyperlint-ai bot commented Jun 30, 2025

PR Change Summary

Uh oh!

dorukgezici commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stevenh commented Jul 3, 2025

Uh oh!

stevenh commented Jul 3, 2025

Uh oh!

dorukgezici commented Jul 4, 2025

Uh oh!

stevenh commented Jul 4, 2025

Uh oh!

DouweM left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DouweM Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

stevenh Jul 5, 2025

Choose a reason for hiding this comment

Uh oh!

DouweM Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dorukgezici commented Jul 2, 2025 •

edited

Loading