Next.js AI SDK
Overview
Build AI product features with the Vercel AI SDK: server route handlers for streaming, Zod-validated tool schemas, and thin client UI. Keep secrets and model calls on the server.
Process
- Add or extend
app/api/chat/route.tswithstreamText(or equivalent) — never call providers from client components with secret keys. - Define tools with Zod schemas in
lib/tools.ts(or colocated modules); return typed, small results agents/UI can render. - Prefer structured outputs (
generateObject/ schema) when the UI needs a known shape instead of free-form prose. - Keep
app/page.tsx(or chat UI) as a client leaf; pass messages to the API route only. - Verify with
npm run typecheckandnpm run build. Smoke the chat UI withnpm run devwhen changing streaming behavior.
Guidelines
- Read
OPENAI_API_KEY(or provider env) only on the server. - Validate all tool arguments with Zod; reject unknown keys.
- Document model id and provider choice in code comments when non-default.
- For browser QA of the chat UI, use the project Playwright MCP (see AGENTS.md).
- Re-check secrets and data exposure with
project-securitybefore shipping.
Anti-patterns
- Exposing API keys via
NEXT_PUBLIC_*. - Untyped tool arguments or free-form JSON without a schema.
- Doing privileged tool work in the browser.
- Giant route handlers mixing UI strings, prompts, and business logic.


