add dump_messages method to vercel ai adapter #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!

dsfaccini · 2025-11-11T03:49:16Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py


+                        if isinstance(args, str):
+                            try:
+                                args = json.loads(args)
+                            except json.JSONDecodeError:
+                                pass
+


Tests showed "load_messages" converted args from a dict to a string, so I added this one to parse them back, but args supports both.

Our args is a str | dict[str, Any] while input is Any. Can you make this code a bit more robust in making sure we end up with a valid string or dict on our part? For example, if args is JSON, parsing it could also give us a list or something, in which case we'd rather want the string. And if it's not a string or already a dict, perhaps we should raise an error.

dsfaccini · 2025-11-11T03:50:18Z

tests/test_vercel_ai.py

+                parts=[
+                    TextPart(content='Response text'),
+                    ToolCallPart(tool_name='tool1', args={'key': 'value'}, tool_call_id='tc1'),
+                ],
+                timestamp=IsDatetime(),


and this is the test that caught the asymmetry (dict != str)

DouweM · 2025-11-11T22:20:02Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py


+                        if isinstance(args, str):
+                            try:
+                                args = json.loads(args)
+                            except json.JSONDecodeError:
+                                pass
+


Our args is a str | dict[str, Any] while input is Any. Can you make this code a bit more robust in making sure we end up with a valid string or dict on our part? For example, if args is JSON, parsing it could also give us a list or something, in which case we'd rather want the string. And if it's not a string or already a dict, perhaps we should raise an error.

DouweM · 2025-11-11T22:20:58Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

        return builder.messages
+
+    @classmethod
+    def dump_messages(  # noqa: C901


Let's add this to the super class, and maybe you can look at integrating #3068 into this new framework as well, to make sure our decisions/assumptions hold up against 2 standards not just 1.

on the args front

if isinstance(args, str): # if args is a list, we'll keep it as a string, otherwise try to parse as dict try: args = json.loads(args) if args.strip()[:1] != '[' else args except json.JSONDecodeError: pass elif not isinstance(args, dict | list | None): # pragma: no branch raise UserError(f'Unsupported tool call args type: {type(args)}')

on the superclass front

@classmethod @abstractmethod def dump_messages(cls, message: ModelMessage) -> MessageT: """Transform Pydantic AI messages into protocol-specific messages.""" raise NotImplementedError

on the 3068 front, you mean integrating the changes from that PR into this one?

On the args front, I'd rather test the type of the parsed result

On the superclass front, yeah lets include that PR.

DouweM · 2025-11-11T22:21:29Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+        cls,
+        messages: Sequence[ModelMessage],
+        *,
+        _id_generator: Callable[[], str] | None = None,


As we don't have this elsewhere I'd rather not have it here, and use IsStr() and IsSameStr() in the test instead

DouweM · 2025-11-11T22:22:38Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+        for msg in messages:
+            if isinstance(msg, ModelRequest):
+                for part in msg.parts:
+                    if isinstance(part, ToolReturnPart | BuiltinToolReturnPart):


BuiltinToolReturnPart only exists on ModelResponse as it all happens on the server side

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

DouweM · 2025-11-11T22:37:57Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                            if builtin_return:
+                                content = builtin_return.model_response_str()
+                                call_provider_metadata = (
+                                    {'pydantic_ai': {'provider_name': part.provider_name}}


Right, we were already doing this for builtin tools in the event stream already :)

I suppose the stuff I said above also applies to the other events we output like for reasoning. But since we get the data chunk by chunk and have to stream it using particular Vercel AI events, we may not always have the information a Vercel AI event needs at the time we get the Pydantic AI event. But for best behavior we really should use provider_metadata to store this kind of info there more as well. Feel free to look into that here or in a new PR.

DouweM · 2025-11-11T22:40:02Z

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

+                        had_interruption = True
+
+                        if isinstance(part, BuiltinToolCallPart):
+                            prefixed_id = _make_builtin_tool_call_id(part.provider_name, part.tool_call_id)


What do we need this for?

I honestly just read it in your review of 3068 and thought I'd need a helper as well, but I'm only calling it once

pydantic_ai_slim/pydantic_ai/ui/vercel_ai/_adapter.py

tests/test_vercel_ai.py

DouweM · 2025-11-11T22:42:33Z

tests/test_vercel_ai.py

+    # Load back to Pydantic AI format
+    reloaded_messages = VercelAIAdapter.load_messages(ui_messages)
+
+    # Can't use `assert reloaded_messages == original_messages` because the timestamps will be different


What if we use a helper function that walks the list and resets the timestamps? assert reloaded_messages == original_messages would be much less brittle than having to manually review these 2 snapshots for equality

yeahp, I was thinking the same. same patch can be applied to the UUIDs to get rid of the _id_generator.

…dumping and IsStr - add dump_messages to base adapter class

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

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

add dump_messages method to vercel ai adapter #3392

Are you sure you want to change the base?

add dump_messages method to vercel ai adapter #3392

Conversation

dsfaccini commented Nov 11, 2025

Summary

Implementation

Cases Covered

Design Considerations

Caveats

Tests

Uh oh!

dsfaccini commented Nov 11, 2025

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!

dsfaccini Nov 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dsfaccini Nov 16, 2025 •

edited

Loading