ai-sdk

Vue d’ensemble de la skill ai-sdk

À quoi sert cette skill ai-sdk

La skill ai-sdk est un guide pratique pour les développeurs qui construisent avec l’AI SDK de Vercel, en particulier quand vous avez besoin d’une aide à jour et sensible aux versions plutôt que de conseils LLM génériques. Son rôle concret est de vous aider à choisir la bonne forme d’API, à vérifier une syntaxe moderne et à éviter les patterns obsolètes lorsque vous ajoutez du chat, du streaming, des tools, de la génération structurée, des embeddings ou des agents à une application.

Pour qui installer cette skill ai-sdk

Les profils pour lesquels elle est la plus adaptée incluent :

• Les développeurs full-stack qui évaluent ai-sdk for Full-Stack Development
• Les équipes qui migrent un ancien code AI SDK vers des API plus récentes
• Les développeurs qui utilisent generateText, streamText, des tools, ToolLoopAgent ou useChat
• Toute personne qui compare la configuration des providers entre OpenAI, Anthropic, Google et un accès via gateway
• Les builders qui veulent éviter davantage de faux départs qu’avec un simple prompt du type « écris-moi du code AI »

Pourquoi cette skill est plus utile qu’un prompt générique

Son principal avantage, c’est qu’elle indique explicitement que la connaissance interne des modèles sur l’AI SDK est souvent périmée. Au lieu de se fier à la mémoire, elle vous oriente vers la documentation des packages installés localement, l’inspection du code source et des références ciblées comme les changements d’API fréquents, l’usage du gateway, les devtools et les patterns d’agents type-safe. Cette ai-sdk skill est donc plus fiable qu’un prompt classique pour décider d’une installation comme pour avancer sur l’implémentation.

Ce qui compte le plus avant d’adopter ai-sdk

Voici ce que les utilisateurs veulent généralement savoir en premier :

• s’ils doivent commencer par installer uniquement ai
• comment choisir ensuite les packages provider sans trop en installer
• quelles API ont changé récemment
• si les exemples useChat trouvés en ligne sont encore valides
• comment déboguer les tool loops et les exécutions en streaming
• si le SDK convient à des routes serveur, des interfaces React, ou aux deux

Si ce sont précisément vos points de blocage, cette page vous fera gagner du temps.

Comment utiliser la skill ai-sdk

Commencez par le chemin d’installation minimal pour ai-sdk

Commencez par l’installation la plus minimale possible :

pnpm add ai

La recommandation du dépôt est volontaire ici : installez d’abord uniquement le package cœur ai. N’ajoutez pas immédiatement @ai-sdk/openai, @ai-sdk/react ou d’autres packages provider/client tant que votre cas d’usage ne l’exige pas réellement. Cela réduit les mauvaises hypothèses de départ et garde votre implémentation alignée sur la documentation actuelle.

Si vous installez la skill GitHub elle-même dans votre workflow agent, utilisez :

npx skills add vercel/ai --skill ai-sdk

Vérifiez la doc en local avant de demander du code

Le bon réflexe n’est pas « demander de mémoire ». Le workflow à suivre est :

1. Vérifier que node_modules/ai/docs/ existe.
2. Chercher dans node_modules/ai/docs/ et node_modules/ai/src/.
3. Ne revenir vers ai-sdk.dev ou les références du repo qu’ensuite.

C’est le comportement pratique le plus important dans ce ai-sdk guide, car les API de l’AI SDK évoluent vite et beaucoup d’exemples publics accusent un temps de retard.

Lisez d’abord ces fichiers

Si vous voulez vous orienter rapidement, commencez dans cet ordre :

1. skills/use-ai-sdk/SKILL.md
2. skills/use-ai-sdk/references/common-errors.md
3. skills/use-ai-sdk/references/ai-gateway.md
4. skills/use-ai-sdk/references/devtools.md
5. skills/use-ai-sdk/references/type-safe-agents.md

Pourquoi cet ordre fonctionne :

• SKILL.md donne les conditions de déclenchement et le workflow
• common-errors.md vous évite très tôt les pièges liés aux renommages d’API
• ai-gateway.md aide à obtenir rapidement un modèle fonctionnel
• devtools.md améliore le débogage une fois le code lancé
• type-safe-agents.md devient important quand les types UI et agent doivent rester cohérents

Identifiez les écarts d’API actuels avant d’écrire du code

Un frein majeur à l’adoption consiste à recopier de vieux exemples. Les références signalent plusieurs changements qui affectent concrètement l’ai-sdk usage :

• maxTokens → maxOutputTokens
• maxSteps → stopWhen: stepCountIs(n)
• parameters pour les tools → inputSchema
• certains anciens patterns de génération d’objets ont changé
• useChat a beaucoup évolué et doit être revérifié avant réutilisation

Si votre premier prompt vers la skill inclut votre version actuelle du package et tout code legacy, l’aide à la migration sera nettement meilleure.

Utilisez AI Gateway quand vous voulez un premier succès rapide

Pour beaucoup d’équipes, le chemin le plus rapide passe par une configuration appuyée sur le gateway. La skill inclut une référence utile sur Vercel AI Gateway, où un modèle peut être sélectionné avec une chaîne comme :

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  prompt: 'What is love?',
});

C’est utile quand votre décision porte moins sur le câblage du SDK provider que sur la validation rapide du comportement produit.

Avant de coder en dur un identifiant de modèle, récupérez la liste actuelle des modèles. La référence indique explicitement qu’il ne faut pas se fier à sa mémoire pour les noms de modèles.

Quelles informations donner à la skill ai-sdk

Donnez à la skill suffisamment de contexte pour qu’elle choisisse la bonne structure de packages et le bon pattern d’API. Une bonne demande inclut généralement :

• le runtime : Next.js, Node.js, Vercel, edge/serverless, etc.
• l’objectif : UI de chat, agent, RAG, extraction structurée, tool calling
• les versions de packages actuellement installées
• si vous avez besoin de streaming
• une préférence provider ou l’usage du gateway
• les contraintes frontend, comme des hooks React ou un usage strictement serveur
• tout code qui échoue et le texte exact de l’erreur

Entrée faible :

• « Aide-moi à utiliser AI SDK »

Entrée forte :

• « J’ai un projet Next.js app router sur AI SDK 6, j’ai besoin d’un chat en streaming avec tool calling, je veux démarrer avec gateway, et mon ancien code useChat ne fonctionne plus. Montre-moi la route serveur minimale et la structure UI minimale. »

Le second prompt permet à la skill de cibler les bonnes docs et les noms d’API actuels.

Transformer un besoin vague en meilleur prompt ai-sdk

Une bonne formule :

• contexte applicatif
• expérience utilisateur visée
• état actuel de l’implémentation
• contraintes
• format de sortie attendu

Exemple :

I'm building a customer-support assistant in Next.js. I need ai-sdk usage for streamed responses, one weather tool, and a React chat UI. Keep packages minimal, prefer gateway first, and explain any AI SDK 6 changes from older examples. Return the file list, install commands, and the smallest working path.

Cela fonctionne mieux que de demander « un agent », car la skill a assez de structure pour éviter de produire un échafaudage générique.

Choisissez le bon workflow ai-sdk selon le travail à faire

Utilisez la skill différemment selon la tâche :

• Pour une première installation : demandez l’ensemble minimal de packages et une seule requête qui fonctionne
• Pour une migration : collez l’ancien code et demandez les renommages d’API et les changements de comportement
• Pour le tool calling : demandez la forme du schéma des tools et les conditions d’arrêt
• Pour le chat côté frontend : demandez explicitement les patterns useChat actuels
• Pour le débogage : demandez comment inspecter les exécutions avec DevTools et où les traces sont stockées

C’est dans ce prompting orienté par tâche que la ai-sdk skill apporte plus de valeur qu’une simple lecture rapide du repo.

Utilisez DevTools une fois le code lancé si le comportement reste incorrect

Quand le code compile mais que le modèle se comporte de manière inattendue, la référence DevTools devient particulièrement utile. Elle capture les appels SDK, les étapes et les interactions avec les tools dans :

.devtools/generations.json

C’est particulièrement utile pour :

• les boucles de tool calls cachées
• les sorties structurées mal formées
• les décalages entre prompt et tools
• les comportements de streaming difficiles à comprendre
• l’inspection des tokens et des étapes pendant l’exécution d’agents

Pour une décision d’adoption, c’est important, car cela réduit le coût de débogage après l’installation initiale.

Utilisez des patterns d’agents type-safe quand le rendu UI compte

Si vous construisez une UI pilotée par agent, la référence sur les agents type-safe montre bien que la skill est utile au-delà de simples exemples de démonstration. Elle présente un pattern dans lequel les définitions d’agents exportent des types UIMessage inférés, ce qui rend le rendu useChat plus fiable.

C’est particulièrement pertinent pour ai-sdk for Full-Stack Development, où la configuration d’agent côté backend et le rendu des messages côté frontend doivent rester alignés.

Cas où cette skill n’est pas le bon choix

Ne choisissez pas cette skill si vous avez surtout besoin de :

• documentation de SDK propres à un provider, sans lien avec le package ai
• conseils généraux de prompt engineering sans travail d’implémentation
• recommandations AI orientées Python en priorité
• théorie LLM indépendante de tout framework

Cette skill est la plus pertinente quand votre question porte précisément sur l’implémentation ou le débogage de l’AI SDK dans une stack JavaScript/TypeScript.

FAQ sur la skill ai-sdk

Cette skill ai-sdk convient-elle aux débutants ?

Oui, si vous êtes déjà à l’aise avec les bases de JavaScript ou TypeScript. Elle est accessible aux débutants dans le sens où elle clarifie les premières étapes, mais elle suppose que vous savez modifier des fichiers de projet, installer des packages et suivre les conventions d’un framework.

La skill ai-sdk remplace-t-elle la lecture de la documentation ?

Non. Elle s’utilise au mieux comme une couche d’orientation qui vous dit où regarder et quels patterns modernes considérer comme fiables. Sa valeur principale est de réduire les mauvais aiguillages, pas de remplacer la documentation source.

Quel est le principal avertissement avant une installation ai-sdk ?

Ne faites pas confiance à d’anciens exemples ni à la mémoire du modèle concernant la syntaxe de l’AI SDK. Le dépôt insiste à plusieurs reprises sur la nécessité de vérifier d’abord la documentation installée et le code source. Ce n’est pas une simple note de prudence : c’est central pour réussir une ai-sdk install et l’implémentation qui suit.

Faut-il installer tous les packages provider dès le départ ?

En général, non. Commencez avec ai, puis ajoutez les packages provider ou client uniquement lorsque votre cas d’usage le demande. Cela rend le choix des dépendances plus intentionnel et évite d’introduire dès le départ des hypothèses obsolètes dans votre setup.

Est-ce principalement destiné aux applications de chat ?

Non. Le chat est un cas d’usage fréquent, mais la skill convient aussi à la génération structurée, au tool calling, aux agents, aux embeddings, à l’accès aux modèles via gateway et aux réponses serveur en streaming.

En quoi est-ce différent du fait de demander à un LLM d’écrire du code AI SDK ?

Un prompt générique peut générer avec assurance des API obsolètes. Cette skill est meilleure parce qu’elle impose un workflow de vérification : docs locales, références à jour, pièges de migration connus et lecture ciblée des bons fichiers. Cela améliore la fiabilité et réduit les reprises.

Est-ce utile pour React et useChat ?

Oui, mais avec une réserve : useChat a beaucoup changé. Traitez les anciens snippets avec prudence et utilisez la skill pour vérifier la forme actuelle avant de réutiliser des exemples d’UI.

Quand ne faut-il pas utiliser ce guide ai-sdk ?

Passez votre chemin si votre problème concerne surtout la facturation d’un fournisseur, une stratégie d’évaluation de modèles ou une intégration sur une plateforme non-JS. Utilisez-le lorsque votre blocage porte sur un détail d’implémentation actuel de l’AI SDK.

Comment améliorer l’usage de la skill ai-sdk

Donnez un contexte versionné, pas seulement des objectifs

Le moyen le plus rapide d’obtenir de meilleurs résultats est d’indiquer les versions exactes, en particulier pour ai et les packages associés. Beaucoup d’échecs viennent de demandes de type « donne-moi du code AI SDK » sans préciser si vous utilisez une version récente ou si vous migrez un ancien code.

Demandez d’abord des morceaux minimaux qui fonctionnent

Mieux que « construis toute mon app agent » :

• « montre le plus petit exemple generateText »
• « ajoute un tool »
• « puis passe-le en streaming »
• « puis branche useChat »

Ce workflow incrémental rend le ai-sdk guide beaucoup plus efficace, car chaque étape peut être vérifiée dans la documentation actuelle avant que la complexité ne s’accumule.

Remontez les erreurs mot pour mot

Si quelque chose casse, incluez l’erreur exacte et l’extrait de code concerné. La référence common-errors.md existe parce que beaucoup de problèmes viennent de noms d’API presque corrects, mais pas tout à fait. Une erreur précise permet souvent à la skill de savoir immédiatement si vous utilisez une ancienne doc, de mauvais imports de packages ou des options dépassées.

Dites si vous voulez un setup gateway ou provider direct

Beaucoup d’ambiguïtés disparaissent si vous précisez d’emblée l’un de ces choix :

• « Use Vercel AI Gateway first »
• « Use direct OpenAI provider package »
• « Keep provider choice abstract for now »

Cela change les commandes d’installation, la sélection du modèle et la structure des exemples.

Soyez explicite sur le runtime et les frontières du framework

Pour obtenir une aide plus solide sur l’ai-sdk usage, indiquez :

• serveur uniquement ou client + serveur
• Next.js App Router ou un autre framework
• runtime edge ou Node
• niveau d’exigence TypeScript
• si les tools appellent des API internes ou des services externes

Ces détails influencent directement ce à quoi ressemble un code « correct ».

Principaux modes d’échec à surveiller

Les causes de baisse de qualité les plus fréquentes sont :

• s’appuyer sur des exemples useChat obsolètes
• recopier des noms d’options dépréciés
• coder en dur d’anciens identifiants de modèle
• installer trop de packages trop tôt
• demander du code d’agent sans définir les tools et les conditions d’arrêt
• déboguer avec des console.log au lieu des traces d’exécution

Si vous évitez ces pièges, la ai-sdk skill devient nettement plus fiable.

Demandez à la skill de comparer deux voies d’implémentation

Une bonne manière d’améliorer les résultats consiste à demander une décision, pas seulement du code. Par exemple :

Compare ai-sdk usage for (A) gateway-first quick setup and (B) direct provider setup in my Next.js app. Recommend one based on fast prototyping, future portability, and minimal package count.

Ce type de prompt produit une meilleure aide à l’adoption que « montre-moi la doc ».

Itérez après la première réponse avec des éléments concrets

Après une première réponse, vous pouvez améliorer fortement la qualité en renvoyant l’un de ces éléments :

• l’arborescence actuelle des fichiers
• la liste des packages installés
• la requête exacte qui échoue
• un extrait capturé de .devtools/generations.json
• un extrait de doc locale depuis node_modules/ai/docs/

Cette itération fondée sur des preuves est le meilleur moyen de faire passer la ai-sdk skill d’un guide général à une aide d’implémentation exploitable.