Message Metadata

Überblick

Die metadata-Property auf UIMessage ist ein beliebiges Objekt, das nicht an das LLM gesendet wird. Es beschreibt die Message selbst — wer sie gesendet hat, wann, mit welchem Modell, wie viele Tokens verbraucht wurden. Metadata ist unsichtbar für das LLM, aber nuetzlich für Logging, Analytics und Persistenz.

Der Unterschied zu Data Parts: Metadata beschreibt die Message (wer, wann, womit), Data Parts sind dynamischer Content innerhalb der Message (Wetter-Karten, Fortschrittsbalken, Quellen). Metadata ändert sich nicht nach dem Erstellen, Data Parts können sich über ID-Reconciliation weiterentwickeln.

Auf der Server-Seite setzt Du Response-Metadata über die messageMetadata-Option in toUIMessageStreamResponse. Incoming-Metadata von User-Messages kannst Du auf dem Server auslesen und für Logging oder Analytics nutzen.

Code-Beispiel

import type { UIMessage } from 'ai';

// User-Message mit Metadata
const message: UIMessage = {
  id: 'msg-1',
  role: 'user',
  parts: [{ type: 'text', text: 'Erklaere Streaming.' }],
  metadata: {
    userId: 'user-42',
    timestamp: Date.now(),
    sessionId: 'session-abc',
  },
};

Response Metadata setzen

import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: anthropic('claude-sonnet-4-5-20250514'),
    messages,
  });

  return result.toUIMessageStreamResponse({
    messageMetadata: ({ part }) => {
      if (part.type === 'start') {
        return {
          modelId: 'claude-sonnet-4-5-20250514',
          generatedAt: Date.now(),
        };
      }
    },
  });
}

Typische Use Cases

Metadata-Feld	Zweck
`userId`	Zuordnung zu einem User
`timestamp`	Zeitstempel der Erstellung
`sessionId`	Zuordnung zu einer Session
`modelId`	Welches Modell die Antwort generiert hat
`tokenUsage`	Token-Verbrauch für Kosten-Tracking
`latencyMs`	Antwortzeit für Performance-Monitoring
`feedbackScore`	User-Bewertung der Antwort

Metadata vs Data Parts

Eigenschaft	Metadata	Data Parts
Beschreibt	Die Message selbst	Content innerhalb der Message
Aenderbar	Nein (einmal gesetzt)	Ja (via ID-Reconciliation)
Sichtbar für LLM	Nein	Nein
Typischer Inhalt	userId, timestamp, modelId	Wetter-Daten, Fortschritt, Quellen
Zugriff im Frontend	`message.metadata`	`message.parts` (type `'data'`)

Siehe auch

Challenge 7.2: Message Metadata — Hands-on mit Metadata
Challenge 4.3: Persistence — Messages mit Metadata speichern