Expose a standalone message validation API

[Visualizeit]

I’d like to propose exposing a standalone API for validating messages in TanStack AI.

Currently, chatParamsFromRequestBody() validates messages internally through validateMessage():

const messages = requireArray(body.messages, 'messages').map(validateMessage)

However, validateMessage() is not exported, and the public API only exposes validation as part of the complete AG-UI RunAgentInput parsing flow.

Use case

In applications that persist conversations, messages are often loaded from a database or durable storage before being passed to chat():

const messages = await loadMessagesFromDatabase(conversationId)

const result = await chat({
  messages,
  // ...
})

It would be useful to validate these messages independently, without having to construct a complete RunAgentInput just to trigger the existing validation logic.

This also applies to applications using custom transports or restoring messages from persistent storage.

Proposal

Expose a standalone message validation API, for example:

import { validateMessages } from '@tanstack/ai'

const validatedMessages = validateMessages(messages)

I don't think the existing internal validateMessage() necessarily needs to be exported directly. Instead, a public validateMessages() API could provide a stable interface while keeping the current implementation internal.

A non-throwing variant could also be considered:

const result = safeValidateMessages(messages)

if (!result.success) {
  // handle validation error
}

Similar API in Vercel AI SDK

Vercel AI SDK provides validateUIMessages() and safeValidateUIMessages() for this use case.

For example:

const validatedMessages = await validateUIMessages({
  messages,
})

This is particularly useful when messages come from persistent storage and need to be validated before being processed or rendered.

I think TanStack AI could provide a similar lower-level API for its message format.

Why this might be useful

This would provide a cleaner separation between:

chatParamsFromRequest(request)

for validating an entire AG-UI request, and:

validateMessages(messages)

for validating messages independently.

It would also allow applications to reuse TanStack AI's own message validation logic instead of duplicating it when implementing persistence, custom transports, or other server-side workflows.

Would this be something worth exposing as a public API? I'm also interested in feedback on the API shape and naming.