Build a Next.js 16 AI Chatbot: AI SDK Tutorial from Scratch

A Next.js 16 AI chatbot built on the Vercel AI SDK is the shortest path from a blank repo to a production-shaped agentic interface. Eight steps, roughly 600 lines of TSX, and a deploy that lands on Vercel with streaming, tool calls, and provider switching wired from day one. This tutorial is the canonical reference build.

The reason this stack matters right now: chatbots are the visible tip of the agentic iceberg. The same primitives that power a customer-facing chat surface — streaming responses, tool invocations, structured outputs, provider abstraction — power every higher-order agent built on top. Getting the chat layer right is what compounds when you add retrieval, memory, and multi-turn planning later.

What this guide covers: scaffolding with create-next-app on the App Router; an /api/chat route handler running streamText; the useChat hook on the client; a shadcn/ui-styled message list with auto-scroll; Zod tool schemas executed server-side and rendered client-side; single-env-var provider switching across Anthropic, OpenAI, Google, and xAI; rate limiting, error boundaries, and abuse protection; and a one-command Vercel deploy. Code is copy-pasteable. No prior AI SDK experience assumed.

The starting point is a fresh Next.js 16 app on the App Router with TypeScript and Tailwind enabled by default. The non-default choices: turn on the App Router (it is the default in 16, but confirm during the prompt), keep Turbopack as the bundler, and decline the src/ directory unless your team's convention requires it. The chatbot lives entirely under app/ and components/.

The three install commands

Three terminal steps get the dependencies in place. The AI SDK 6 line includes the React bindings, the core, and one or more provider packages. We install all four mainstream providers up front so the provider-switch section is a one-line change later, not a re-installation.

One tsconfig adjustment is worth making early: ensure moduleResolution is "bundler" and target is at least "ES2022". The AI SDK uses native ReadableStream APIs and top-level await patterns that older module resolutions stumble on. The create-next-app default already lands here in Next.js 16, but verify after install — a one-line mistake here produces opaque "cannot resolve" errors three sections from now.

Add a single environment variable to .env.local before going further: ANTHROPIC_API_KEY=sk-ant-…. The tutorial defaults to Claude Sonnet 4.7 because the streaming and tool-calling APIs are the most stable across providers right now; swap providers in Section 06.

The three install commands above produce a project tree with roughly forty files — most of them shadcn-generated UI source. The chatbot itself will live in two new files we add over the next two sections: app/api/chat/route.ts (the server-side route handler) and components/chat.tsx (the client component). The tutorial's full surface area is small on purpose; the rest of the repo is scaffolding that ships with create-next-app and shadcn.

One scaffold-time decision worth making consciously: the App Router defaults to colocating components inside app/ rather than under a separate components/ directory. For a chatbot that may grow into a multi-surface product, keep components/chat/ as a sibling directory — the chat will eventually be embedded in marketing pages, dashboards, and possibly a public widget, and a top-level component directory keeps the import paths clean. The shadcn primitives go in components/ui/ by default and should stay there.

The server-side surface is a single App Router route handler at app/api/chat/route.ts. It accepts POST requests carrying a JSON body with the conversation history, invokes streamText against the chosen model, and returns the stream as a UI-Message response that useChat knows how to consume on the client. Roughly 30 lines for the minimum viable shape.

The full minimum route

Two patterns to internalize here. First, convertToModelMessages is the bridge between the client's UIMessage shape (which carries tool-call parts, attachments, and ID metadata for React's reconciliation) and the provider-neutral model message shape that streamText expects. Always convert at the boundary — never pass UI messages directly to the model. Second, result.toUIMessageStreamResponse() returns the Server-Sent-Events stream in the protocol that useChat consumes natively. No manual JSON chunking, no per-provider decoder.

maxDuration = 30 caps the route at 30 seconds, which is comfortable for Sonnet-class responses on the Vercel Hobby and Pro plans. Bump to 60 if you expect long reasoning traces with Think Max mode; bump to 300 only on the Enterprise plan where the function timeout ceiling is raised. The route is a Node.js runtime by default — that is the right choice when calling third-party SDKs, which often rely on Node-only APIs. Switch to the Edge runtime only when you have measured a latency benefit and confirmed no Node dependencies.

A note on the system prompt. The AI SDK passes whatever string you put in system as a top-level system message to the provider, ahead of the converted message history. Keep this string tight and behavior-shaping rather than knowledge-loading — the model is already smart, what it needs from you is constraints, tone, and tool-use policy. A useful template is three sentences: (1) the assistant's role and audience, (2) the output style (length, format, citation policy), (3) the tool-use policy (when to invoke search, how to handle ambiguous queries, when to ask a clarifying question). Anything longer tends to drift into knowledge that belongs in the retrieved context, not the static prompt.

For multi-turn conversations, the AI SDK automatically passes the entire messages array on every turn, which gives the model perfect context within its window. For extremely long conversations that approach the context limit, implement a summarization step at, say, turn 30 — generate a structured summary of turns 1–25, replace those turns with a single system message containing the summary, and continue. The AI SDK's generateObject with a Zod schema is the right tool for the summarization step; reserve streamText for the user-facing assistant turns.

The client side is a single React component marked 'use client' that calls useChat() and renders the returned message array. The hook owns everything you would otherwise hand-build: streaming reassembly, optimistic user-message insertion before the server responds, abort signals on form re-submit, message ID generation, and tool-call part rendering.

What the hook returns

The shape is small enough to memorize. messages is the ordered array of UI messages, each with a stable id, a role of user or assistant, and a parts array carrying text, tool calls, and tool results. sendMessage(text) appends a user message and triggers the server call. status is one of ready / submitted / streaming / error. stop() aborts an in-flight stream. regenerate() retries the last assistant turn.

Two implementation rules to lock in early. First, always render from the parts array, never from a presumed content string. The AI SDK 6 message shape is part-oriented because a single assistant turn can interleave text, tool calls, tool results, and reasoning traces — flattening to a string loses tool-call UX and breaks the moment you add a tool in Section 05. Second, never mutate messages directly; the hook owns the array and exposes setMessages only for advanced cases (initial-history hydration, server-side persistence). Treat it as read-only in everyday rendering.

status is the prop that drives the perceived-quality half of this UX. While the value is streaming, the input should be disabled and a streaming indicator should render on the assistant placeholder. When it flips to ready, re-enable the input and focus it. The reference useChat hook in @ai-sdk/react handles the optimistic user-message insertion before the network round trip completes — that is what eliminates the "did my message send?" perception gap you get from a naive fetch-and-render implementation.

The minimum chat from Section 03 is ugly on purpose — clean primitives are easier to reason about. The production-shaped UI adds five pieces on top: a Card-based message list with role badges, an auto-scroll anchor pinned to the latest message, a multiline Textarea with Cmd+Enter submission, role-aware bubble styling, and a streaming skeleton on the assistant placeholder while status === 'streaming'.

shadcn/ui is the right component library for this surface because it generates source files into your repo rather than installing a black-box dependency — every variant of every bubble is a file you own and can edit. The five components installed in Section 01 cover the entire chat scaffold: Card for message wrappers, Button for the send action, Textarea for input, ScrollArea for the message column, and Input as a fallback.

The three message visual states

The grid below shows the three rendering states the message list cycles through. Get all three right and the chat reads as production polish. Skip the streaming state and the chat feels broken; skip the role badges and the conversation gets confusing past the third turn.

Auto-scroll is the one piece teams get wrong most often. The wrong implementation re-scrolls on every token, which feels janky and breaks user-initiated up-scroll. The right implementation checks whether the user is currently within ~120 pixels of the bottom on each render; if so, snap to bottom on the next frame, if not, leave the scroll position alone. Use a ref on a sentinel <div /> at the bottom of the list and an IntersectionObserver; do not call scrollIntoView on every message append.

Markdown rendering should be done with a sanitizing pipeline. react-markdown plus rehype-sanitize plus remark-gfm covers tables, task lists, and inline code. For syntax-highlighted code blocks, shiki renders server-side at request time — slower than a raw <pre> but produces the best-looking output and keeps the bundle small. Lazy-load shiki only when an assistant message contains a code fence.

Tools are where the chatbot stops being a Q&A surface and becomes an agentic interface. The AI SDK 6 implementation is the cleanest of any major framework: define each tool with a name, a Zod input schema, a description, and an execute function that runs server-side. The SDK handles routing the model's structured tool-call output to your function and streaming the result back as a part on the assistant message.

Two example tools

A web search tool and a URL fetch tool are the canonical pair — together they make the chatbot research-capable without any RAG infrastructure. Add them to the streamText call as a tools object. The model decides when to invoke either; the SDK serializes the calls and waits for results before continuing generation.

stopWhen: stepCountIs(5) caps the agent loop at five tool-call rounds per assistant turn. The AI SDK's multi-step tool loop will keep invoking execute functions and feeding results back to the model until the model emits a final text response or the cap is hit. Five is a reasonable default for chat — high enough to handle "search, fetch one result, answer" chains, low enough to bound cost on a runaway loop.

For client-side tool rendering, the part shape is { type: 'tool-call', toolName, args, toolCallId } on the request side and { type: 'tool-result', toolName, result, toolCallId } on the response side. Render the request as a skeleton card ("Searching for <query>…"); render the result as a structured card with click-through. Cite the tool result in any follow-up text rendered by the model. This citation UX is what differentiates a real research agent from a chatbot that hallucinates URLs.

The provider-adapter pattern is the AI SDK's quiet superpower. Every adapter exports a function that returns a model object implementing the same internal interface, which means swapping anthropic('claude-sonnet-4-7') for openai('gpt-5-5') is a one-line change. No re-shaping of messages, no per-provider stream parsing, no per-provider tool-call format.

The adapter pattern in the route handler

Drive provider selection from an environment variable so production deploys can flip providers without a redeploy. Implement a thin getModel() helper that reads process.env.AI_PROVIDER and returns the appropriate model. Cache the result on first call.

The matrix below summarizes the four mainstream providers as of May 2026. Pick a default based on the workload's quality-cost target, then keep the switch in place so you can re-route when prices shift or a new generation lands. Provider lock-in is the silent killer of long-lived AI products; the SDK eliminates it.

One operational note on Anthropic specifically: the prompt caching feature is materially valuable for chatbots with a stable system prompt. Mark the system message as cacheable in the provider options, and subsequent requests within the five-minute cache window pay only 10% of the input-token cost for the cached prefix. For a chatbot that handles 1,000 sessions a day with a 500-token system prompt, this is the difference between a meaningful and a trivial monthly bill. The other providers have similar but less mature implementations; the pattern is worth implementing the moment you settle on a default provider.

For production deployments, do not hard-code AI_PROVIDERas a single value. Instead, configure a small routing layer that picks the provider per request based on the workload signature — a "default to Sonnet, route code questions to GPT-5.5, route long-document Q&A to Gemini" policy can run inside the route handler with no extra infrastructure. The Vercel AI Gateway is a managed alternative covered in Section 08; both work with the same adapter pattern.

A pragmatic note on tool ergonomics. Keep tool schemas tight — three or four required arguments, no unbounded freeform fields, descriptions written for the model not for the human reader. The model uses the description text to decide when to invoke each tool, so phrase descriptions in terms of the trigger condition ("Search the public web for current information when the question cannot be answered from training data alone") rather than the mechanism ("Calls the Bing Search API"). The difference in tool-call accuracy is large and shows up immediately in production evals.

The four pieces between "demo running on localhost" and "chatbot deployed in front of real users" are rate limiting, error boundaries on the client, abuse protection on the route, and an auth gate when the chatbot is anything other than fully public. Each is a 20-to-50-line change and the order below is the order to ship them in.

Upstash rate limit at the edge

Add Upstash Redis as a Vercel Marketplace integration (free tier covers small-app traffic), then wrap the route in a per-IP and per-user rate limit using @upstash/ratelimit. A sliding-window limit of 10 requests per 10 seconds and 100 per hour catches both burst-abuse and sustained-abuse vectors without inconveniencing legitimate users. The check runs before the expensive streamText call, so a blocked request costs effectively nothing.

The order in which these four pieces ship matters more than the specific implementations. Rate limiting first because it protects every other piece — without it, the first abuse incident is a multi-thousand-dollar provider bill. Error boundaries second because they prevent a single malformed message from breaking the entire chat surface for every other user in that session. Abuse protection third because by this point you have logging and rate limits to inform the policy. Auth last because every chat that needs persistent identity or per-user policy needs auth, but the chatbot can ship to a limited beta before that is in place. Skipping any of the four is a recoverable mistake; shipping them in the wrong order usually means re-shipping them under deadline pressure during an incident.

Client-side error boundaries are the second piece. The AI SDK's client is robust, but the wider chat surface — markdown rendering, syntax highlight, custom tool-result cards — can crash on malformed input. Wrap <Chat /> in a React ErrorBoundary that catches render-time crashes and offers a "reload conversation" affordance. Pair with an onError callback on useChat to surface server-side failures (rate-limit blocks, provider errors, timeouts) as inline toast messages, not as silent dead-end states.

Abuse protection beyond rate limiting is mostly about input filtering. The simplest effective layer is a tool that refuses requests matching prompt-injection patterns or known jailbreaks before they reach the model. Keep the filter narrow — overly aggressive filtering frustrates legitimate users — and log every block so you can tune the rule set. For higher-stakes deployments, layer a moderation API call (OpenAI's free moderation endpoint or Anthropic's classifier) before streamText on every inbound user message.

For teams interested in the cost-per-token side of the picture before committing to a provider default, our LLM API pricing index for Q2 2026 tracks the input and output rates across the major providers, normalizes batch and caching discounts, and projects monthly spend at realistic chat volumes. Re-check the index quarterly; the cost-quality frontier is the single most volatile variable in this stack and the provider-adapter pattern only pays off if you are actually willing to switch when the math changes.

Authentication is the fourth piece and the one most often deferred. Even for fully public chats, identify the user via a signed cookie so per-user rate limits are meaningful and so conversation history can be persisted later. Supabase Auth ( our preferred default) and Clerk both integrate cleanly with the App Router. The session is read inside the route handler and threaded into the rate-limit key.

The deploy step is the easiest of the eight. Run vercel deploy --prod from the repo root after linking the project. Vercel detects Next.js 16, builds with Turbopack, and ships the route handler as a Node.js Serverless Function. The first prod URL is live in under three minutes on an unprimed cache.

The env-var checklist

Before the first prod deploy, set the provider keys and any integration tokens in the Vercel project's Environment Variables settings — or better, pull them locally with vercel env pull after configuring the production environment. The minimum set is ANTHROPIC_API_KEY (or the equivalent for your chosen default), UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN for rate limiting, and AI_PROVIDER if you want to override the default.

Region selection matters for latency. By default, the route handler runs in the deployment's primary region. For chat that calls Anthropic or OpenAI endpoints, US-East (iad1) is the lowest-latency choice today — both providers route from US-East datacenters. Pin the function region in vercel.json if your overall deployment lives elsewhere. The P50 first-token latency in the stats card above reflects this configuration.

Optional: Vercel AI Gateway

For production deployments running multiple providers, the Vercel AI Gateway is worth considering as a managed replacement for the routing layer in Section 06. It exposes a single endpoint that routes to underlying providers based on configured policies, with built-in caching, retries, and observability. The adapter pattern still works; you point the SDK at the Gateway base URL instead of the vendor's API and keep the rest of the code unchanged. Costs scale with usage; evaluate against rolling your own.

A second deploy-time consideration: streaming responses behave differently on different hosting platforms. Vercel's Serverless Function runtime supports streaming natively via the platform's edge-aware response transport. On other platforms — particularly self-hosted Node containers behind older reverse proxies — you may need to disable response buffering at the proxy layer (Nginx proxy_buffering off;, Cloudflare's "Buffering" set to off) to see token-by-token output reach the client. Test the streaming behavior end-to-end on the actual deployment target before assuming it works.

Observability is the under-discussed part of running this in production. The minimum useful signal is structured logging of every assistant turn — provider, model, total input tokens, total output tokens, total tool-call count, total latency, cost estimate. Pipe to your existing observability layer (Datadog, Honeycomb, Vercel's built-in analytics, or a custom Postgres table) and alert on latency percentile shifts and on unusual token-consumption patterns. The AI SDK's onFinish callback on streamText is the right hook for this — it fires once per turn with the full usage breakdown.

What this build becomes when you keep going: add retrieval- augmented generation against a pgvector store for grounded answers (we cover that in our self-hosted RAG tutorial); add persistent multi-turn memory in a conversations table; expose the same agent as an MCP server for desktop assistants per our MCP server tutorial; or wire it to a workplace chat surface like Slack via the event subscriptions pattern. The chat surface in this tutorial is the foundation; every subsequent agentic capability composes on top of it.

One more deploy-time note worth internalizing: production chat surfaces should ship behind a feature flag for the first week of real traffic. Vercel Edge Config or a simple Postgres row both work — the goal is to be able to disable the chat without a redeploy if a provider has an outage, a cost-runaway bug ships, or a tool integration breaks. The flag check goes at the top of the route handler and returns a friendly 503 with a "temporarily unavailable" message if disabled. Costs nothing; saves the one bad afternoon every production chatbot eventually has.