Tool result data shaped like a file is rebuilt as a file download or provider file reference when message history is reloaded
Description
When message history is serialized and loaded again, a tool result that contains a JSON object in the serialized shape of one of Pydantic AI's file types is rebuilt as that file. A third party who controls data a tool returns can use this to make the application download a URL on its local network, or make the model provider read an s3:// object or uploaded file with the application's credentials.
Details
When history is loaded, Pydantic AI rebuilds file items (ImageUrl, DocumentUrl, AudioUrl, VideoUrl and UploadedFile) nested in tool results, so that files a tool returned survive the round trip. A mapping that a tool returned as data serialized to the same JSON as one of these items, so loading rebuilt it as a file too. During the run the model received that mapping as JSON text. After the reload, it is a file that the next model request downloads or references.
Tool results are serialized and loaded again when:
- the application stores message history and loads it later, for example with
ModelMessagesTypeAdapter, including the history a UI adapter loads withmanage_message_history='server'; - the agent runs with Temporal, DBOS or Prefect durable execution, which serialize a tool's result between steps within a single run.
The assumed attacker is a third party with no access to the application who controls content that reaches a tool result, such as a record that an MCP server or a function tool returns from an external system. The MCP server and the tools themselves are trusted. No injected instructions are needed for the download or file reference to happen: it only takes a later model request.
The impact depends on the file the data is rebuilt as:
- A
DocumentUrlorImageUrlwithforce_download='allow-local'is downloaded by Pydantic AI with the private-network block turned off. Cloud metadata addresses stay blocked. For a plain-text document, and for any model that honorsforce_download, the response body is sent to the model provider as part of the conversation. The attacker can obtain it if the model can be induced to repeat it, for example to a tool the attacker controls. - A file URL with a non-HTTP scheme such as
s3://orgs://, or anUploadedFile, is resolved by the model provider with the application's credentials. The attacker can name any object those credentials can read.
You are affected if all of the following apply:
- Tool results can contain data that third parties control, for example from an MCP server or from an external API whose JSON a tool returns unchanged.
- Message history containing those results is serialized and loaded again: stored history, server-held UI adapter history, or durable execution.
- The model is one Pydantic AI downloads files for, or that honors
force_download, or its provider resolves non-HTTP file URLs or uploaded files.
History that a client submits through the Vercel AI or AG-UI adapter in the default mode is not affected. The adapters run sanitize_messages() on it, which resets force_download and drops non-HTTP URLs and uploaded files, including those nested in tool results.
Fix
A tool result now records the file items it holds when it is serialized, outside the tool's data, and loading rebuilds only those. A mapping that a tool returned stays a mapping, whatever its shape.
History saved by an earlier version has no such record. In it, a mapping shaped like a file is rebuilt only as an HTTP(S) URL with force_download reset, and an UploadedFile or non-HTTP URL stays a mapping. This also applies to files your own tools returned before the upgrade: in history saved by an earlier version, a tool-returned UploadedFile, non-HTTP URL or force_download setting does not survive loading. Files saved by the patched version keep every field.
If you stored that history yourself and trust its contents, load it with ModelMessagesTypeAdapter.validate_json(data, context={'pydantic_ai': {'rebuild_unrecorded_tool_files': True}}) (or validate_python), and its file items load as they did before. Save it again, and it carries the record and no longer needs the context. Only do this for history no third party could have shaped: loading it this way restores the earlier behavior for any lookalike it already contains.
Older versions ignore the record, so a rolling upgrade of durable-execution workers is safe, and durable execution decodes journal entries written before the upgrade as before, so runs in flight keep their files. The harness's step persistence stores, saved conversations and delegated-task records likewise load snapshots saved before the upgrade as before, so continued and forked runs keep their files. If those journals or snapshots may contain tool results built from third-party data, finish or discard runs started before the upgrade rather than continuing them, or run sanitize_messages() on the history first.
Mitigation
Upgrade to a patched version.
Until you can upgrade:
- Run
sanitize_messages()on stored history before reusing it. It resetsforce_downloadon file URLs in tool results and drops uploaded-file references and non-HTTP URLs. It also applies its other rules for untrusted history, such as removing unresolved tool calls at the end, so check those against how your application resumes runs. - Have function tools return third-party data as a JSON string, for example with
pydantic_core.to_json(data).decode(), rather than as a dict or list. A string is never rebuilt as a file.
To check history you have already stored, look for tool-return content containing "kind" values such as "document-url", "image-url" or "uploaded-file" that your own tools did not produce, especially with "force_download" set or a non-HTTP "url".