migrate-ai-sdk-v6-to-v7

AI SDK 6 to 7 Migration

Use

content/docs/08-migration-guides/23-migration-guide-7-0.mdx

from the AI SDK repo as the source of truth. This skill is the working checklist; read the guide for exact examples or when behavior is unclear.

Migration Workflow

Ensure the user has a clean backup or committed baseline before editing.
Inspect
```
package.json
```
and lockfiles to identify installed
```
ai
```
,
```
@ai-sdk/*
```
, provider, UI, MCP, and telemetry packages.
Upgrade AI SDK packages to latest versions, and add
```
@ai-sdk/otel
```
only if the project uses OpenTelemetry spans.
Update runtime and module assumptions: Node.js must be
```
>=22
```
, and AI SDK packages are ESM-only. Replace
```
require()
```
imports with ESM imports and add
```
"type": "module"
```
or use
```
.mjs
```
where needed.
Search for the v6 patterns below, migrate only the code that exists, then run typecheck and targeted tests.

Prefer behavior-preserving changes. When v7 changes semantics, decide whether the app wants the new all-steps behavior or the previous final-step-only behavior.

Core API Changes

experimental_customProvider

customProvider

experimental_generateImage

generateImage

;

Experimental_GenerateImageResult

GenerateImageResult

experimental_transcribe

transcribe

;

Experimental_TranscriptionResult

TranscriptionResult

experimental_generateSpeech

generateSpeech

;

Experimental_SpeechResult

SpeechResult

```
experimental_output
```
option/result ->
```
output
```
option/result.

CallSettings

LanguageModelCallOptions & Omit<RequestOptions, 'timeout'>

;

prepareCallSettings

prepareLanguageModelCallOptions

```
stepCountIs
```
->
```
isStepCount
```
.

Prompts and Steps

Rename top-level

system

instructions

for

generateText

streamText

generateObject

streamObject

, and

streamUI

Move
```
{ role: 'system' }
```
messages from
```
prompt
```
or
```
messages
```
into top-level
```
instructions
```
. Only use
```
allowSystemInMessages: true
```
for trusted persisted messages.
Rename
```
experimental_prepareStep
```
to
```
prepareStep
```
.
In
```
prepareStep
```
, rename returned
```
system
```
to
```
instructions
```
.

experimental_repairToolCall

, use

{ instructions }

instead of

{ system }

Audit
```
prepareStep
```
behavior: returned
```
instructions
```
and
```
messages
```
now carry forward into later steps. If code depended on one-step-only overrides, rebuild from
```
initialInstructions
```
,
```
initialMessages
```
, and
```
responseMessages
```
explicitly.

Lifecycle Callbacks

```
experimental_onStart
```
->
```
onStart
```
.
```
experimental_onStepStart
```
->
```
onStepStart
```
.
```
onFinish
```
->
```
onEnd
```
.
```
onStepFinish
```
->
```
onStepEnd
```
.

For

embed

embedMany

, and

rerank

experimental_onFinish

onEnd

Callback event fields use
```
instructions
```
instead of
```
system
```
.

Usage, Telemetry, and Include Options

usage.cachedInputTokens

usage.inputTokenDetails.cacheReadTokens

usage.reasoningTokens

usage.outputTokenDetails.reasoningTokens

OpenTelemetry moved out of
```
ai
```
; install
```
@ai-sdk/otel
```
and call
```
registerTelemetry(new OpenTelemetry(...))
```
at app startup.
Telemetry is enabled by default once an integration is registered. Remove redundant
```
isEnabled: true
```
; use
```
isEnabled: false
```
to opt out per call.

Move

experimental_telemetry.tracer

into the

OpenTelemetry

constructor.

```
experimental_telemetry
```
->
```
telemetry
```
.
Telemetry integration callbacks:
```
onRerankFinish
```
->
```
onRerankEnd
```
,
```
onEmbedFinish
```
->
```
onEmbedEnd
```
. Update tracing-channel subscribers for the same event type names.
```
experimental_include
```
->
```
include
```
.
```
includeRawChunks
```
->
```
include.rawChunks
```
.
Request and response bodies are excluded by default. If code reads
```
request.body
```
or
```
response.body
```
, opt in with
```
include.requestBody
```
and, for
```
generateText
```
,
```
include.responseBody
```
.

Streaming, Messages, and Tools

```
StreamTextResult.fullStream
```
->
```
stream
```
.
```
streamText
```
```
onChunk
```
now receives all stream parts, including lifecycle, boundary, finish, abort, and error parts. Guard by
```
chunk.type
```
before assuming text/tool/raw content.
```
step.response.messages
```
is no longer accumulated across previous steps. Use
```
result.responseMessages
```
for the full response message history, or flatten
```
result.steps
```
.

Tool execution callbacks:

experimental_onToolCallStart

onToolExecutionStart

experimental_onToolCallFinish

onToolExecutionEnd

Tool callback
```
experimental_context
```
->
```
context
```
.
Split shared runtime data from tool-specific data: use top-level
```
runtimeContext
```
for orchestration state, declare per-tool
```
contextSchema
```
, and pass per-tool values through
```
toolsContext
```
.

Move

needsApproval

from

tool()

dynamicTool()

into per-call or agent

toolApproval

```
experimental_activeTools
```
->
```
activeTools
```
.
```
ToolCallOptions
```
->
```
ToolExecutionOptions
```
.
```
isToolOrDynamicToolUIPart
```
->
```
isToolUIPart
```
.

Content Parts and Reasoning

Tool result
```
{ type: 'media' }
```
is removed; use
```
{ type: 'file-data' }
```
.

Migrate

toModelOutput

image-*

file-*

file-id

, and

image-file-id

variants to canonical

{ type: 'file', mediaType, data: { type: 'data' | 'url' | 'reference', ... } }

User message

{ type: 'image', image, mediaType? }

is deprecated; use

{ type: 'file', mediaType: 'image' | 'image/*', data }

Add support for the new
```
reasoning-file
```
content type in exhaustive switches, renderers, serializers, and validators.
When adopting top-level
```
reasoning
```
, remove overlapping provider-specific reasoning settings from
```
providerOptions
```
unless provider-specific settings intentionally take precedence.

Multi-Step Result Shape

```
result.usage
```
now includes all steps;
```
result.totalUsage
```
is deprecated. Use
```
result.finalStep.usage
```
for final-step-only usage.

Top-level

content

toolCalls

staticToolCalls

dynamicToolCalls

toolResults

staticToolResults

dynamicToolResults

files

sources

, and

warnings

now include all steps. Use

finalStep

for previous final-step-only behavior.

Top-level

reasoning

reasoningText

request

response

, and

providerMetadata

are deprecated for final-step data. Use

result.finalStep.*

; for

streamText

, await

result.finalStep

Apply the same result-shape rules to
```
onEnd
```
events.

Stream Response Helpers

The

streamText

result helper methods are deprecated. Replace result methods with top-level stateless helpers:

result.toUIMessageStream(...)

toUIMessageStream({ stream: result.stream, ... })

result.toUIMessageStreamResponse(...)

toUIMessageStream(...)

plus

createUIMessageStreamResponse({ stream })

result.pipeUIMessageStreamToResponse(response, ...)

toUIMessageStream(...)

plus

pipeUIMessageStreamToResponse({ response, stream })

result.toTextStreamResponse()

toTextStream({ stream: result.stream })

plus

createTextStreamResponse({ stream })

result.pipeTextStreamToResponse(response)

toTextStream({ stream: result.stream })

plus

pipeTextStreamToResponse({ response, stream })

Package-Specific Checks

MCP:
```
MCPTransportConfig.redirect
```
now defaults to
```
'error'
```
. Only set
```
redirect: 'follow'
```
for trusted MCP servers that rely on redirects.
Vue:
```
@ai-sdk/vue
```
```
Chat
```
class is deprecated. Prefer
```
useChat
```
, including getter/ref init for reactive chat inputs.

Anthropic and

@ai-sdk/google-vertex/anthropic

providerMetadata.anthropic.cacheCreationInputTokens

was removed. Use

usage.inputTokenDetails.cacheWriteTokens

; raw Anthropic usage remains at

finalStep.providerMetadata?.anthropic?.usage

Google: rename
```
GoogleGenerativeAI*
```
types, classes, and functions to
```
Google*
```
, e.g.
```
createGoogleGenerativeAI
```
->
```
createGoogle
```
. The
```
google
```
entry point is unchanged.

Validation

Run the project typecheck after edits, then the smallest relevant test suite. Also smoke-test streaming, chat UI, tool execution, telemetry, and multi-step flows if the migration touched them. If type errors remain, search the migration guide for the exact removed or renamed symbol before inventing a workaround.

migrate-ai-sdk-v6-to-v7

NPX Install

Tags

SKILL.md Content

AI SDK 6 to 7 Migration

Migration Workflow

Core API Changes

Prompts and Steps

Lifecycle Callbacks

Usage, Telemetry, and Include Options

Streaming, Messages, and Tools

Content Parts and Reasoning

Multi-Step Result Shape

Stream Response Helpers

Package-Specific Checks

Validation