Vercel AI Sdk Knowledge Patch

Vercel AI SDK Knowledge Patch

Use this skill when implementing or reviewing TypeScript applications built with the ai package, AI SDK UI, provider packages, agents, workflows, or @ai-sdk/mcp. Start with the breaking-change notes, then load the topic reference that matches the work. Preserve provider-specific options when a top-level abstraction does not expose the required capability.

Reference index

Breaking changes first

Runtime and modules

When targeting the v7 API line:

• Require Node.js 22 or newer.
• Use ESM imports; CommonJS require() is unsupported.
• Upgrade ai and every provider package together.
• Run npx @ai-sdk/codemod v7, then review semantic changes manually.

The earlier 4.0 migration also removed deprecated APIs. Its codemods cover much of the mechanical work, but they do not eliminate the need to follow the migration guide.

Renamed APIs

For v7-targeted code, use the current names:

System messages placed directly in prompt or messages require allowSystemInMessages: true. Tool-level needsApproval, result-instance response methods, and Vue's Chat class are deprecated; prefer call-level toolApproval, top-level response helpers, and useChat.

repairToolCall and repairText are the stable repair options. Their experimental_ aliases remain only for compatibility.

Multi-step result scope

Top-level multi-step results accumulate content, tool calls and results, files, sources, warnings, and usage across the whole run. Use finalStep when only the last step is relevant. Request and response bodies are no longer retained unless explicitly requested.

const totalUsage = await result.usage;
const finalStep = await result.finalStep;
console.log(totalUsage, finalStep.usage);

Agent control quick reference

Stop conditions

ToolLoopAgent defaults to isStepCount(20). stopWhen is evaluated after a step that produced tool results; arrays use OR semantics. A loop also stops on a normal finish without tool calls, a tool without execute, or an approval-required call. Use isLoopFinished() only when natural completion is safe without a step cap.

const agent = new ToolLoopAgent({
  model,
  tools,
  stopWhen: [isStepCount(50), hasToolCall('publish')],
});

Reconfigure each step

prepareStep receives the current model, zero-based stepNumber, prior steps, outgoing messages, and runtime context. It can replace the model or messages, restrict activeTools or toolChoice, and override model-call settings. Return {} to keep constructor settings.

For explicit completion, combine toolChoice: 'required' with a terminal tool that has no execute. The terminal payload remains available through staticToolCalls.

Typed outputs and UI

Declare output: Output.object(...) on the agent for a validated, inferred generate().output. Derive persisted and rendered chat types with InferAgentUIMessage<typeof agent>, and serve them with createAgentUIStreamResponse.

Constructor-level and call-level lifecycle callbacks compose. If both define the same callback, the constructor callback runs first; the call callback does not replace it.

Context boundaries

Use runtimeContext for typed orchestration state shared across step preparation, approvals, callbacks, telemetry, and agents. Use a tool's contextSchema plus toolsContext for private, tool-scoped configuration; only that tool receives its validated context.

Approvals are return and replay

An approval request ends the current generation. Preserve result.response.messages, append matching tool-approval-response parts in a tool message, and invoke the model again. Call-level toolApproval can require a user decision, decide automatically, or use a typed policy. Use signed approvals and revalidate input and policy when replay crosses a trust boundary.

Tool execution quick reference

• execute(input, context) can read toolCallId, conversation messages, and the request abortSignal.
• dynamicTool keeps static inference for known tools while exposing dynamic: true for runtime-defined calls that need validation or casting.
• An async-generator execute streams preliminary values; its last value is the final tool result.
• onInputStart, onInputDelta, and onInputAvailable observe argument construction. onInputStart precedes onInputAvailable in both streaming and non-streaming calls; deltas remain streaming-only.
• Media returned by execute does not automatically reach the model. Implement toModelOutput, preferably with inline media bytes where provider URL support is uncertain.
• Use repairToolCall to replace malformed calls or return null to decline repair. Distinguish NoSuchToolError, InvalidToolArgumentsError, ToolExecutionError, and ToolCallRepairError.

Generation and agents accept total, step, first-content, idle-chunk, default-tool, and per-tool timeouts where applicable. Timeout aborts surface as TimeoutError. A supplied SandboxSession reaches tools as experimental_sandbox and supports working directories, environment values, streaming output, and abort signals.

Use WorkflowAgent when execution must survive restarts, deployments, interruptions, or delayed approvals. Use HarnessAgent to expose an external agent runtime through the standard Agent interface, including resumable sessions and interrupted turns.

Streaming and structured output quick reference

streamText starts immediately but progresses under consumer backpressure: always consume a returned stream. Streaming generation failures arrive through onError or an in-band error part; tool failures become tool-error parts. Non-streaming schema and generation failures still throw.

Await response-piping helpers so stream read and write failures propagate. Stream transcription result promises consume the single underlying stream; access fullStream first when both incremental parts and final values are needed.

Stream transforms run in order before callbacks and result promises. A transform that calls stopStream must emit synthetic finish-step and finish events so downstream consumers complete. Exceptions in experimental lifecycle observer hooks are swallowed and do not fail generation.

For structured output:

• Agents can own an Output.object schema directly.
• Text generation can combine tools with a final validated output in a multi-step run.
• NoObjectGeneratedError retains raw text, response metadata, usage, and cause.
• Array mode preserves transforms, coercions, defaults, and pipes.
• JSON extraction and repair can recover malformed structured output and tool calls.

UI and transport quick reference

useChat supports client-to-server chat IDs, server-assigned response message IDs, and appendResponseMessages for persistence. createDataStreamResponse can emit custom data and message annotations before or alongside generation; merge a streamText result with mergeIntoDataStream.

DirectChatTransport connects useChat directly to an Agent without a separate route transport. UI flows can submit approval responses automatically, use async sendAutomaticallyWhen conditions, and preserve provider metadata across streams and turns. Experimental realtime hooks normalize browser WebSocket sessions, ephemeral tokens, audio transcription, client tools, and UIMessage[] state.

MCP quick reference

Create MCP clients from @ai-sdk/mcp. Prefer HTTP for deployments and stdio only for local servers. Keep the client open through generation and close it afterward. The lightweight adapter does not provide session management, resumable streams, or notification reception.

Passing schemas to client.tools() limits discovery to named tools and adds typed inputs. An outputSchema validates structuredContent, falls back to JSON parsed from text, and throws when neither yields a valid value. Without one, execution returns the raw CallToolResult.

Treat resources as application-selected context and prompts as user-selected server templates. Elicitation requires both an advertised capability and a registered handler that returns accept, decline, or cancel.

Before exposing remotely described tools, persist a trusted fingerprintTools snapshot and compare later definitions with detectToolDrift. The application owns snapshot storage and the policy for detected drift.

Media and provider quick reference

• Compatible providers accept PDF bytes as a file message part with mimeType: 'application/pdf'.
• uploadFile and uploadSkill create reusable provider references instead of resending bytes or skill files.
• generateSpeech, transcribe, SpeechResult, and TranscriptionResult are stable APIs; streaming speech translation remains experimental.
• Canonical file parts may contain inline data, URLs, provider references, or text-backed content; use GeneratedFile rather than Experimental_GeneratedImage.
• Experimental video generation supports aborts, bounded downloads, polling, webhooks, adaptive aspect ratio, and image or video reference inputs.
• Top-level reasoning provides portable reasoning effort while providerOptions remains available for provider-specific controls.

Register one global telemetry integration with registerTelemetry. OpenTelemetry lives in @ai-sdk/otel. Runtime and tool context is excluded unless explicitly selected; include only fields safe to export. Use onStart, onStepEnd, and onEnd for portable lifecycle handling, or subscribe instrumentation to the Node.js ai:telemetry tracing channel for structured events.

Implementation checklist

1. Confirm the target API line before choosing renamed or experimental symbols.
2. Bound every agent loop and long-running tool with stop rules, timeouts, and aborts.
3. Consume streams, await response piping, and handle in-band error parts.
4. Persist complete response messages before replaying approvals.
5. Validate runtime-defined tools, MCP outputs, and remotely supplied definitions.
6. Keep secrets in tool-scoped context and opt telemetry fields in deliberately.
7. Use durable workflows for operations that must survive process boundaries.