Vercel AI SDK 6 Deep Dive: Features + Tool Calls 2026

Vercel AI SDK 6 is the de facto standard for shipping AI features on Next.js and the broader React ecosystem — yet most teams adopt roughly thirty percent of its surface area, leave the rest unused, and reach for third-party libraries to fill gaps the SDK already covers. This deep dive walks the full feature set so the next decision you make is informed by what exists, not what you remember from the quickstart.

The reason this matters in mid-2026: the cost of choosing wrong inside the AI stack compounds quickly. Provider lock-in, ad-hoc streaming protocols, hand-rolled tool-call shapes, custom agent loops — each of these is a maintenance liability that the SDK has quietly solved over its 6.x line. Teams that adopt the full surface area ship faster and pay less in technical debt twelve months later.

What this guide covers: the useChat message-parts model and its optimistic-UI behavior; streamText as the right server primitive and how it routes reasoning effort; tool calls with Zod input schemas and the full run-call lifecycle; the provider-adapter pattern across Anthropic, OpenAI, Google, Mistral, and xAI; multi-modal generation (image, audio, video); the new agent-loop primitive that closes the framework gap; and a measured comparison against LangChain on performance and cost.

Adoption of the Vercel AI SDK has crossed the line from "interesting option" to "default expectation" over the last two release cycles. Every major Next.js starter template now ships with it pre-wired; the React ecosystem's chat and agent tutorials assume it; downstream agentic frameworks (Mastra, Inngest's agent kit, even LangChain's TypeScript port) integrate against it rather than competing with it. The 6.x line consolidated the patterns that 4.x and 5.x experimented with — message-parts, provider adapters, the tool-call lifecycle — into a stable surface that production teams can rely on.

And yet the typical adoption pattern is shallow. Most teams ship with useChat on the client and streamText on the server, call it done, and then reach for bespoke libraries the moment they need a tool, multi-modal generation, or an autonomous loop. That pattern costs twice — first in the integration of the second library, then again when the SDK's own implementation of the same feature catches up and the team has to re-platform mid-project. The cure is a structured tour of the full surface area.

The deep-dive structure below moves bottom-up: the message-parts model first because it underpins every other client-side feature; then the server primitive that produces those parts; then tools and the provider abstraction; then the newer multi-modal and agent-loop surface areas. Each section is dense by design — the goal is a reference you keep open in a tab during real implementation work, not a tutorial you skim once.

useChat is the React hook that owns the entire client-side chat surface. It wires streaming reassembly, optimistic user-message insertion, abort signals on re-submission, stable message IDs for React reconciliation, status state machine, and tool-call part rendering. The shape it exposes is small enough to memorize and stable enough to depend on.

The message-parts model

The single most important concept in AI SDK 6 is that every message — user and assistant — is an array of parts rather than a single content string. A typical assistant turn now contains text fragments, tool-call requests, tool-call results, and reasoning traces, interleaved in the order the model emitted them. Rendering a message means iterating the parts array and dispatching on part.type. Collapsing this to a string loses tool-call UX, breaks reasoning display, and invalidates the entire upgrade path to agentic interfaces.

The hook also exposes status, which is the four-state machine that drives perceived quality. ready means idle and accepting input. submitted means the user's message is sent but the model has not yet produced a first token. streaming means tokens are arriving — disable the input, show a pulsing cursor, and prepare for tool-call parts to interleave with text. error means the route returned non-200 or the stream broke — surface a toast and offer regenerate(). Most quality regressions on chatbots ship from a render loop that ignores status.

Optimistic UI for free

The hook inserts the user's message into the messages array on sendMessage call, before the network round trip resolves. This is what eliminates the "did my message send?" perception gap that naive fetch-and-render chat implementations always have. The optimistic insert is rolled back automatically if the request fails. Build on this — never manage your own optimistic insertion logic alongside the hook.

Initial-history hydration is the one place you may legitimately interact with the underlying state. Pass initialMessages to useChat on mount with historical conversation rows from your database, and the hook treats them as already-completed turns. setMessages is exposed for advanced cases like server-side persistence with optimistic ID reconciliation, but reach for it sparingly.

One implementation discipline worth internalizing: the messages array returned by useChat is owned by the hook; treat it as read-only inside render. Mutations during render produce stale UI and break streaming reassembly. Use regenerate() for retries, stop() for cancellation, setMessages only for edit-and-resubmit flows or hydration, and sendMessage for new user turns. The discipline pays back the moment you add tool calls in Section 04.

streamText is the server-side counterpart to useChat and the right primitive for any user-facing AI surface. It accepts a model object, an array of messages, an optional system prompt, tools, stop conditions, and provider- specific options; it returns a streaming response object with methods to turn the stream into a UI-Message Server-Sent-Events response, a plain text stream, or a JSON-RPC stream. The default shape — result.toUIMessageStreamResponse() — pairs with useChat on the client and requires no manual stream parsing.

Reasoning effort routing

AI SDK 6 added first-class support for routing reasoning effort across providers that expose it. Pass providerOptions with the provider-specific reasoning controls and the SDK normalizes the runtime behavior. Anthropic uses thinking with a token budget; OpenAI's reasoning models use reasoning.effort as a low / medium / high enum; Google exposes a thinkingBudget with a token cap. The SDK does not unify these into a single abstraction — each provider's surface is too different — but it gives you a single place to set them.

The response-stream shape itself is where the SDK earns its keep. toUIMessageStreamResponse() returns an SSE stream in the protocol that useChat consumes natively — text chunks, tool-call requests, tool-call results, and reasoning fragments all flow in the same stream with discriminated event types. No manual chunk parsing, no per-provider decoder, no wrestling with stream-parsing edge cases on connection close.

Lifecycle hooks

streamText exposes lifecycle callbacks that are the right place to put observability and per-turn business logic. onChunk fires for every incoming token or part — useful for token-level metrics if you need them, expensive if you don't. onStepFinish fires once per tool-call step in multi-step runs — useful for logging tool invocations. The highest-value hook is onFinish, which fires once at stream completion with the full usage breakdown — input tokens, output tokens, reasoning tokens, total cost estimate, finish reason. Pipe onFinish data to your observability layer and most production debugging questions resolve themselves.

For non-streaming workloads — a background summarization job, a batch reranker, a tool that needs a structured response with no user visibility — reach for generateText or generateObject instead. They share the same provider adapter and message shape but return a single result rather than a stream. The split is real and consequential: stream for user-facing surfaces, generate for backend pipelines.

Tools are where AI SDK 6's design choices pay off most visibly. Every tool is defined with a name, a description for the model, a Zod input schema, and an execute function. The SDK handles routing the model's structured tool-call output to your function, validating the arguments against the schema, awaiting the result, serializing it back into the stream as a part, and looping if the model wants to invoke another tool.

The four tool-call patterns

The grid below maps the four canonical tool-call shapes you will actually ship. Most production chatbots use all four. The differences come down to where state lives (client vs server), whether the user must approve the invocation, and how long the execution can take.

The run-call lifecycle

Each tool invocation passes through a four-stage lifecycle that the SDK exposes via discriminated message parts. Stage one — the model emits a tool-call part with the tool name, arguments, and a stable toolCallId. The SDK validates the arguments against your Zod schema; on validation failure, the call is aborted with a typed error and the model is re-prompted. Stage two — the SDK invokes your execute function with the validated arguments. Stage three — your function returns a value (or throws), which the SDK serializes into a tool-result part, paired to the original call by toolCallId. Stage four — the model receives the result and either emits a final text response or another tool call, looping until a stop condition fires.

Error discrimination

Production tool calls fail in four distinct ways and the SDK surfaces each as a different error type. NoSuchToolError — the model hallucinated a tool name that does not exist; usually means the system prompt under-specified the available tools. InvalidToolInputError — the model's structured output failed Zod validation; usually means the schema description is ambiguous or the model is too small for the task. A thrown error from your execute function — surfaced as a tool-result with an error field, which the model can read and decide how to recover from. ToolExecutionError — wraps the underlying throw with tool-call context (name, args, callId) for logging. Switch on the error type rather than catching everything as a generic Error; production reliability depends on the discrimination.

One ergonomics rule that compounds across a tool catalog: write the description for the model, not for human reviewers. The model uses the description to decide when to invoke each tool, so phrase it as a trigger condition rather than a mechanism — "Search the public web for current information when the question cannot be answered from training data alone" rather than "Calls the Bing Search API." The difference in tool-call accuracy is measurable and shows up immediately in production evals. Keep argument names descriptive (searchQuery not q), keep required arguments minimal, and avoid optional freeform fields that the model can fill with anything.

The provider-adapter pattern is the AI SDK's quietest superpower and the single architectural decision that most determines a product's long-term flexibility. Every provider package exports a factory 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, no per-provider error taxonomy.

The five-plus mainstream providers covered by first-party packages today: Anthropic, OpenAI, Google, Mistral, and xAI. Community- maintained adapters cover Cohere, Groq, Fireworks, Together, OpenRouter, Bedrock, Vertex, and Azure OpenAI. Any OpenAI-compatible endpoint can be wired in via the createOpenAICompatible factory, which covers most inference-on-demand providers without a dedicated package.

The pattern in practice is a thin getModel() helper that reads an environment variable and returns the appropriate model factory. Cache the result on first call. Drive per-environment defaults from vercel.json environment settings or your platform equivalent; drive per-request routing from a small policy layer inside the route handler — "default to Sonnet, route code questions to GPT-5.5, route long-document Q&A to Gemini." The Vercel AI Gateway is a managed alternative that implements the same pattern with built-in caching, retries, and observability; it scales with usage and is worth evaluating once traffic justifies the cost.

One feature worth using deliberately: provider-specific options via providerOptions. The SDK exposes a typed object per provider that surfaces vendor-specific knobs — Anthropic prompt caching, OpenAI's reasoning effort, Google's safety settings — without polluting the cross-provider interface. Set these at the call site rather than wrapping them in a custom abstraction; the SDK already maintains the abstraction for you.

AI SDK 6 added first-class generation primitives for images, audio (speech and transcription), and an experimental video primitive — alongside the existing input-side support for vision and audio on chat models. The same provider-adapter pattern applies: each media type has a dedicated SDK function (generateImage, generateSpeech, transcribe, experimental generateVideo) and each compatible provider exports a factory that conforms to that function's interface.

Input vs output multi-modal

Two distinct surface areas matter here. Input-side multi-modal — sending images, audio, or video to a chat model as part of a user message — is supported via image, audio, and file parts on the UIMessage shape. All major chat providers accept images today; audio input is supported by GPT-5.5 and Gemini natively; video input is supported only by Gemini at production quality. Output-side generation is handled by dedicated functions, not by streamText — do not try to make a chat model generate images by asking nicely.

The image-generation surface is the most production-ready: pass a prompt, optional size and quality parameters, and an optional set of input images for reference. Returns base64-encoded image data or a stored URL depending on the provider. The function call is synchronous from the SDK's perspective — generation itself takes 5–30 seconds, so wire it through your long-running tool pattern from Section 04 if you call it inside a chat agent. For stand-alone generation flows (a "create image" button in a UI), call generateImage directly from a route handler with a longer maxDuration.

Speech and transcription are the next most-used surfaces. generateSpeech turns text into an audio buffer using the configured voice; pair with a streaming endpoint to play the audio progressively as it generates. transcribe accepts an audio buffer and returns text plus optional word-level timestamps. Both are useful for accessibility (read-aloud, voice-input chat) and for content workflows (podcast transcription, video voiceover). The provider matrix is wide — OpenAI, ElevenLabs, Deepgram, AssemblyAI, Groq, and Google all ship adapters.

The agent-loop primitive is the headline feature of the AI SDK 6 line and the one that closes the most important historical gap against LangChain-style frameworks. Before 6.x, building an autonomous agent on top of the SDK meant hand-rolling the multi-step loop — prompt the model, parse tool calls, execute, re-prompt with results, check a stop condition, repeat. The new primitive does this for you with typed stop conditions, step tracking, and clean cancellation semantics.

Stop conditions, not max-steps

The mental model that the SDK encourages is "the agent runs until a stop condition fires," not "the agent runs for at most N steps." Stop conditions are composable: stepCountIs(10) caps total rounds, hasToolCall('finalize') stops the moment a sentinel tool is invoked, tokenUsageExceeds(5000) stops on cost, and you can write custom predicates that inspect the running message array. Compose multiple stop conditions with stopWhen: [...] and the loop terminates on the first match.

Step tracking and observability are the second half of the primitive. Each step is surfaced via the onStepFinish callback with the full set of parts emitted that step, the tool calls made, the tool results received, and the usage stats. Stream this to your observability layer and you get a per-step audit trail of agent behavior — essential for debugging the long tail of "why did the agent do that?" questions.

Where the agent loop replaces LangChain

The strongest historical reason teams layered LangChain on top of the AI SDK was the agent abstraction — LangChain's AgentExecutor and the various agent types it shipped with. The SDK's agent loop now covers the same surface area for most use cases: multi-step tool sequencing, stop conditions, structured intermediate results, and step-level observability. What LangChain still offers on top is the orchestration ecosystem — chains, retrievers, memory abstractions, the broader LangSmith tracing platform — which matters for some workloads and is overkill for most chatbots and product agents.

The most common architectural question in mid-2026 is "AI SDK or LangChain?" — and the honest answer is "depends on the workload, and most teams need both for different things." That said, measurable deltas exist on the workloads where they overlap, and the deltas favor the AI SDK on most production chat and agent surfaces.

Performance

On equivalent streaming chat workloads with the same provider and model, AI SDK 6 is roughly 15–25 percent faster end-to-end than LangChain TypeScript on cold-start route invocations and roughly 5–10 percent faster on warm requests. The delta comes from the SDK's smaller client and server surface — fewer abstractions on the path between the request body and the streaming response, less object allocation per token, and a streaming protocol that doesn't re-serialize across internal layers. The numbers narrow on longer requests where provider latency dominates, and widen on short, high-frequency calls.

Cost

Provider cost is identical — both libraries call the same endpoints with the same tokens. Where cost actually diverges is infrastructure: AI SDK routes run faster, so per-request compute time on Vercel Functions is lower, which compounds at scale into a 10–20 percent monthly platform-cost reduction at the same request volume. The smaller client bundle (~25 KB gzipped for @ai-sdk/react vs ~80 KB for the equivalent LangChain React bindings) also reduces edge-network egress and improves initial page load on chat-heavy products.

When each wins

Use the AI SDK as the default for chatbots, in-product AI features, streaming agent interfaces, and any workload where client-side React rendering is the surface. Use LangChain (or its TypeScript siblings — Mastra, Inngest's agent kit) when you need heavy orchestration on the backend: parallel tool execution graphs, complex memory abstractions across sessions, retrieval pipelines with multiple rerankers, or the LangSmith tracing platform specifically. Many production builds use both — LangChain in a server-side orchestration service that produces results, AI SDK in the user-facing chat layer that streams them.

For teams sizing this decision, our LangChain 1 deep dive covers the orchestration side of the picture in symmetric detail, and our Next.js 16 AI chatbot tutorial ships a production-shaped chat surface end-to-end on the AI SDK. For larger transformation work — picking a default AI stack across multiple products and teams — that's exactly the kind of comparative eval our AI transformation engagements start with.