The Vercel AI SDK · Chapter 13 of 21

Data parts and message metadata

By the end of this chapter your chat route can send more than the model's answer: a status line for the page while Mali works, suggested replies a customer can tap, and facts about each answer (which model, how many tokens). You will write the metadata, stream a status and suggestions from the route, and show all three on the page. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The chat UI
  • 3 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of The Vercel AI SDK are free. This one comes with the all labs plan.

Why you need this

Ananya has been watching customers use Mali on her phone, and has three small requests.

The first second after Send feels dead: the customer's message appears, then nothing, until the first word or tool arrives. She wants a line that says Mali has the message. After an answer about an order, customers often type the same next question ("What if it arrives damaged?"); she wants it as a button they can tap. And Vikram wants every answer to show which model wrote it and how many tokens it used, small and grey, so the team can spot an expensive conversation while testing.

None of that is the model's text. The route from chapter 9 streams exactly what streamText produces, so it has no way to say anything of its own. Farhan says the UI message stream was built for this: the route can write its own parts into the stream, beside the model's, and attach facts to the message itself.

What you build: 3 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    metadata.ts: metadata about each answer

    Export the type MaliMetadata and a function maliMetadata({ part }) that returns { model: 'lab-chat', createdAt: Date.now() } for the start part, { inputTokens, outputTokens, totalTokens } from part.totalUsage for the finish part, and undefined for every other part.

    The Check calls it with a start part, a finish part with totalUsage 812 in, 37 out, 849 in all, and a text part.

  2. Task 2

    server.ts: a status, suggestions and metadata in the stream

    Rewrite chapter 9's route with createUIMessageStream: in execute, first write a transient data-status part with the text Mali is reading your message..., then run streamText (Mali, the tools, isStepCount(5)) whose onChunk writes a data-suggestions part with the id next each time the model calls a tool, holding NEXT's line for every tool called so far; then merge toUIMessageStream({ stream: result.stream, messageMetadata: maliMetadata }). Keep chapter 7's 400 for a bad body.

    The Check posts an order question (the status first; the suggestion What if my plant arrives damaged?; metadata with the tokens of both requests), a question that calls two tools (two suggestion parts, the last with both lines), and a question with no tool (no suggestions).

  3. Task 3

    Chat.tsx: the status, the suggestions and the tokens on the page

    Add to chapter 9's chat: the text of each data-status part (from useChat's onData) shown in a status line while the chat is busy and cleared when it finishes; each reply of the message's last data-suggestions part as a button that sends that reply; and under each answer with metadata, MODEL · TOKENS tokens from metadata.model and metadata.totalTokens.

    The Check uses its own route (task 2's shape) at the real pace: the status shows while Mali works and is gone after, the tokens line equals the lab model's usage, and pressing the suggestion sends it as the customer's next message.

What you will learn

  • createUIMessageStream: a stream your route writes into, and the model's stream merged in.
  • Data parts: your own typed parts, data-<name>, kept in the message.
  • Transient parts: sent to the page once, never kept, read with onData.
  • Updating a part by writing the same id again.
  • Message metadata: facts about a message (messageMetadata), on start and finish.
  • Typed messages: UIMessage<Metadata, Data, Tools>, so the page knows the shapes.

More in The chat UI

Build "Data parts and message metadata" yourself

HariBhari, a Bengaluru plant shop, wants Mali, a plant helper on its website. You build it end to end, from the first call to a chat that streams cards, asks before it adds to the cart and stays within budget. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of The Vercel AI SDK are free. This one comes with the all labs plan.