Input Multimodale in una Chat AI con Mastra AI e Vercel AI SDK

Negli ultimi mesi sto lavorando molto sull’integrazione di agenti AI multimodali dentro esperienze conversazionali per il mio progetto Sarion, un assistente intelligente che ti aiuta a gestire meglio la tua giornata.

Grazie a Mastra AI e Vercel AI SDK v4 è possibile costruire workflow che combinano testo e immagini dentro una stessa chat, mantenendo un’esperienza fluida sia lato frontend che backend.

In questo articolo racconto come ho implementato il supporto agli input multimodali (testo + immagini) in una chat AI, sfruttando la feature experimental_attachments dell'SDK v4.

Perché l’input multimodale è importante

Un agente che capisce solo testo è utile, ma limitato.

Pensiamo a use case come:

• Analisi di immagini caricate dall’utente,
• Conversazioni con screenshot e prompt testuali combinati,
• Chat AI che aiutano in contesti professionali (design, documenti, e-commerce).

Il valore è permettere all’utente di dialogare con l’AI usando più canali insieme: scrivere, allegare un’immagine, chiedere all’agente di interpretarla, e ricevere una risposta coerente.

Tecnologie usate

• Mastra AI (ultima versione) → per orchestrare agenti e workflow intelligenti.
• Vercel AI SDK v4 → per gestire la chat e il flusso dei messaggi, incluso experimental_attachments.

Lato Frontend: gestire testo e immagini

Dal lato FE ho definito una struttura semplice per i messaggi, in cui ogni parte può essere di tipo text o image:

type MessagePart =
  | { type: "text"; text: string }
  | { type: "image"; imageUrl: string; mimeType: string };

Quando l’utente scrive un messaggio e allega file:

1. Il testo viene aggiunto come text.
2. Le immagini vengono convertite in base64 e inserite come image con mimeType. Gli attachment vengono inviati al backend tramite il campo experimental_attachments.

Il punto chiave è questo blocco:

await append(
  {
    role: "user",
    content: textContent, 
    data: {
      ...messageData,
      threadId: currentThreadToUse?.id || "",
      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
    },
    experimental_attachments: attachments,
  }
);

Qui Vercel AI SDK v4 permette di spedire insieme testo + immagini senza dover stravolgere la struttura dei messaggi.

Best practice:

• Limite 5MB per immagine e 5000 caratteri per il testo, così eviti upload eccessivi.
• Massimo 5 immagini per thread, con un cap di 10 thread per utente, per mantenere scalabilità e performance.

Lato Backend: validare e costruire il messaggio

Dal lato server, il compito principale è validare gli attachment e trasformarli in un contenuto coerente per l’agente AI.

La parte interessante è la costruzione del messaggio multimodale:

if (hasAttachments) {
  const contentParts = [];

  // testo
  if (latestMessage.content) {
    contentParts.push({ type: "text", text: latestMessage.content });
  }

  // immagini
  for (const att of attachments) {
    if (att.contentType?.startsWith("image/")) {
      contentParts.push({
        type: "image",
        image: att.url,
        mimeType: att.contentType,
      });
    }
  }

  messageToSend = {
    id: uuidv4(),
    role: "user",
    content: contentParts,
  };
} else {
  messageToSend = {
    id: uuidv4(),
    role: "user",
    content: latestMessage.content,
  };
}

In pratica:

• Se l’utente invia solo testo, il messaggio rimane una stringa.
• Se invia testo + immagini, il messaggio diventa un array di contentParts.

Ho anche inserito il validatore di input nell'agente principale tramite ModerationProcessor che permette valutare, tramite un LLM dedicato, e bloccare contenuti ritenuti non idonei.

Questa validazione, unita a quella dimensionale, è fondamentale per evitare abusi e per mantenere la UX consistente.

Risultato: una chat multimodale

Grazie a questa integrazione, l’utente può scrivere un prompt e allegare immagini direttamente dalla chat.

L’agente Mastra riceve un input multimodale e può:

• Analizzare l’immagine,
• Leggere il testo,
• Fondere le informazioni per rispondere in modo intelligente.

Conclusione

Con poche righe di codice, sfruttando Mastra AI e il nuovo Vercel AI SDK v4, si può passare da una chat testuale a una vera esperienza multimodale.

Questo apre la strada a casi d’uso molto potenti: dall’assistente che interpreta screenshot al sistema che combina descrizioni testuali e immagini per generare report, analisi o suggerimenti.