Building AI features in Next.js

A tea advisor that answers word by word

The tea shop wants an advisor: Asha types "Which tea helps me sleep?" and gets an answer from a language model, a program that writes text in reply to text, run by a company like OpenAI or Anthropic (the model provider). Your app sends it a request with a secret API key, and the provider bills you for every request. A model writes its answer a few letters at a time, and a long answer takes seconds. So the page shows it as it comes, piece by piece.

This lesson uses the AI SDK (the ai package on npm, by the company behind Next.js), version 7.0.157. It works the same way with many providers. Here is the advisor: a page, a Client Component that asks, and a Route Handler that calls the model. It's a recording of a real Next.js 16.4.3 project, built with next build, run with next start and used in real Chrome. The model in every recording is a stand-in: a small server that answers the way a real provider does, with fixed words, and accepts a fake key. No recording called a real model.

1import { createTextStreamResponse, streamText, toTextStream } from "ai";2import { z } from "zod";3import { allowCall, currentUserId } from "../../_lib/guard";4import { model } from "../../_lib/model";5 6const Question = z.object({ question: z.string().trim().min(1).max(300) });7 8export async function POST(request: Request) {9  const userId = await currentUserId();10  if (!userId) return Response.json({ error: "Sign in to ask the advisor." }, { status: 401 });11 12  const parsed = Question.safeParse(await request.json().catch(() => null));13  if (!parsed.success) return Response.json({ error: "Ask a question of 1 to 300 characters." }, { status: 400 });14 15  if (!allowCall(userId)) {16    return Response.json({ error: "Three questions a minute. Try again soon." }, { status: 429 });17  }18 19  const result = streamText({20    model,21    instructions: "You are the tea shop's advisor. Answer in one or two sentences.",22    prompt: parsed.data.question,23    maxOutputTokens: 200,24    abortSignal: request.signal,25    onAbort: () => console.log(`${userId}'s request closed, so the model call stopped`),26    onEnd: ({ totalUsage }) => {27      console.log(`${userId} used ${totalUsage.inputTokens ?? "unknown"} input and ${totalUsage.outputTokens ?? "unknown"} output tokens`);28    },29  });30  return createTextStreamResponse({ stream: toTextStream({ stream: result.stream }) });31}

app/api/advice/route.ts answers POST /api/advice. Every call to the model costs the shop money, and anyone on the internet can post to this address, so lines 9 to 17 check three things first: who is asking (a signed-in user), what they ask (a question of 1 to 300 characters), and how often (three questions a minute). Each refusal answers with an error and never reaches the model; the checks section takes them one by one. Then lines 19 to 29 call streamText from ai:

• model: which model to ask. It comes from app/_lib/model.ts, which holds the provider's address and the key (the key section reads it).
• instructions, line 21: what the shop tells the model before every question. Providers call this the system message.
• prompt, line 22: Asha's question, as the check on line 12 read it.
• maxOutputTokens and abortSignal, lines 23 and 24: how much the model may write, and when to stop.

streamText returns at once, before the model has written anything. Line 30 turns its stream into a response that sends the answer as plain text, piece by piece. Open the Steps tab: Asha, already signed in, typed her question, clicked Ask, and the page showed Try chamomile: it has no caffeine and helps you relax.

Streaming the answer from a Route Handler

A provider streams its answer as server-sent events: lines of text that start with data: , each followed by a blank line. This is the start and the end of what the stand-in model streamed for Asha's question, in the format of OpenAI's API, which many providers also use:

data: {"id":"chatcmpl-tea","object":"chat.completion.chunk","created":1793300000,"model":"tea-advisor-1","choices":[{"index":0,"delta":{"content":"Try "},"finish_reason":null}]}

data: {"id":"chatcmpl-tea","object":"chat.completion.chunk","created":1793300000,"model":"tea-advisor-1","choices":[{"index":0,"delta":{"content":"chamomile: "},"finish_reason":null}]}

…

data: {"id":"chatcmpl-tea","object":"chat.completion.chunk","created":1793300000,"model":"tea-advisor-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":31,"completion_tokens":6,"total_tokens":37}}

data: [DONE]

Each event holds one piece of the answer in choices[0].delta.content: Try , then chamomile: . The last ones say why the model stopped (finish_reason), how many tokens it read and wrote (a token is a piece of a word; providers bill by tokens), and [DONE]. You never parse these yourself: the provider package, @ai-sdk/openai-compatible here, turns them into result.stream, a stream of events your route can read as they come.

Line 30 of the route turns that stream into a response. AI SDK 7 has two pairs of helpers for it, and each row is one of them:

In the Network tab, POST /api/advice, sent straight to the route with Asha's question, answered 200 with content-type: text/plain and the whole answer as its body. The recording keeps the body once it has all arrived; in the browser, it arrived in pieces. app/advisor.tsx reads those pieces:

"use client";

import { useState } from "react";

export function Advisor() {
  const [question, setQuestion] = useState("");
  const [answer, setAnswer] = useState("");

  async function ask() {
    setAnswer("");
    const response = await fetch("/api/advice", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ question }),
    });
    if (!response.ok) {
      setAnswer((await response.json()).error);
      return;
    }
    const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      setAnswer((old) => old + value);
    }
  }

  return (
    <>
      <input value={question} onChange={(event) => setQuestion(event.target.value)} aria-label="Your question" />
      <button onClick={ask}>Ask</button>
      <p>{answer}</p>
    </>
  );
}

Lines 11 to 15 post the question. Lines 16 to 19 show the error message when the route refuses, like a fourth question in a minute. Line 20 gets a reader for the body, decoded from bytes to text. The loop on lines 21 to 25 waits for each piece and adds it to answer, so React shows the answer growing. The Route Handlers lesson split its stream on new lines, because one read can hold half a line. Here that doesn't matter: the pieces are added in order, so however the text is cut, the page ends up with all of it.

And this is what the route sent the stand-in model, as the stand-in recorded it:

{
  "model": "tea-advisor-1",
  "max_tokens": 200,
  "messages": [
    {
      "role": "system",
      "content": "You are the tea shop's advisor. Answer in one or two sentences."
    },
    {
      "role": "user",
      "content": "Which tea helps me sleep?"
    }
  ],
  "stream": true
}

Line 2 names the model, and line 3 caps the answer at 200 tokens. Lines 4 to 13 are the messages: the instructions as a system message, then Asha's question as a user message. Line 14 asks for a stream. The request also carried an authorization header with the fake key from .env: the server sent the key, never the page.

Calling a model from a Server Action

A Server Action can call a model too. For a short answer that a form waits for, like a product description for the shop's staff, generateText asks the model and waits for the whole answer:

1"use server";2 3import { generateText } from "ai";4import { z } from "zod";5import { allowCall, currentUserId } from "../_lib/guard";6import { model } from "../_lib/model";7 8const Tea = z.string().trim().min(1).max(40);9 10export async function describeTea(previous: string, formData: FormData) {11  const userId = await currentUserId();12  if (!userId) return "Sign in to write descriptions.";13  const tea = Tea.safeParse(formData.get("tea"));14  if (!tea.success) return "Name a tea of 1 to 40 characters.";15  if (!allowCall(userId)) return "Three descriptions a minute. Try again soon.";16 17  const { text } = await generateText({18    model,19    instructions: "You write the tea shop's product descriptions. One sentence.",20    prompt: `Describe ${tea.data}.`,21    maxOutputTokens: 100,22  });23  return text;24}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/2gsxhio73malr.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/0ooaq-girjaeh.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <script src="/_next/static/chunks/02vzl2i0ae3y8.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <!--&-->
    <main>
      <h1>Describe a tea</h1>
      <!--F!-->
      <form action="" enctype="multipart/form-data" method="POST">
        <input type="hidden" name="$ACTION_REF_1">
        <input type="hidden" name="$ACTION_1:0" value="{&quot;id&quot;:&quot;60344250cce960b590c520fb6d4cdfe2d699c20365&quot;,&quot;bound&quot;:&quot;$@1&quot;}">
        <input type="hidden" name="$ACTION_1:1" value="[&quot;Mint tea is fresh and cool, with a sweet finish after every sip.&quot;]">
        <input type="hidden" name="$ACTION_KEY" value="k1e11587b2f37d02491b0759b426f1442">
        <input aria-label="Tea" name="tea" value="Mint tea">
        <button>Describe</button>
        <p>Mint tea is fresh and cool, with a sweet finish after every sip.</p>
      </form>
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

In app/describe/actions.ts, lines 11 to 15 make the same three checks as the route, with the helpers from app/_lib/guard.ts: a signed-in user, a tea name of 1 to 40 characters (line 8), and three calls a minute. A Server Action is a public endpoint too, so it never skips them. Lines 17 to 22 call generateText, which returns once the model has finished. maxOutputTokens: 100 on line 21 caps the length of the answer. Line 23 returns the text, and useActionState in describe-form.tsx shows it (Forms teaches it). The recording posted the form the way a browser does before the page's JavaScript loads, and the Network tab shows the page that came back, with Mint tea is fresh and cool, with a sweet finish after every sip. in it. The form was sent with Asha's session cookie, as her browser would send it.

To stream from a Server Action, the AI SDK has streamable values in the @ai-sdk/rsc package. The action returns a value at once, and keeps updating it as the model writes:

1"use server";2 3import { createStreamableValue } from "@ai-sdk/rsc";4import { streamText } from "ai";5import { z } from "zod";6import { allowCall, currentUserId } from "../_lib/guard";7import { model } from "../_lib/model";8 9const Question = z.string().trim().min(1).max(300);10 11export async function askAdvisor(question: unknown) {12  const userId = await currentUserId();13  if (!userId) return { error: "Sign in to ask the advisor." };14  const parsed = Question.safeParse(question);15  if (!parsed.success) return { error: "Ask a question of 1 to 300 characters." };16  if (!allowCall(userId)) return { error: "Three questions a minute. Try again soon." };17 18  const answer = createStreamableValue("");19  (async () => {20    try {21      const result = streamText({ model, instructions: "You are the tea shop's advisor. Answer in one or two sentences.", prompt: parsed.data, maxOutputTokens: 200 });22      for await (const part of result.stream) {23        if (part.type === "text-delta") answer.update(part.text);24        if (part.type === "error") throw part.error;25      }26      answer.done();27    } catch (error) {28      answer.error(error);29    }30  })();31  return { answer: answer.value };32}

In app/ask/actions.ts, lines 12 to 16 make the same checks and return an error message for a refused call. Line 18 makes the streamable value. The function on lines 19 to 30 runs without being awaited. It reads result.stream: line 23 sends each piece of text with answer.update, and line 24 turns an error from the provider into a thrown error. Every path ends the value: line 26 says it's done, and if anything failed, line 28 passes the error on with answer.error, so the browser isn't left waiting. Line 31 returns answer.value right away. In app/ask/ask-form.tsx, readStreamableValue on line 19 waits for each update in the browser, and lines 22 and 23 show a message if the value ended with an error. In the Steps tab, the click made one request, POST /ask, answered with text/x-component: the Server Action's answer, which went on streaming the updates.

A chat with useChat

A chat keeps a conversation: Asha asks, the advisor answers, Asha asks again. useChat from @ai-sdk/react is a hook that keeps the messages, sends them to a Route Handler, and reads the streamed answer into a new message:

1"use client";2 3import { useChat } from "@ai-sdk/react";4import { useState } from "react";5 6export function Chat() {7  const [input, setInput] = useState("");8  const { messages, sendMessage, status } = useChat();9 10  return (11    <>12      <ul>13        {messages.map((message) => (14          <li key={message.id}>15            {message.role === "user" ? "You: " : "Advisor: "}16            {message.parts.map((part) => (part.type === "text" ? part.text : "")).join("")}17          </li>18        ))}19      </ul>20      <p>{status === "ready" ? `${messages.length} messages` : "Thinking…"}</p>21      <form22        onSubmit={(event) => {23          event.preventDefault();24          sendMessage({ text: input });25          setInput("");26        }}27      >28        <input value={input} onChange={(event) => setInput(event.target.value)} aria-label="Message" />29        <button disabled={status !== "ready"}>Send</button>30      </form>31    </>32  );33}

In app/chat/chat.tsx:

• Line 8 calls useChat(). With no options it posts to /api/chat. It gives back messages, sendMessage, and status, which is "ready" when no answer is on its way.
• Lines 13 to 18 show each message. A message has parts; this page shows the text ones, after You: or Advisor: .
• Line 24 sends what Asha typed. Line 20 shows how many messages there are once the answer is done, and line 29 turns Send off while one is on its way.

The route behind it makes the same checks as the advisor's, and checks the conversation too:

import { convertToModelMessages, createUIMessageStreamResponse, streamText, toUIMessageStream, validateUIMessages } from "ai";
import { allowCall, currentUserId } from "../../_lib/guard";
import { model } from "../../_lib/model";

export async function POST(request: Request) {
  const userId = await currentUserId();
  if (!userId) return Response.json({ error: "Sign in to chat with the advisor." }, { status: 401 });

  const body = await request.json().catch(() => null);
  const messages = await validateUIMessages({ messages: body?.messages }).catch(() => null);
  if (!messages || messages.length > 20 || JSON.stringify(messages).length > 8000) {
    return Response.json({ error: "Send at most 20 messages, 8,000 characters in all." }, { status: 400 });
  }

  if (!allowCall(userId)) {
    return Response.json({ error: "Three questions a minute. Try again soon." }, { status: 429 });
  }

  const result = streamText({
    model,
    instructions: "You are the tea shop's advisor. Answer in one or two sentences.",
    messages: await convertToModelMessages(messages),
    maxOutputTokens: 200,
    abortSignal: request.signal,
  });
  return createUIMessageStreamResponse({ stream: toUIMessageStream({ stream: result.stream }) });
}

Lines 6 and 7 check who is asking. The messages come from the browser, so they're input like any other, and a browser can send any history, even an assistant message the model never wrote. Line 10 checks their shape with validateUIMessages, and line 11 refuses more than 20 messages or more than 8,000 characters in all. Lines 15 to 17 count the call. Line 22 turns the messages into the model's format with convertToModelMessages, lines 23 and 24 cap the answer and pass the signal, and line 26 answers with createUIMessageStreamResponse. In the Steps tab, Asha asked twice, and the page counted 4 messages. The stand-in always gives the same answer, which happens to fit both questions. In the Network tab, POST /api/chat shows the stream useChat reads: server-sent events like {"type":"text-delta","id":"txt-0","delta":"Try "}, and the header x-vercel-ai-ui-message-stream: v1.

Now look at what the route sent the model for Asha's second question:

{
  "model": "tea-advisor-1",
  "max_tokens": 200,
  "messages": [
    {
      "role": "system",
      "content": "You are the tea shop's advisor. Answer in one or two sentences."
    },
    {
      "role": "user",
      "content": "Which tea helps me sleep?"
    },
    {
      "role": "assistant",
      "content": "Try chamomile: it has no caffeine and helps you relax."
    },
    {
      "role": "user",
      "content": "And which one has no caffeine?"
    }
  ],
  "stream": true
}

Four messages: the instructions, her first question, the first answer, and her new question. The model keeps nothing between calls in this setup, so every call carries the whole conversation, and the provider reads, and bills, all of it again.

That's why a long chat costs more for every new question. Real chats cap how many messages they send, or replace old ones with a short summary; line 11's cap also stops one chat from growing without end.

Keeping the API key on the server

Anyone who has the key can call the model on your account. So the key lives in one module, which only the server may load:

import "server-only";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

// The model provider: its address and its key come from the server's environment.
const provider = createOpenAICompatible({
  name: "tea-model",
  baseURL: `${process.env.MODEL_API_URL}/v1`,
  apiKey: process.env.MODEL_API_KEY,
});

export const model = provider("tea-advisor-1");

Line 1, import "server-only", marks the module as server code (Server-only code and environment variables teaches it). Lines 5 to 9 make the provider: line 7 reads its address from MODEL_API_URL (in the recordings, the stand-in's address), and line 8 reads the key from MODEL_API_KEY, set in .env. Neither name starts with NEXT_PUBLIC_, so Next.js doesn't inline their values into the JavaScript it builds for the browser. That prefix only decides what gets inlined: it isn't access control. A key without it still reaches the browser the moment a component renders it or passes it to a Client Component. So the key is read in this one server-only module, used only to call the provider, and never rendered, returned or passed on. Line 11 picks the model. With a real provider, you'd use its own package, like @ai-sdk/openai, or its address here.

The advisor's recording looked for the key, and for the instructions, in every JavaScript file the page loads: neither was in any of them. Here is what happens when a Client Component tries to call the model itself:

1"use client";2 3import { streamText } from "ai";4import { useState } from "react";5import { model } from "./_lib/model";6 7export function Advisor() {8  const [question, setQuestion] = useState("");9  const [answer, setAnswer] = useState("");10 11  async function ask() {12    setAnswer("");13    const result = streamText({ model, prompt: question });14    for await (const piece of result.textStream) setAnswer((old) => old + piece);15  }16 17  return (18    <>19      <input value={question} onChange={(event) => setQuestion(event.target.value)} aria-label="Your question" />20      <button onClick={ask}>Ask</button>21      <p>{answer}</p>22    </>23  );24}

$ next build▲ Next.js 16.4.3 (Turbopack)- Environments: .env- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ... > Build error occurredError: Turbopack build failed with 2 errors:./app/_lib/model.ts:1:1Error: You're importing a module that depends on "server-only" into a React Client Component module. This API is only available in Server Components but one of its parents is marked with "use client", so this module is also a Client Component.    Learn more: https://nextjs.org/docs/app/building-your-application/rendering> 1 | import "server-only";    | ^^^^^^^^^^^^^^^^^^^^^  2 | import { createOpenAICompatible } from "@ai-sdk/openai-compatible";  3 |  4 | // The model provider: its address and its key come from the server's environment. Ecmascript file had an error Import traces:  App Route:    ./app/_lib/model.ts    ./app/api/advice/route.ts   Client Component Browser:    ./app/_lib/model.ts [Client Component Browser]    ./app/advisor.tsx [Client Component Browser]    ./app/advisor.tsx [Server Component]    ./app/page.tsx [Server Component]   Client Component SSR:    ./app/_lib/model.ts [Client Component SSR]    ./app/advisor.tsx [Client Component SSR]    ./app/advisor.tsx [Server Component]    ./app/page.tsx [Server Component] ./app/_lib/model.ts:1:1Error: 'server-only' cannot be imported from a Client Component module> 1 | import "server-only";    | ^^^^^^^^^^^^^^^^^^^^^  2 | import { createOpenAICompatible } from "@ai-sdk/openai-compatible";  3 |  4 | // The model provider: its address and its key come from the server's environment. It should only be used from a Server Component. Import traces:  App Route:    ./app/_lib/model.ts    ./app/api/advice/route.ts   Client Component Browser:    ./app/_lib/model.ts [Client Component Browser]    ./app/advisor.tsx [Client Component Browser]    ./app/advisor.tsx [Server Component]    ./app/page.tsx [Server Component]   Client Component SSR:    ./app/_lib/model.ts [Client Component SSR]    ./app/advisor.tsx [Client Component SSR]    ./app/advisor.tsx [Server Component]    ./app/page.tsx [Server Component]     at ignore-listed frames

Line 5 of this app/advisor.tsx imports the model module, and line 13 calls streamText in the browser. The build stops: You're importing a module that depends on "server-only" into a React Client Component module. Without line 1 of the model module, it would have built, and the module's code would have gone to the browser. Each row is one place a key could be:

Checks, limits and costs

A Route Handler is a public address: anyone can post to /api/advice, from any program, as often as they like, and every call costs the shop money. So before the model is called, the advisor's route checks who is asking, what they ask, and how often. This recording sends it six requests, one after the other:

1import { createTextStreamResponse, streamText, toTextStream } from "ai";2import { z } from "zod";3import { allowCall, currentUserId } from "../../_lib/guard";4import { model } from "../../_lib/model";5 6const Question = z.object({ question: z.string().trim().min(1).max(300) });7 8export async function POST(request: Request) {9  const userId = await currentUserId();10  if (!userId) return Response.json({ error: "Sign in to ask the advisor." }, { status: 401 });11 12  const parsed = Question.safeParse(await request.json().catch(() => null));13  if (!parsed.success) return Response.json({ error: "Ask a question of 1 to 300 characters." }, { status: 400 });14 15  if (!allowCall(userId)) {16    return Response.json({ error: "Three questions a minute. Try again soon." }, { status: 429 });17  }18 19  const result = streamText({20    model,21    instructions: "You are the tea shop's advisor. Answer in one or two sentences.",22    prompt: parsed.data.question,23    maxOutputTokens: 200,24    abortSignal: request.signal,25    onAbort: () => console.log(`${userId}'s request closed, so the model call stopped`),26    onEnd: ({ totalUsage }) => {27      console.log(`${userId} used ${totalUsage.inputTokens ?? "unknown"} input and ${totalUsage.outputTokens ?? "unknown"} output tokens`);28    },29  });30  return createTextStreamResponse({ stream: toTextStream({ stream: result.stream }) });31}

{"question":"Which tea helps me sleep?"}

{"error":"Sign in to ask the advisor."}

• Who is asking. Lines 9 and 10 call currentUserId from app/_lib/guard.ts, which reads the signed session cookie from Authentication (app/_lib/session.ts is that lesson's file). No valid session: 401.
• What they ask. Line 6 says what a question is: text of 1 to 300 characters once spaces are trimmed. Line 12 checks the body with Zod, and line 13 answers 400 for anything else.
• How often. Lines 15 to 17 allow three model calls a minute for each user: allowCall in app/_lib/guard.ts uses allowTry from Securing Server Actions. Its counter lives in this one server's memory; with several servers or serverless functions, keep it in a shared store like Redis.
• How much. Line 23, maxOutputTokens: 200, caps how many tokens the model may write for one answer.

In the Network tab, the six requests answered 401, 400, 200, 200, 200 and 429. The stand-in model received only three calls, each with "max_tokens":200 in its body: the refused requests never reached it, so they cost nothing. Lines 26 to 28 print what each call used, from totalUsage, once the answer has finished; the Terminal shows u1 used 31 input and 6 output tokens three times. AI SDK 7 types these counts as optional: a provider may leave them out, so line 27 prints unknown instead of a number, and code that saves them per user must handle a missing count.

Stopping the call when the visitor leaves

Line 24 passes request.signal to streamText. A signal (an AbortSignal) is an object that says when something should stop. With next start, Next.js aborts a Route Handler's request.signal when the visitor's request closes: they closed the tab, or clicked Stop. This advisor has a Stop button, and the stand-in model never finishes its answer, the way a long answer would still be on its way:

1import { createTextStreamResponse, streamText, toTextStream } from "ai";2import { z } from "zod";3import { allowCall, currentUserId } from "../../_lib/guard";4import { model } from "../../_lib/model";5 6const Question = z.object({ question: z.string().trim().min(1).max(300) });7 8export async function POST(request: Request) {9  const userId = await currentUserId();10  if (!userId) return Response.json({ error: "Sign in to ask the advisor." }, { status: 401 });11 12  const parsed = Question.safeParse(await request.json().catch(() => null));13  if (!parsed.success) return Response.json({ error: "Ask a question of 1 to 300 characters." }, { status: 400 });14 15  if (!allowCall(userId)) {16    return Response.json({ error: "Three questions a minute. Try again soon." }, { status: 429 });17  }18 19  const result = streamText({20    model,21    instructions: "You are the tea shop's advisor. Answer in one or two sentences.",22    prompt: parsed.data.question,23    maxOutputTokens: 200,24    abortSignal: request.signal,25    onAbort: () => console.log(`${userId}'s request closed, so the model call stopped`),26    onEnd: ({ totalUsage }) => {27      console.log(`${userId} used ${totalUsage.inputTokens ?? "unknown"} input and ${totalUsage.outputTokens ?? "unknown"} output tokens`);28    },29  });30  return createTextStreamResponse({ stream: toTextStream({ stream: result.stream }) });31}

It's the same route: line 24 passes the signal, and line 25 logs when it fires. In app/advisor.tsx, the Stop button calls abort() on the AbortController whose signal the fetch got. In the Steps tab, the page showed Try chamomile, then Stopped. The Terminal shows u1's request closed, so the model call stopped, and the stand-in model recorded that its request was closed before the answer had ended. Step through it:

Without line 24, the route would go on reading words nobody will see. Whether the provider stops writing, and what it bills for an answer cut short, depends on the provider. One limit to know: a stream from a Server Action can't be cancelled this way.

The model's answer is untrusted

A model follows text, and it can't reliably tell your instructions from text written by someone else. Prompt injection is text that tells the model to break its instructions: a user typing "ignore your rules and…", or a sentence hidden in a review, a web page or a file that the model is asked to read. No instruction you write stops it for sure. So treat the answer like any other input from outside: it may hold anything.

The first place that matters is the page. Here the stand-in model answers with text that holds an HTML tag, as an injected answer might. Before you pick a version, guess what each one shows.

1"use client";2 3import { useState } from "react";4 5export function Advisor() {6  const [question, setQuestion] = useState("");7  const [answer, setAnswer] = useState("");8 9  async function ask() {10    setAnswer("");11    const response = await fetch("/api/advice", {12      method: "POST",13      headers: { "Content-Type": "application/json" },14      body: JSON.stringify({ question }),15    });16    if (!response.ok) {17      setAnswer((await response.json()).error);18      return;19    }20    const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();21    while (true) {22      const { value, done } = await reader.read();23      if (done) break;24      setAnswer((old) => old + value);25    }26  }27 28  return (29    <>30      <input value={question} onChange={(event) => setQuestion(event.target.value)} aria-label="Your question" />31      <button onClick={ask}>Ask</button>32      <p>{answer}</p>33    </>34  );35}

Shown as text, the tag is only characters on the page: React escapes text it puts in the page, so nothing runs. Used as HTML, Chrome built a real <img>, its address x failed with a 404, and the code in its onerror ran and wrote Injected code ran. Injected code can do anything the page's own code can, like send the visitor's data elsewhere. Keep answers as text. If you show the answer as Markdown, the renderer must:

• keep raw HTML in the Markdown turned off, so a tag stays text;
• allow only safe link and image addresses, like https: and mailto:, and never javascript:;
• sanitise the HTML it produces whenever any step does produce HTML, since a plugin can add some.

A Content Security Policy is a second wall behind that.

The second place is tools: functions you let the model call, like looking up an order. The model chooses the arguments, so treat them as untrusted too, and check access in your own code, as for any request:

import { streamText, tool, type ModelMessage } from "ai";
import { z } from "zod";
import { getCurrentUser } from "@/lib/dal";
import { findOrder } from "@/lib/db";
import { model } from "@/app/_lib/model";

export async function answerAboutOrders(messages: ModelMessage[]) {
  // Who is asking comes from the session, on the server: never from the model.
  const user = await getCurrentUser();
  if (!user) throw new Error("Sign in first");
  return streamText({
    model,
    instructions: "You answer questions about the customer's orders.",
    messages,
    maxOutputTokens: 200,
    tools: {
      orderStatus: tool({
        description: "Look up one of the signed-in customer's orders",
        inputSchema: z.object({ orderId: z.number().int() }),
        // The model chose orderId, so check that the order is this user's.
        execute: async ({ orderId }) => {
          const order = await findOrder(orderId);
          return order?.userId === user.id ? order.status : "No such order";
        },
      }),
    },
  });
}

Line 9 reads the signed-in user on the server, with getCurrentUser from the data access layer, before the model runs, and line 10 stops without one. Lines 17 to 25 define the tool: a description the model reads, the shape of its input (checked with Zod), and execute, your code. The model only chooses orderId; line 23 returns the order's status only if the order's userId is the signed-in user's. The model never chooses whose data it reads. Give tools only what the user may do anyway, and ask the user to confirm anything that can't be undone. One more guard: by default, the AI SDK refuses system messages inside prompt or messages, so your rules belong in instructions. The option allowSystemInMessages: true turns that off; use it only for a history your own server wrote, never one a browser sent.

Checking the advisor before it ships

Before the advisor goes live, go through its choices. Sort each one: safe to ship, or fix it first?

Common mix-ups

• "The browser can call the model directly with a public key." No. A NEXT_PUBLIC_ key is in the browser's code, where anyone can copy it. Call the model from the server.
• "Good instructions make the answer safe." No. Prompt injection can make the model ignore them. Show the answer as text, and check access in tools.
• "The model remembers the chat." No. In the recorded chat, each call sent the whole conversation, and the provider read all of it again.
• "Closing the tab stops the model call." Only if the route passes request.signal to streamText. Otherwise the server keeps reading the answer.
• "A rate limit after the call is as good as one before." No. Every call that reaches the model is billed. Count first: the refused fourth question never reached the stand-in.
• "Streaming needs Server Actions." No. A Route Handler streams, and the AI SDK recommends that for production; streams from Server Actions are experimental and can't be cancelled.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

.env
app/_lib/model.ts
app/advisor.tsx
app/api/advice/route.ts
app/layout.tsx
app/page.tsx

import "server-only";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

// The model provider: its address and its key come from the server's environment.
const provider = createOpenAICompatible({
  name: "tea-model",
  baseURL: `${process.env.MODEL_API_URL}/v1`,
  apiKey: process.env.MODEL_API_KEY,
});

export const model = provider("tea-advisor-1");

import { createTextStreamResponse, streamText, toTextStream } from "ai";
import { z } from "zod";
import { allowCall, currentUserId } from "../../_lib/guard";
import { model } from "../../_lib/model";

const Question = z.object({ question: z.string().trim().min(1).max(300) });

export async function POST(request: Request) {
  const userId = await currentUserId();
  if (!userId) return Response.json({ error: "Sign in to ask the advisor." }, { status: 401 });

  const parsed = Question.safeParse(await request.json().catch(() => null));
  if (!parsed.success) return Response.json({ error: "Ask a question of 1 to 300 characters." }, { status: 400 });

  if (!allowCall(userId)) {
    return Response.json({ error: "Three questions a minute. Try again soon." }, { status: 429 });
  }

  const result = streamText({
    model,
    instructions: "You are the tea shop's advisor. Answer in one or two sentences.",
    prompt: parsed.data.question,
    maxOutputTokens: 200,
    abortSignal: request.signal,
    onAbort: () => console.log(`${userId}'s request closed, so the model call stopped`),
    onEnd: ({ totalUsage }) => {
      console.log(`${userId} used ${totalUsage.inputTokens ?? "unknown"} input and ${totalUsage.outputTokens ?? "unknown"} output tokens`);
    },
  });
  return createTextStreamResponse({ stream: toTextStream({ stream: result.stream }) });
}

1. No session cookie, a good question.
2. Asha's session, the question "   ".
3. Asha's session, "Which tea helps me sleep?"
4. Asha's session, the same question again.
5. Asha's session, the same question a third time.
6. Asha's session, the same question a fourth time.

"use client";

import { useState } from "react";

export function Advisor() {
  const [question, setQuestion] = useState("");
  const [answer, setAnswer] = useState("");

  async function ask() {
    setAnswer("");
    const response = await fetch("/api/advice", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ question }),
    });
    if (!response.ok) {
      setAnswer((await response.json()).error);
      return;
    }
    const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      setAnswer((old) => old + value);
    }
  }

  return (
    <>
      <input value={question} onChange={(event) => setQuestion(event.target.value)} aria-label="Your question" />
      <button onClick={ask}>Ask</button>
      <p dangerouslySetInnerHTML={{ __html: answer }} />
    </>
  );
}

"use client";

import { useState } from "react";

export function Advisor() {
  const [question, setQuestion] = useState("");
  const [answer, setAnswer] = useState("");

  async function ask() {
    setAnswer("");
    const response = await fetch("/api/advice", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ question }),
    });
    if (!response.ok) {
      setAnswer((await response.json()).error);
      return;
    }
    const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      setAnswer((old) => old + value);
    }
  }

  return (
    <>
      <input value={question} onChange={(event) => setQuestion(event.target.value)} aria-label="Your question" />
      <button onClick={ask}>Ask</button>
      <p>{answer}</p>
    </>
  );
}

"use client";

import { streamText } from "ai";
import { useState } from "react";
import { model } from "./_lib/model";

export function Advisor() {
  const [question, setQuestion] = useState("");
  const [answer, setAnswer] = useState("");

  async function ask() {
    setAnswer("");
    const result = streamText({ model, prompt: question });
    for await (const piece of result.textStream) setAnswer((old) => old + piece);
  }

  return (
    <>
      <input value={question} onChange={(event) => setQuestion(event.target.value)} aria-label="Your question" />
      <button onClick={ask}>Ask</button>
      <p>{answer}</p>
    </>
  );
}

A. Call the model with maxOutputTokens: 200.
B. Check the question is 1 to 300 characters.
C. Check who is asking.
D. Count this user's calls this minute.

Check your understanding

For each question, ask where the code runs, what reaches the model, and what the page does with the answer.

Key takeaways

• Call the model from the server. streamText returns at once; a Route Handler sends its answer as plain text with createTextStreamResponse, or for useChat with createUIMessageStreamResponse.
• A Server Action can call generateText for a short answer a form waits for. Streams from Server Actions (@ai-sdk/rsc) are experimental and can't be cancelled.
• useChat keeps the messages and sends all of them on every call, so long chats cost more each time.
• Keep the key in a variable without NEXT_PUBLIC_, read in a module that starts with import "server-only".
• Before the model: check the session, validate the input, and count calls per user. Cap answers with maxOutputTokens, and pass request.signal so the call stops when the visitor leaves.
• The answer is untrusted: show it as text, never as HTML, and check access in your own code before a tool does anything.

Coming next: Core Web Vitals, the first lesson of the Production stage: measuring how fast the app feels to real visitors, and fixing the usual causes in a Next.js app.