Add `VercelAIAdapter.dump_messages` to convert Pydantic AI messages to Vercel AI messages #3392

dsfaccini · 2025-11-11T01:20:23Z

Summary

Implements a dump_messages() @classmethod for the VercelAIAdapter to convert Pydantic AI messages to Vercel AI format, enabling export of agent conversation history from Pydantic AI to Vercel AI protocol.

This is the reverse operation of the existing load_messages() method.

Implementation

dump_messages():

Accepts a sequence of ModelMessage objects (ModelRequest/ModelResponse)
Returns a list of UIMessage objects in Vercel AI format
Maintains message grouping and ordering
Quirk: accepts an _id_generator() function to generate message ids
- this is used primarily by the test suite to keep constant UUIDs in the snapshots

Cases Covered

The implementation handles:

Basic message types: System prompts, user messages, assistant responses
Text content: Single and multi-part text with proper concatenation
Tool calls: Regular tool calls with state tracking (in-progress, output-available, output-error)
Builtin tools: Provider-executed tools with proper ID prefixing and metadata
Tool returns: Automatic matching of tool calls with their returns to set proper states
Thinking/reasoning: ThinkingPart conversion to ReasoningUIPart
File attachments:
- BinaryContent conversion to data URIs
- URL-based files (ImageUrl, AudioUrl, VideoUrl, DocumentUrl)
Retry prompts: Tool errors converted to output-error state
Multi-modal content: Mixed text and file content in user prompts

Design Considerations

Tool return handling: Tool returns in ModelRequest are used to determine the state of tool calls in ModelResponse messages, not emitted as separate user messages.
Text concatenation: Consecutive TextPart instances are concatenated. When interrupted by non-text parts (tools, files, reasoning), subsequent text is separated with \n\n.
Builtin tool IDs: Uses the existing BUILTIN_TOOL_CALL_ID_PREFIX pattern for consistency with other adapters.
Message grouping: System and user parts within a ModelRequest are split into separate UIMessage objects when needed.

Caveats

Tool call input reconstruction: When tool returns appear in ModelRequest without the original tool call in the same message history, the input field is set to an empty object {} since the original arguments are not available.
No perfect roundtrip: Due to timestamp generation and UUID assignment, dump_messages(load_messages(ui_msgs)) will not produce identical objects, but will preserve semantic equivalence.
Builtin tool return location: The implementation checks both the same ModelResponse (for builtin tools) and subsequent ModelRequest messages (for regular tools) to find tool returns.

Tests

Added tests for the following cases in test_vercel_ai.py

Basic message dumping
Tool calls with and without returns
Builtin tools with provider metadata
Thinking/reasoning parts
File attachments (data URIs and URLs)
Retry prompts and errors
Consecutive text concatenation
Text with interruptions
Roundtrip conversion (dump then load)

dsfaccini · 2025-11-11T01:43:44Z

there's a missing for loop in the method inplementstion, will push a fix tomorrow!

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

tests/test_vercel_ai.py

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

tests/test_vercel_ai.py

…dumping and IsStr - add dump_messages to base adapter class

pydantic_ai_slim/pydantic_ai/ui/_adapter.py

pydantic_ai_slim/pydantic_ai/ui/ag_ui/_adapter.py

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

DouweM · 2025-11-28T20:46:59Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                        user_ui_parts.extend(_convert_user_prompt_part(part))
+                    elif isinstance(part, ToolReturnPart | RetryPromptPart):
+                        # Tool returns/errors don't create separate UI parts
+                        # They're merged into the tool call in the assistant message


Only if the retry prompt part has a tool call ID, otherwise it should be a text message

DouweM · 2025-11-28T20:48:00Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                local_builtin_returns: dict[str, BuiltinToolReturnPart] = {}
+                for part in msg.parts:
+                    if isinstance(part, BuiltinToolReturnPart):
+                        local_builtin_returns[part.tool_call_id] = part


This can be a single dict comprehension

DouweM · 2025-11-28T20:48:43Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                        # Combine consecutive text parts by checking the last UI part
+                        if ui_parts and isinstance(ui_parts[-1], TextUIPart):
+                            last_text = ui_parts[-1]
+                            ui_parts[-1] = last_text.model_copy(update={'text': last_text.text + part.content})


Why not just last_text.text += part.content?

DouweM · 2025-11-28T20:51:51Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                    elif isinstance(part, BaseToolCallPart):
+                        if isinstance(part, BuiltinToolCallPart):
+                            prefixed_id = (
+                                f'{BUILTIN_TOOL_CALL_ID_PREFIX}|{part.provider_name or ""}|{part.tool_call_id}'


We shouldn't need to make any special IDs, as we can store metadata on the part, right? And Vercel AI already has a native way of specifying provider_executed tool calls

DouweM · 2025-11-28T20:52:42Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                                        tool_call_id=prefixed_id,
+                                        input=part.args_as_json_str(),
+                                        state='input-available',
+                                        provider_executed=True,


Shouldn't we still store the metadata in this case?

yeahp we should, I'm not even sure this case is reachable but I should've included the metadata

DouweM · 2025-11-28T20:53:13Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                                )
+                        else:
+                            tool_return = tool_returns.get(part.tool_call_id)
+                            tool_error = tool_errors.get(part.tool_call_id)


We could have a single dict, right?

makes it more verbose though, when we start getting into second level keys accesses

DouweM · 2025-12-01T21:48:42Z

pydantic_ai_slim/pydantic_ai/ui/_adapter.py


-    @classmethod
-    @abstractmethod
-    def dump_messages(cls, messages: Sequence[ModelMessage]) -> list[MessageT]:


I still wanted this method exactly as defined, just not abstractmethod :) That way subclasses are not required to implemented it, but if it's called it'll still raise NotImplementedError.

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

DouweM · 2025-12-01T21:49:52Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+    def _dump_response_message(  # noqa: C901
+        msg: ModelResponse,
+        tool_returns: dict[str, ToolReturnPart],
+        tool_errors: dict[str, RetryPromptPart],


Can we combine these 2 dicts into 1?

DouweM · 2025-12-01T21:51:14Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                    )
+                )
+            elif isinstance(part, BaseToolCallPart):
+                if isinstance(part, BuiltinToolCallPart):


Instead of if isinstance(part, BaseToolCallPart): and inside it 2 branches for Builtin vs not builtin, I'd rather have top-level branches for if isinstance(part, ToolCallPart): and if isinstance(part, BuiltinToolCallPart):

…ptPart without tool_name, split BaseToolCallPart branches

dsfaccini · 2025-11-28T21:25:54Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                                )
+                        else:
+                            tool_return = tool_returns.get(part.tool_call_id)
+                            tool_error = tool_errors.get(part.tool_call_id)


makes it more verbose though, when we start getting into second level keys accesses

dsfaccini · 2025-11-30T04:07:14Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                                        tool_call_id=prefixed_id,
+                                        input=part.args_as_json_str(),
+                                        state='input-available',
+                                        provider_executed=True,


yeahp we should, I'm not even sure this case is reachable but I should've included the metadata

tests/test_vercel_ai.py

DouweM · 2025-12-02T20:56:41Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

-                                call_provider_metadata=call_provider_metadata,
-                            )
+                    )
+                else:  # pragma: no cover


Let's cover this branch as well

add dump_messages method to vercel ai adapter

4fdb27d

fix broken loop and add tests for coverage

1cb60bf

dsfaccini commented Nov 11, 2025

View reviewed changes

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py Show resolved Hide resolved

dsfaccini commented Nov 11, 2025

View reviewed changes

tests/test_vercel_ai.py Outdated Show resolved Hide resolved

add missing tests for coverage

261bc3a

DouweM self-assigned this Nov 11, 2025

DouweM added the awaiting author revision label Nov 11, 2025

DouweM requested changes Nov 11, 2025

View reviewed changes

wip: remove id generator and BuiltinToolReturnPart - fix tests using …

3f70b83

…dumping and IsStr - add dump_messages to base adapter class

DouweM mentioned this pull request Nov 19, 2025

Improved support for roundtrip AG_UI message conversion #3474

Open

dsfaccini added 9 commits November 20, 2025 13:39

Merge branch 'main' into vercelai-adapter-dump-messages

97feec2

Merge branch 'main' into vercelai-adapter-dump-messages

dfcb30c

Merge branch 'main' into vercelai-adapter-dump-messages

f99bc0c

refactor: simplify dump_messages method and remove unused id generator

4870dd4

test: add unit test for dumping and loading ThinkingPart with metadata

b1272b7

Merge branch 'main' into vercelai-adapter-dump-messages

6cdec4d

coverage

e300c15

Merge branch 'main' into vercelai-adapter-dump-messages

42596b9

syntax imprevement

57157d6

dsfaccini requested a review from DouweM November 28, 2025 03:03

DouweM changed the title ~~add dump_messages method to vercel ai adapter~~ Add VercelAIAdapter.dump_messages to convert Pydantic AI messages to Vercel AI messages Nov 28, 2025

DouweM requested changes Nov 28, 2025

View reviewed changes

dsfaccini added 4 commits November 28, 2025 17:09

address review points

58a71a2

Merge branch 'main' into vercelai-adapter-dump-messages

2f3b2a2

fix coverage

a061421

refaator (for comfort)

73fb21d

DouweM requested changes Dec 1, 2025

View reviewed changes

Refactor dump_messages per review: merge tool dicts, handle RetryProm…

e49f656

…ptPart without tool_name, split BaseToolCallPart branches

dsfaccini commented Dec 1, 2025

View reviewed changes

DouweM requested changes Dec 2, 2025

View reviewed changes

dsfaccini added 2 commits December 3, 2025 10:59

test builtin tool call without return in dump_messages

54f77a7

Merge branch 'main' into vercelai-adapter-dump-messages

dbdca1d

Add VercelAIAdapter.dump_messages to convert Pydantic AI messages to Vercel AI messages #3392

Are you sure you want to change the base?

Add VercelAIAdapter.dump_messages to convert Pydantic AI messages to Vercel AI messages #3392

Conversation

dsfaccini commented Nov 11, 2025

Summary

Implementation

Cases Covered

Design Considerations

Caveats

Tests

Uh oh!

dsfaccini commented Nov 11, 2025

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add `VercelAIAdapter.dump_messages` to convert Pydantic AI messages to Vercel AI messages #3392

Add `VercelAIAdapter.dump_messages` to convert Pydantic AI messages to Vercel AI messages #3392