I spent two hours last Thursday rewriting the chat endpoint of a side project because my own code was driving me up a wall. I’d built it six months ago with the raw OpenAI Node SDK, a custom SSE stream, a home-rolled tool-call parser, and a state machine that felt clever at the time and reads like a ransom note now.<\/p>\n
Short version: I moved it to Vercel AI SDK v5 and about a third of the file got deleted. Not refactored. Deleted. That’s usually the sign of a good abstraction.<\/p>\n
I’m not here to tell you the SDK is magic or that it’s the future of AI apps. I’ll tell you what the migration felt like, which parts saved me real time, which parts I still work around, and the before\/after code so you can judge for yourself. If you’re on the fence about adopting it in a Next.js app, this is the honest accounting I wish I’d had two weeks ago.<\/p>\n
The headline for v5 isn’t a new feature. It’s a cleaner mental model. Earlier versions had you mix imperative helpers like v5 collapses most of that into two primitives that stay out of your way. On the server, There are other wins. Better typed messages. A cleaner Here’s roughly what my endpoint looked like before. I’ve stripped it to the bones, but this is the real shape, not a toy:<\/p>\n That “40 more lines I’m not going to paste” is where all the real pain lived. Partial JSON in the tool arguments. Re-calling the model with the tool result. Mapping OpenAI’s delta format into something the client could render. A small ceremony every time I wanted to add a new tool. It worked. I shipped it. I also swore at it about once a week.<\/p>\n Here’s the same endpoint with v5:<\/p>\n That’s not a selective paste. That’s the whole file. The tool parsing, the re-prompt loop, the streaming format, the client\/server message contract. The SDK owns all of it. I describe the tool and its The reason this is so short isn’t that v5 added a ton of features. It picked sensible defaults. Tools are Zod-typed. Messages are typed. The response format is a known standard that plugs into I wrote recently about how Next.js server actions changed where I put my API boundary<\/a>, and the AI SDK fits neatly alongside that shift. The chat endpoint stays an explicit route the SDK can stream from, and everything else goes in a server action.<\/p>\n The part of my old code that I really wanted to delete was the tool-call parser. In the raw OpenAI stream, tool arguments arrive as a sequence of partial JSON fragments across many SSE chunks. You buffer them, wait for With v5 you define the tool once and you’re done:<\/p>\n No parsing. No re-prompt plumbing. The SDK calls One thing I wish the AI SDK docs<\/a> said louder: the Zod schema you define is the contract. If you’ve been writing vague JSON schemas and hoping the model gets it right, switching to Zod forces you to think about the shape you actually want, and the model responds to tighter schemas much better than to loose ones. That alone was worth the migration.<\/p>\n The client side is where v5 made my React code smaller too. Here’s the chat page, trimmed:<\/p>\n The That sounds fussy until you use it. It’s what lets you show a “Looking up docs\u2026” card while a tool is running, swap it for the result when it returns, and continue streaming the model’s reply below it. No coordination code on my end. I’d been faking that with custom SSE events and ref-based state, and all of that got deleted.<\/p>\n I don’t use the AI SDK for everything. Two cases where I still open Batch jobs that don’t need streaming. If I’m generating 5,000 product descriptions overnight, the raw SDK with a simple concurrency wrapper is cheaper on my attention. No streaming, no tool calls, no UI. The abstractions don’t earn their keep.<\/p>\n Tight token accounting. The SDK gives you The other thing worth knowing: the SDK is provider-agnostic in name but OpenAI-shaped in practice. It works fine with Anthropic, Google, and others via their adapters, but a tool-heavy app assumes the provider supports OpenAI-style function calling<\/a>. If you’re targeting a model that doesn’t, read the adapter docs carefully before you bet your roadmap on it.<\/p>\nstreamText<\/code>, a separate tool-invocation hook, and a useChat<\/code> that quietly did three different jobs depending on how you called it. Fine in small demos. Annoying once you had tool calls, custom state, and a backend that wasn’t a Next.js route.<\/p>\nstreamText<\/code> returns a standard web ReadableStream<\/code> and treats tool calls as first-class. On the client, useChat<\/code> now treats tool invocations as first-class messages instead of a side channel.<\/p>\ngenerateObject<\/code> with Zod schemas. Simpler MCP support if you’re into that. But the thing that actually made me delete code was the tool-call flow. I’ll get to that in a minute. First, the old code.<\/p>\nThe raw OpenAI client way<\/h2>\n
\/\/ \/app\/api\/chat\/route.ts (before)\nimport OpenAI from "openai";\n\nconst client = new OpenAI();\n\nexport async function POST(req: Request) {\n const { messages } = await req.json();\n\n const stream = await client.chat.completions.create({\n model: "gpt-4o-mini",\n messages,\n tools: [searchDocsTool],\n stream: true,\n });\n\n const encoder = new TextEncoder();\n const body = new ReadableStream({\n async start(controller) {\n let toolBuffer = "";\n for await (const chunk of stream) {\n const delta = chunk.choices[0]?.delta;\n if (delta?.content) {\n controller.enqueue(encoder.encode(delta.content));\n }\n if (delta?.tool_calls) {\n toolBuffer += delta.tool_calls[0].function?.arguments ?? "";\n }\n if (chunk.choices[0]?.finish_reason === "tool_calls") {\n const args = JSON.parse(toolBuffer);\n const result = await runSearchDocs(args);\n \/\/ ... re-prompt the model with the result\n \/\/ ... more streaming\n \/\/ ... 40 more lines i'm not going to paste\n }\n }\n controller.close();\n },\n });\n\n return new Response(body, { headers: { "Content-Type": "text\/plain" } });\n}\n<\/code><\/pre>\nThe AI SDK way, side by side<\/h2>\n
\/\/ \/app\/api\/chat\/route.ts (after)\nimport { streamText, tool } from "ai";\nimport { openai } from "@ai-sdk\/openai";\nimport { z } from "zod";\n\nexport async function POST(req: Request) {\n const { messages } = await req.json();\n\n const result = streamText({\n model: openai("gpt-4o-mini"),\n messages,\n tools: {\n searchDocs: tool({\n description: "Search the internal docs",\n parameters: z.object({ query: z.string() }),\n execute: async ({ query }) => runSearchDocs({ query }),\n }),\n },\n });\n\n return result.toDataStreamResponse();\n}\n<\/code><\/pre>\nexecute<\/code> function, and the framework handles the “got tool result, now re-call the model” step I used to hand-code.<\/p>\nuseChat<\/code> on the client. You can still eject if you need to: streamText<\/code> returns a full StreamTextResult<\/code> with textStream<\/code>, toolCalls<\/code>, usage<\/code>, and everything else you might reach for. But you don’t have to hand-roll the streaming protocol to get started.<\/p>\nTool calling stops being a parsing exercise<\/h2>\n
finish_reason === \"tool_calls\"<\/code>, JSON.parse the buffer, catch failures, re-prompt the model with the result, and then continue streaming text back to the user.<\/p>\nimport { z } from "zod";\nimport { tool } from "ai";\n\nexport const searchDocs = tool({\n description: "Search internal docs by natural-language query",\n parameters: z.object({\n query: z.string(),\n limit: z.number().int().min(1).max(20).default(5),\n }),\n execute: async ({ query, limit }) => {\n const hits = await db.search(query, { limit });\n return { hits };\n },\n});\n<\/code><\/pre>\nexecute<\/code>, feeds the return value back to the model, and keeps streaming. If execute<\/code> throws, the error surfaces as a typed tool result instead of a cryptic 500.<\/p>\nStreaming into the UI with useChat<\/h2>\n
\/\/ \/app\/chat\/page.tsx\n"use client";\nimport { useChat } from "ai\/react";\n\nexport default function ChatPage() {\n const { messages, input, handleInputChange, handleSubmit, status } = useChat();\n\n return (\n <form onSubmit={handleSubmit}>\n {messages.map((m) => (\n <div key={m.id} className={m.role}>\n {m.parts.map((p, i) =>\n p.type === "text" ? <span key={i}>{p.text}<\/span>\n : p.type === "tool-invocation" ? <ToolCard key={i} part={p} \/>\n : null\n )}\n <\/div>\n ))}\n <input value={input} onChange={handleInputChange} disabled={status === "streaming"} \/>\n <\/form>\n );\n}\n<\/code><\/pre>\nm.parts<\/code> array is the big shift. A message is now a list of parts, not a single string. Text parts. Tool-invocation parts. Reasoning parts for models that emit them. Step-start and step-end markers. You render what you want and ignore what you don’t.<\/p>\nWhere I still reach for the raw SDK<\/h2>\n
openai<\/code> directly:<\/p>\nusage<\/code> at the end of a stream. If I need per-message billing accounting and I’m doing odd prompt-caching tricks on the vendor side, reading raw completion chunks is easier than fighting the wrapper.<\/p>\n