The Vercel AI SDK · Chapter 7 of 21

The chat route

By the end of this chapter you can put Mali behind a web route: a POST handler that takes the chat from a page, asks the model with streamText, and streams the answer back in the AI SDK's UI message stream. You will write the route, read its stream event by event with your own code, and show why a chat page sends the whole conversation every time. 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

Mali works. In chapters 1 to 6 it answered questions, looked up orders, filled Deepa's forms and streamed a long care guide. But every one of those answers came out of a Node script in a terminal. Ananya wants Mali on HariBhari's website, in a chat box a customer can type into.

A browser cannot call the model itself. The model's address and HariBhari's key would have to be in the page, where anyone can read them, and so would Mali's instructions and tools. So the model call stays on the server, and the page talks to a route: one URL on HariBhari's server, /api/chat, that takes the customer's messages and sends back Mali's answer as it is written. Farhan puts it plainly: the page shows, the route thinks.

What you build: 3 tasks

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

  1. Task 1

    server.ts: the chat route

    Export async function POST(req: Request): Promise<Response> from server.ts. Read the JSON body; if it is not JSON, or body.messages is not a list of UI messages (check it with safeValidateUIMessages from 'ai'), answer 400 with Response.json({ error: '...' }, { status: 400 }) and call no model.

    Otherwise call streamText with lab('lab-chat') and instructions MALI_INSTRUCTIONS (from ../../shared/mali.ts), and messages: every UI message turned into model messages with await convertToModelMessages(...). Return createUIMessageStreamResponse({ stream: toUIMessageStream({ stream: result.stream }) }).

    The Check posts its own chat: status 200, the header x-vercel-ai-ui-message-stream: v1, the events start, start-step, text-start, text-delta..., text-end, finish-step, finish, the model's own text; a follow-up with all 3 messages reaching the model; and 400 for {}, a body that is not JSON, an empty list, and a message with no id or parts.

  2. Task 2

    read-stream.ts: the stream, event by event

    Export async function readEvents(res: Response) from read-stream.ts: read res.body with getReader() and a TextDecoder, keep a buffer, and every time it holds a blank line (\n\n) parse the text after "data: " with JSON.parse; skip [DONE]. Return the events in order. The Check also feeds it a stream that arrives in 4 uneven pieces, with events cut in two.

    Under if (import.meta.main), call POST from ./server.ts with one user message, exactly: What is the shipping charge?

    Print each event's type on its own line, and for a text-delta also its delta with JSON.stringify (text-delta "Delivery"), then a last line: text: and all the deltas joined.

  3. Task 3 · interview question

    Interview: follow-up.ts, why send the whole chat?

    Post three times to your route (POST from ./server.ts) and read each answer with readEvents (./read-stream.ts): the user message Do you replace plants that arrive broken? on its own; then only the follow-up What about pots?; then all three: the first question, Mali's first answer as an assistant message, and the follow-up.

    Print first: ANSWER, last message only: ANSWER and whole conversation: ANSWER, one line each.

    Farhan will ask: why does a chat page send every message again on every post, and what does that do to a long chat's tokens?

What you will learn

  • Where the model call lives: page, route, model, and why the key stays on the server.
  • UI messages (what a page keeps) and model messages (what a model reads), and convertToModelMessages between them.
  • A route: POST(req: Request): Promise<Response>, the shape Next.js, Hono, Remix and Workers all use.
  • The UI message stream: the events a route sends, and how to read them.
  • lab serve, lab stream and the Requests pane: watching your route answer.
  • The whole conversation, every time, and a route that refuses a bad body.

More in The chat UI

Build The chat route 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.