Ces trois API ne représentent pas trois niveaux de qualité du modèle. Elles organisent différemment l’exécution. generateText attend un résultat complet, streamText expose progressivement les événements et ToolLoopAgent encapsule une boucle multi-étapes capable d’appeler des outils.
generateText : un traitement borné
Utilisez generateText pour un résumé, une extraction structurée, une classification ou une tâche en arrière-plan. Le code attend la fin puis récupère texte, usage, raison d’arrêt, appels et résultats d’outils. Cette forme est facile à tester et à relancer. Elle convient aussi à un petit nombre d’étapes d’outils si vous gardez des limites explicites.
streamText : améliorer l’expérience interactive
streamText devient pertinent lorsqu’un utilisateur attend devant l’interface. Le flux peut contenir texte, sources, appels d’outils et autres événements ; le client doit donc gérer davantage qu’une concaténation de caractères. Prévoyez annulation, déconnexion, erreur après le premier fragment et persistance du résultat final. Le streaming réduit la latence perçue, pas le temps de calcul total.
ToolLoopAgent : une boucle réutilisable
ToolLoopAgent regroupe modèle, instructions, outils et conditions d’arrêt dans un objet réutilisable. Ses méthodes generate et stream exécutent la boucle jusqu’au résultat final ou à une limite. Choisissez-le lorsqu’un même agent intervient dans plusieurs routes ou lorsque les étapes et outils doivent être centralisés. Une boucle autonome exige budgets, délais, validation des entrées et journalisation de chaque étape.
Arbre de décision
- Une seule réponse complète suffit : generateText.
- L’utilisateur doit voir la réponse arriver : streamText.
- Le système doit enchaîner plusieurs décisions et outils : ToolLoopAgent.
- Le processus est métier, déterministe et auditable : préférez un workflow explicite, qui peut appeler generateText à certaines étapes.
Ne transformez pas une génération simple en agent. Chaque étape supplémentaire augmente coût, latence et possibilités d’échec.
Sécurité et observabilité
Décrivez chaque outil avec un schéma strict et contrôlez les autorisations dans son exécuteur. Limitez étapes, durée, tokens et outils actifs. Enregistrez modèle, usage, temps jusqu’au premier fragment, résultat des outils et raison d’arrêt, tout en filtrant les données sensibles. Les DevTools officiels sont destinés au développement local et peuvent conserver les interactions en clair.
FAQ
streamText est-il toujours préférable pour un chat ?
Souvent, mais une réponse très courte ou une contrainte d’infrastructure peut justifier generateText.
ToolLoopAgent remplace-t-il un orchestrateur ?
Non. Il convient à une boucle pilotée par le modèle ; un processus métier critique bénéficie d’étapes explicites et de reprise contrôlée.
Comment tester ?
Injectez un modèle simulé, vérifiez les événements, les schémas d’outils, les limites et les erreurs à chaque étape.
Trois usages distincts dans l’AI SDK
~~~typescript import { generateText, streamText } from 'ai' import { openai } from '@ai-sdk/openai'
const generated = await generateText({ model: openai('gpt-4.1-mini'), prompt: 'Résume ce ticket en une phrase.', })
const streamed = streamText({ model: openai('gpt-4.1-mini'), prompt: 'Explique la résolution étape par étape.', abortSignal: request.signal, }) return streamed.toTextStreamResponse() ~~~
Utilisez generateText lorsque le serveur attend le résultat complet et streamText lorsque le temps avant le premier token compte. Propagez le signal d’annulation. Pour une boucle agentique, préférez ToolLoopAgent avec limite de pas, schémas et délais par outil. Les écritures doivent être idempotentes et confirmées ; journalisez chaque étape, pas seulement la réponse finale.