Migrer de AI SDK v6 à v7 sans erreurs de build

Migration AI SDK 6 vers 7

Utilisez content/docs/08-migration-guides/23-migration-guide-7-0.mdx du repo AI SDK comme source de vérité. Cette skill est la checklist de travail ; consultez le guide pour les exemples exacts ou quand le comportement n'est pas clair.

Workflow de migration

Assurez-vous que l'utilisateur dispose d'une sauvegarde propre ou d'une baseline commitée avant les modifications.
Inspectez package.json et les fichiers de lock pour identifier les packages ai, @ai-sdk/*, provider, UI, MCP et telemetry installés.
Mettez à jour les packages AI SDK vers les dernières versions, et ajoutez @ai-sdk/otel uniquement si le projet utilise des spans OpenTelemetry.
Mettez à jour les hypothèses de runtime et de module : Node.js doit être >=22, et les packages AI SDK sont ESM uniquement. Remplacez les imports require() par des imports ESM et ajoutez "type": "module" ou utilisez .mjs si nécessaire.
Recherchez les patterns v6 ci-dessous, migrez uniquement le code qui existe, puis exécutez le typecheck et les tests ciblés.

Privilégiez les changements qui préservent le comportement. Quand v7 change la sémantique, décidez si l'app veut le nouveau comportement all-steps ou le comportement précédent final-step-only.

Changements Core API

experimental_customProvider -> customProvider.
experimental_generateImage -> generateImage ; Experimental_GenerateImageResult -> GenerateImageResult.
experimental_transcribe -> transcribe ; Experimental_TranscriptionResult -> TranscriptionResult.
experimental_generateSpeech -> generateSpeech ; Experimental_SpeechResult -> SpeechResult.
option/résultat experimental_output -> option/résultat output.
CallSettings -> LanguageModelCallOptions & Omit<RequestOptions, 'timeout'> ; prepareCallSettings -> prepareLanguageModelCallOptions.
stepCountIs -> isStepCount.

Prompts et steps

Renommez system de haut niveau en instructions pour generateText, streamText, generateObject, streamObject, et streamUI.
Déplacez les messages { role: 'system' } de prompt ou messages vers instructions de haut niveau. Utilisez uniquement allowSystemInMessages: true pour les messages persistants de confiance.
Renommez experimental_prepareStep en prepareStep.
Dans prepareStep, renommez le system retourné en instructions.
Dans experimental_repairToolCall, utilisez { instructions } au lieu de { system }.
Auditez le comportement de prepareStep : les instructions et messages retournés se propagent maintenant dans les steps suivantes. Si le code dépendait de overrides single-step uniquement, reconstruisez à partir de initialInstructions, initialMessages, et responseMessages explicitement.

Callbacks de lifecycle

experimental_onStart -> onStart.
experimental_onStepStart -> onStepStart.
onFinish -> onEnd.
onStepFinish -> onStepEnd.
Pour embed, embedMany, et rerank, experimental_onFinish -> onEnd.
Les champs d'événement callback utilisent instructions au lieu de system.

Usage, telemetry, et options Include

usage.cachedInputTokens -> usage.inputTokenDetails.cacheReadTokens.
usage.reasoningTokens -> usage.outputTokenDetails.reasoningTokens.
OpenTelemetry est sorti de ai ; installez @ai-sdk/otel et appelez registerTelemetry(new OpenTelemetry(...)) au démarrage de l'app.
La telemetry est activée par défaut une fois qu'une intégration est enregistrée. Supprimez le isEnabled: true redondant ; utilisez isEnabled: false pour refuser par appel.
Déplacez experimental_telemetry.tracer dans le constructeur OpenTelemetry.
experimental_telemetry -> telemetry.
Callbacks d'intégration telemetry : onRerankFinish -> onRerankEnd, onEmbedFinish -> onEmbedEnd. Mettez à jour les subscribers tracing-channel pour les mêmes noms de type d'événement.
experimental_include -> include.
includeRawChunks -> include.rawChunks.
Les corps de requête et réponse sont exclus par défaut. Si le code lit request.body ou response.body, opt-in avec include.requestBody et, pour generateText, include.responseBody.

Streaming, messages, et tools

StreamTextResult.fullStream -> stream.
streamText onChunk reçoit maintenant toutes les parties de stream, y compris les parties lifecycle, boundary, finish, abort, et error. Gardez chunk.type en vue avant d'assumer du contenu text/tool/raw.
step.response.messages n'est plus accumulé à travers les steps précédentes. Utilisez result.responseMessages pour l'historique complet des messages de réponse, ou aplatissez result.steps.
Callbacks d'exécution tool : experimental_onToolCallStart -> onToolExecutionStart, experimental_onToolCallFinish -> onToolExecutionEnd.
Callback tool experimental_context -> context.
Séparez les données runtime partagées des données spécifiques au tool : utilisez runtimeContext de haut niveau pour l'état d'orchestration, déclarez contextSchema par tool, et passez les valeurs par tool via toolsContext.
Déplacez needsApproval de tool() / dynamicTool() vers toolApproval par appel ou agent.
experimental_activeTools -> activeTools.
ToolCallOptions -> ToolExecutionOptions.
isToolOrDynamicToolUIPart -> isToolUIPart.

Content parts et reasoning

Le résultat tool { type: 'media' } est supprimé ; utilisez { type: 'file-data' }.
Migrez les variants toModelOutput image-*, file-*, file-id, et image-file-id vers la forme canonique { type: 'file', mediaType, data: { type: 'data' | 'url' | 'reference', ... } }.
Le message utilisateur { type: 'image', image, mediaType? } est déprécié ; utilisez { type: 'file', mediaType: 'image' | 'image/*', data }.
Ajoutez le support du nouveau type de contenu reasoning-file dans les exhaustive switches, renderers, serializers, et validators.
En adoptant reasoning de haut niveau, supprimez les paramètres reasoning spécifiques au provider qui se chevauchent de providerOptions à moins que les paramètres provider-specific ne prennent intentionnellement la priorité.

Forme de résultat multi-step

result.usage inclut maintenant tous les steps ; result.totalUsage est déprécié. Utilisez result.finalStep.usage pour l'usage final-step uniquement.
content, toolCalls, staticToolCalls, dynamicToolCalls, toolResults, staticToolResults, dynamicToolResults, files, sources, et warnings de haut niveau incluent maintenant tous les steps. Utilisez finalStep pour le comportement final-step-only précédent.
reasoning, reasoningText, request, response, et providerMetadata de haut niveau sont dépréciés pour les données final-step. Utilisez result.finalStep.* ; pour streamText, attendez result.finalStep.
Appliquez les mêmes règles de forme de résultat aux événements onEnd.

Stream Response Helpers

Les méthodes helper de résultat streamText sont dépréciées. Remplacez les méthodes de résultat par des helpers stateless de haut niveau :

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 }).

Vérifications spécifiques aux packages

MCP : MCPTransportConfig.redirect défaut maintenant à 'error'. Définissez uniquement redirect: 'follow' pour les serveurs MCP de confiance qui dépendent des redirects.
Vue : la classe Chat de @ai-sdk/vue est dépréciée. Préférez useChat, y compris l'init getter/ref pour les inputs de chat réactifs.
Anthropic et @ai-sdk/google-vertex/anthropic : providerMetadata.anthropic.cacheCreationInputTokens a été supprimé. Utilisez usage.inputTokenDetails.cacheWriteTokens ; l'usage Anthropic brut reste à finalStep.providerMetadata?.anthropic?.usage.
Google : renommez les types, classes, et fonctions GoogleGenerativeAI* en Google*, par ex. createGoogleGenerativeAI -> createGoogle. Le point d'entrée google reste inchangé.

Validation

Exécutez le typecheck du projet après les modifications, puis la plus petite suite de tests pertinente. Testez également en fumée le streaming, l'UI de chat, l'exécution de tools, la telemetry, et les flows multi-step si la migration les a touchés. S'il reste des erreurs de type, recherchez le symbole supprimé ou renommé exact dans le guide de migration avant d'inventer une contournement.

migrate-ai-sdk-v6-to-v7