Support for Custom Context Attachments in UserMessage

[tobiasbueschel]

Description

There currently isn’t a straightforward way to store and rehydrate additional context attachments within a UserMessage in the AI SDK.
This becomes relevant when building advanced chat UIs (e.g., similar to Cursor’s <PromptInput /> component), where a message may include not only text or files, but also structured context such as URLs that the system needs to fetch, JSON data, or tool toggles (like enabling webSearch for a specific prompt).

Existing mechanisms (FilePart, custom data parts, Message.metadata) only partially address this and don’t provide a consistent way to persist, rehydrate, and send non-file or text attachments.

Use Case

In chat applications where users can attach extra context to a message — such as files, URLs, structured JSON, or tool toggles - it would be helpful if these attachments could be:

• Stored alongside the user message
• Displayed again when editing that message, and
• Optionally included when converting messages to model input.

At the moment:

• Custom parts are stripped out by convertToModelMessages().
• metadata is not sent to the model and is mainly used for auxiliary data like timestamps or model info.
• Using prepareStep() to call a custom tool (e.g., getContext(attachmentIds)) results in that fetched context being stored in the assistant message rather than the user message, meaning those attachments cannot later be removed or modified.

What's would be helpful

It would be valuable to have a more flexible pattern to:

1. Persist arbitrary contextual data alongside UserMessage objects.
2. Rehydrate and display those attachments when editing messages.
3. Optionally include this data in the conversion process for model messages.
4. Achieve this without manually overriding internal conversion utilities like converToModelMessages()

Potential solution options

• Extending Message.parts to accept additional part types beyond text and file (e.g., data, tool, or url).
• Allowing custom serialization logic to map rich UserMessage structures to ModelMessage.
• Introducing middleware or hooks that can modify message payloads before conversion while retaining the ability to rehydrate those parts.
• Providing a mechanism to selectively include certain metadata fields in model messages when appropriate.

References

• Adding custom attributes to user input message in useChat AI SDK UI #2820 (comment)
• https://ai-sdk.dev/docs/reference/ai-sdk-core/model-message
• https://ai-sdk.dev/docs/ai-sdk-ui/message-metadata#common-use-cases

AI SDK Version

• ai@5.0.76

Code of Conduct

• I agree to follow this project's Code of Conduct

[cheungjulia]

+1 this would be a fantastic functionality to have!

[lgrammel]

You can attach custom parts to user messages today. Only the customization when mapping to model messages is missing.

[Drew-Garratt]

I've begun working on a draft PR for this that I hope will address the gap.

As custom parts can already be attached to messages I've focused on convertToModelMessages expanding the function to include optional handling for convertDataPart

This function uses the same generic passed to convertToModelMessages allowing us to handle custom typed data parts safely via the existing isDataUIPart function.