Un guide sur l’appel d’outils avec le SDK TypeScript AI

Apprenez à connecter vos applications d’IA au monde réel à l’aide d’appels d’outils. Ce guide étape par étape destiné aux développeurs TypeScript vous montre comment utiliser des fonctions personnalisées et des outils natifs du fournisseur comme url_context de Gemini avec le SDK Vercel AI.

Dans notre dernier guide, Créez votre première application d’IA en 30 minutes avec le SDK TypeScript AI et Gemininous avons créé une application de chat AI qui s’exécute dans le terminal. Il peut mémoriser des conversations et même générer des données structurées. Mais il a une limite : il vit dans le passé, complètement déconnecté du monde réel.

Demandez-lui « Quelle heure est-il en ce moment ? » et il ne peut pas vous le dire. Demandez un résumé d’un article d’actualité, et c’est impuissant. Votre assistant IA sophistiqué, malgré toute son intelligence, est comme un brillant érudit enfermé dans une bibliothèque avec des livres datant de janvier 1700. Il peut raisonner sur ce qu’il sait, mais il ne peut pas tendre la main et saisir le journal d’aujourd’hui.

C’est ici appel d’outil ça change tout.

L’appel d’outils, parfois appelé appel de fonctions, constitue le pont entre les capacités de raisonnement de votre IA et le monde extérieur. Il transforme votre chatbot d’une base de connaissances isolée en un agent capable de :

• Augmenter ses connaissances avec des données en temps réel (comme obtenir l’heure actuelle ou la météo)
• Étendre ses capacités en accédant à des services externes (comme résumer des pages Web ou interroger des bases de données)
• Prendre des mesures au nom des utilisateurs (comme l’envoi d’e-mails ou la prise de rendez-vous)

Dans ce guide, nous mettrons à niveau le conversing-bot.ts de la précédent article en ajoutant deux types d’outils distincts :

1. Un outil personnalisé: Un simple getCurrentTime fonction qui donne à l’IA accès à l’heure de votre système local
2. Un outil natif du fournisseur: Les Gémeaux sont intégrés url_context outil, qui permet à l’IA de récupérer et de comprendre le contenu de n’importe quelle URL sans que vous écriviez une seule ligne de logique de récupération

À la fin, vous comprendrez comment connecter votre IA à pratiquement tout : API, bases de données, fonctions locales ou services tiers. Passons à la création d’applications d’IA réellement performantes.

Notez que nous ne couvrirons pas le Model Context Protocol (MCP) dans cet article. Alors gardez un œil sur un futur guide sur ce sujet !

Avant de commencer à coder, comprenons ce qui se passe sous le capot. L’appel d’outils peut sembler magique, mais la mécanique est étonnamment élégante.

Lorsque vous fournissez des outils à l’IA, vous ne vous contentez pas de lui confier des fonctions à exécuter aveuglément. Vous lui donnez un menu de super pouvoirs qu’il peut choisir intelligemment d’utiliser en fonction de la demande de l’utilisateur.

Voici le flux complet :

Étape 1 : Le modèle évalue la situation. Lorsqu’un utilisateur envoie un message du type « Quelle heure est-il ? », le LLM examine à la fois l’invite et les descriptions de tous les outils disponibles. Il s’agit de prendre une décision : « Ai-je besoin d’une aide extérieure pour répondre à cette question, et si oui, quel outil dois-je utiliser ?

Étape 2 : Le modèle demande un appel d’outil. Au lieu de générer du texte directement, le LLM génère une requête structurée : « Je dois appeler le getCurrentTime outil sans paramètres. Ce n’est pas un texte destiné à l’utilisateur, c’est une instruction pour le système.

Étape 3 : Le SDK AI orchestre l’exécution. Le SDK Vercel AI intercepte cette requête, trouve votre getCurrentTime fonction, l’exécute et capture le résultat.

Étape 4 : Le modèle formule la réponse finale. Le résultat de l’outil est renvoyé au LLM comme contexte supplémentaire. Le modèle utilise ensuite ces nouvelles informations pour élaborer sa réponse finale destinée à l’utilisateur : « L’heure actuelle est 14h32. »

La beauté du SDK AI est qu’il gère automatiquement toute cette orchestration. Vous définissez les outils et le SDK gère les allers-retours complexes. Maintenant, construisons cela en pratique.

Nous allons commencer par quelque chose de délicieusement simple : apprendre au modèle à lire l’heure. Cela peut sembler trivial, mais cela démontre le modèle fondamental que vous utiliserez pour tous les outils personnalisés.

Étape 1 : Définition de l’outil

Tout d’abord, nous devons importer le tool assistant du SDK AI. Ajoutez ceci à vos importations en haut de votre fichier à côté de vos importations existantes :

import { generateText, stepCountIs, tool } from "ai";

Maintenant, créons l’outil. Le tool() La fonction prend un objet qui définit tout ce que l’IA doit savoir sur cette capacité. Ajoutez ce code avant le main() fonction:

const timeTool = tool({
  description: "Get the current time to answer user questions about time.",
  inputSchema: undefined,
  execute: async () => {
    const now = new Date();
    return `The current time is ${now.toLocaleTimeString()}.`;
  },
});

Décomposons ce que fait chaque propriété :

• description: C’est ce que lit l’IA pour décider quand utiliser l’outil. Considérez-le comme la documentation de l’outil écrite pour une IA, pas pour un humain. Une description claire et spécifique est cruciale, car mieux vous décrivez l’objectif de l’outil, mieux l’IA saura quand l’invoquer.
• inputSchema: Ceci définit les paramètres attendus par l’outil. Pour getCurrentTimenous n’avons besoin d’aucune entrée (l’heure actuelle est l’heure actuelle, après tout), nous définissons donc ceci sur undefined. Dans un prochain article, nous explorerons les outils qui nécessitent des paramètres, par exemple un outil météo qui nécessite un nom de ville.
• execute: Il s’agit de votre véritable fonction TypeScript. Le SDK AI appellera cela lorsque l’IA décide d’utiliser l’outil. Ici, nous créons simplement un nouveau Date objet et le formater. Vous pouvez tout aussi facilement interroger une base de données, appeler une API ou lire un fichier.

Le execute La fonction est uniquement du JavaScript et vous disposez de toute la puissance de Node.js. Besoin de vous connecter à PostgreSQL ? Importez votre client de base de données. Vous souhaitez appeler une API REST ? Utiliser fetch(). Le ciel est la limite. 😉

Étape 2 : Intégrer l’outil dans votre chatbot

Nous devons maintenant informer le modèle de cette nouvelle capacité. Ouvrez le conversing-bot.ts fichier et localisez le generateText appeler à l’intérieur du while boucle. Nous allons le modifier pour inclure l’outil.

Mettez à jour votre generateText appelez pour ressembler à ceci :

const { text } = await generateText({
  model: google("gemini-2.5-flash-lite"),
  messages: messages,
  system:
    "You are a helpful and friendly AI assistant who uses the tools to help the user achieve various tasks. Keep your responses concise and conversational.",
  tools: {
    getCurrentTime: timeTool,
  },
  stopWhen: stepCountIs(2),
});

Notez ces changements clés :

1. Nous avons mis à jour le system invite à informer le modèle qu’il dispose d’outils disponibles. Alors que le SDK AI informe automatiquement le modèle des descriptions des outils, la mise à jour de l’invite système permet de renforcer son rôle, si nécessaire.
2. Nous avons ajouté le tools propriété, qui est un nom d’outil de mappage d’objets avec des définitions d’outils. La clé (getCurrentTime) est ce que l’IA « voit » comme le nom de l’outil, alors rendez-le descriptif.
3. Nous avons ajouté stopWhen: stepCountIs(2)permettant au SDK AI de réaliser jusqu’à 2 étapes (1 appel d’outil + 1 génération de réponse). Cela lui donne la flexibilité d’appeler l’outil puis de répondre. La valeur par défaut est 1, ce qui autorise uniquement des réponses directes sans appels d’outil.

Voyez-le en action

C’est ça. Aucune configuration supplémentaire, aucune configuration complexe. Exécutez votre chatbot :

node --env-file=.env conversing-bot.ts

Essayez maintenant de poser des questions qui nécessitent des informations en temps réel :

• « Quelle heure est-il? »
• « Pouvez-vous me dire l’heure actuelle? »
• « Quelle heure est-il en ce moment ? »

Sans cet outil, le modèle refuserait (en disant qu’il n’a pas accès aux informations en temps réel) ou ferait une supposition incorrecte basée sur les indices contextuels de votre conversation. Avec l’outil, il exécute votre fonction en toute confiance et fournit la réponse précise.

Voici ce qui se passe en coulisses : le modèle lit votre invite, analyse les descriptions des outils, reconnaît que getCurrentTime est pertinent, génère une demande d’appel d’outil, le SDK exécute votre fonction et le modèle utilise le résultat pour élaborer sa réponse. Tout cela se produit en quelques millisecondes.

Les outils personnalisés sont puissants, mais ils nécessitent que vous écriviez vous-même toute la logique. Et si vous souhaitez que votre IA récupère et comprenne le contenu Web ? Vous pourriez écrire un outil qui utilise fetch et analyse le HTML, mais c’est plus simple si votre fournisseur de modèles dispose déjà de cette fonctionnalité intégrée.

Les fournisseurs d’IA comme Google et OpenAI intègrent des outils sophistiqués directement dans leurs modèles. Ces outils natifs du fournisseur gérez des opérations complexes (recherche sur le Web, interprétation de code, analyse d’images) sans que vous ayez à écrire une seule ligne de code. Votre travail consiste simplement à les activer. J’ai construit un outil pour récupérer des URL dans le passé, mais maintenant Gemini l’a nativement et c’est bien mieux !

Ajoutons les Gémeaux url_context outilqui permet au modèle de récupérer et de comprendre le contenu de n’importe quelle URL.

Comprendre les outils natifs du fournisseur

Le url_context l’outil est différent de notre coutume getCurrentTime d’une manière cruciale : vous ne définissez pas le execute fonction. L’infrastructure de Google gère l’ensemble du processus de récupération de l’URL, d’analyse du contenu et d’extraction des informations pertinentes. Le SDK AI a juste besoin de savoir que vous souhaitez activer cette fonctionnalité.

C’est extrêmement puissant. Le web scraping est notoirement fragile car les structures HTML changent, le contenu rendu en JavaScript nécessite des navigateurs sans tête et la limitation de débit est complexe. Les outils natifs du fournisseur résument tout cela. Vous activez l’outil et l’infrastructure du fournisseur fait le gros du travail.

Activer l’outil url_context de Gemini

L’intégration est remarquablement simple. Il vous suffit d’ajouter une ligne à votre tools objet. Mettez à jour votre generateText appelle comme ceci :

const { text } = await generateText({
  model: google("gemini-2.5-flash-lite"),
  messages: messages,
  system:
    "You are a helpful and friendly AI assistant who uses the tools to help the user achieve various tasks beyond the tools capability. Keep your responses concise and conversational.",
  tools: {
    getCurrentTime: timeTool,
    
    url_context: google.tools.urlContext({}),
  },
  stopWhen: stepCountIs(5),
});

C’est ça. Le google.tools.urlContext({}) L’appel active la capacité native de récupération d’URL de Gemini. L’objet vide {} signifie que nous utilisons la configuration par défaut, mais vous pouvez personnaliser le comportement ici si nécessaire.

Étape 3 : Appel d’outil en plusieurs étapes

Il y a un autre ajout important que nous devrions faire. Certaines requêtes peuvent nécessiter que l’IA utilise plusieurs outils en séquence. Par exemple, un utilisateur peut demander : « Quelle heure est-il et pouvez-vous résumer cet article ? » L’IA doit appeler getCurrentTimepuis utilisez url_contextpuis formulez une réponse.

Nous activons ce comportement avec le stopWhen paramètre, et plus particulièrement le stepCountIs helper afin qu’il ne se lance pas dans une boucle infinie en cas d’erreur. Le stopWhen: stepCountIs(5) Le paramètre permet au SDK d’enchaîner jusqu’à 5 appels d’outils avant de générer sa réponse finale.

Remarque : cela s’appelait auparavant maxSteps dans les versions antérieures du SDK.

Testez l’application

Exécutez à nouveau votre chatbot et essayez ces invites :

Voici un exemple d’interaction :

❯ node --env-file=.env conversing-bot.ts
┌  🤖 Conversational CLI Bot with Tools
Welcome! I'm your AI assistant. Type your messages and I'll respond.
Type "exit" or "quit" to end the conversation.
│
◇  You:
│  list the trending topics in https://news.ycombinator.com
│
◇  AI response received
│
◇  AI Response ──────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                │
│  Here are the trending topics on Hacker News:                                                  │
│  *   Uv as a beneficial tool for the Python ecosystem.                                         │
│  *   An Azure outage.                                                                          │
│  *   A discussion on how ancient people perceived themselves.                                  │
│  *   Minecraft's decision to remove obfuscation in Java Edition.                               │
│  *   Carlo Rovelli's perspective on reality.                                                   │
│  *   Raspberry Pi Pico's capability to handle 100 Mbit/S Ethernet.                             │
│  *   Creating an iOS app in Assembly.                                                          │
│  *   China's reforestation efforts, adding forest area equivalent to the size of Texas.        │
│  *   Details about IRCd service.                                                               │
│  *   The ease of setting up an Onion mirror.                                                   │
│  *   A piece questioning the speed of Kafka and suggesting Postgres.                           │
│  *   An exploration of dithering in images.                                                    │
│  *   Information on OS/2 Warp, PowerPC Edition.                                                │
│  *   An update on Tailscale Peer Relays.                                                       │
│  *   A new game console called Board that uses physical pieces and has an open SDK.            │
│  *   The emerging role of GLP-1 therapeutics in treating alcohol and substance use disorders.  │
│  *   A call to action to "Keep Android Open."                                                  │
│  *   OpenAI's agreement to remain in California to facilitate its IPO.                         │
│  *   The sale of AOL to Bending Spoons for $1.5 billion.                                       │
│  *   The role of free and open-source software in powering the internet and DNS.               │
│  *   An introduction to Iommi, a tool for Django development.                                  │
│  *   The U.S. National Science Foundation's contribution to Software-Defined Networking.       │
│  *   An article discussing imperfection as a potential key to Turing patterns in nature.       │
│  *   Learnings from a 14-hour AWS outage.                                                      │
│  *   A bionic eye prosthesis that restores sight lost to macular degeneration.                 │
│  *   A critique of Crunchyroll's subtitle practices.                                           │
│  *   Extropic's development of thermodynamic computing hardware.                               │
│  *   The impact of reforestation on cooling the eastern US.                                    │
│  *   A guide on tuning WezTerm.                                                                │
│  *   Information on Composer: building a fast frontier model with RL.                          │
│                                                                                                │
├────────────────────────────────────────────────────────────────────────────────────────────────╯
│

L’IA comprend implicitement que lorsque vous fournissez une URL, elle doit utiliser le url_context outil. Vous n’avez pas besoin de dire explicitement « utiliser l’outil URL ». Les capacités de raisonnement du modèle combinées à la description de l’outil suffisent. C’est là le pouvoir de l’IA moderne : elle peut comprendre intention et sélectionnez le bon outil pour le travail.

Rassembler tout cela : le robot conversationnel amélioré

Voyons la version complète et mise à niveau de notre bot conversationnel avec des outils personnalisés et natifs du fournisseur fonctionnant en harmonie.

Voici le code complet pour conversing-bot.ts:

import { generateText, stepCountIs, tool } from "ai";
import type { UserModelMessage, AssistantModelMessage } from "ai";
import { google } from "@ai-sdk/google";
import * as prompts from "@clack/prompts";
import process from "node:process";


const timeTool = tool({
  description: "Get the current time to answer user questions about time.",
  inputSchema: undefined,
  execute: async () => {
    const now = new Date();
    return `The current time is ${now.toLocaleTimeString()}.`;
  },
});

const messages: Array<UserModelMessage | AssistantModelMessage> = [];

async function main() {
  prompts.intro("🤖 Conversational CLI Bot with Tools");

  console.log(
    "\nWelcome! I'm your AI assistant. Type your messages and I'll respond.",
  );
  console.log('Type "exit" or "quit" to end the conversation.\n');

  while (true) {
    const userMessage = await prompts.text({
      message: "You:",
      placeholder: "Type your message here...",
      validate: (value) => {
        if (!value) return "Please enter a message";
      },
    });

    if (prompts.isCancel(userMessage)) {
      prompts.cancel("Conversation ended.");
      process.exit(0);
    }

    const messageText = userMessage;
    if (
      messageText === "exit" ||
      messageText === "quit" ||
      messageText === "bye"
    ) {
      prompts.outro("👋 Goodbye! Thanks for chatting!");
      break;
    }

    messages.push({
      role: "user",
      content: messageText,
    });

    const spinner = prompts.spinner();
    spinner.start("AI is thinking...");

    try {
      const { text } = await generateText({
        model: google("gemini-2.5-flash-lite"),
        messages: messages,
        stopWhen: stepCountIs(5),
        system:
          "You are a helpful and friendly AI assistant who uses the tools to help the user achieve various tasks beyond the tools capability. Keep your responses concise and conversational.",
        tools: {
          getCurrentTime: timeTool,
          url_context: google.tools.urlContext({}),
        },
      });

      spinner.stop("AI response received");
      prompts.note(text, "AI Response");

      messages.push({
        role: "assistant",
        content: text,
      });
    } catch (error) {
      spinner.stop("Error occurred");
      console.error("\n❌ Error generating response:", error);
      console.log("Let's try again...\n");
      messages.pop();
    }
  }
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});

Exécutez le bot complet :

node --env-file=.env conversing-bot.ts

Votre IA peut désormais combiner de manière transparente les conversations, les requêtes temporelles et la recherche sur le Web.

Vous pouvez trouver le code source complet sur GitHub.

C’est un Wrap !

En quelques minutes seulement, vous avez transformé votre chatbot d’une base de connaissances isolée en un agent capable d’accéder au monde réel. Vous avez appris le modèle fondamental d’appel d’outils et vu comment il fonctionne à la fois avec les fonctions personnalisées et les outils natifs du fournisseur.

Le SDK Vercel AI gère l’orchestration complexe. Détecter quand les outils sont nécessaires, les exécuter dans le bon ordre et intégrer les résultats dans la conversation, tout en vous donnant le contrôle des capacités que possède votre IA.

Ce n’est que le début. Les modèles que vous avez appris ici s’adaptent à des cas d’utilisation beaucoup plus sophistiqués :

• Outils avec paramètres: Créez un outil météo qui accepte un nom de ville ou un outil de requête de base de données qui prend des critères de recherche
• Raisonnement en plusieurs étapes: Laissez votre IA enchaîner plusieurs appels d’outils pour résoudre des problèmes complexes, comme « recherchez ce sujet, résumez-le et envoyez-moi le résumé par e-mail ».
• Outils interactifs: Créez des outils qui invitent l’utilisateur à fournir des informations supplémentaires en cours de conversation
• Intégration d’API externe: Connectez votre IA à Stripe, SendGrid, Google Calendar ou toute autre API que vous pouvez imaginer

La seule limite est votre créativité. Vous disposez désormais des bases nécessaires pour créer des applications d’IA capables de véritablement interagir avec le monde.

Lectures complémentaires et exploration

Prêt à aller plus loin ? Voici les ressources essentielles :

Le monde de l’ingénierie de l’IA évolue rapidement et l’appel d’outils en est au cœur. Les modèles deviennent plus performants, les outils de plus en plus sophistiqués et les applications que vous pouvez créer deviennent véritablement transformatrices.

Allez construire quelque chose d’incroyable. Connectez votre IA à une base de données, intégrez-la aux API internes de votre entreprise ou créez un assistant personnel qui peut réellement faire des choses en votre nom. La boîte à outils est ouverte et les possibilités sont infinies.

Si vous avez trouvé ce guide utile, partagez-le avec vos amis et collègues développeurs. Si vous avez des questions ou souhaitez partager ce que vous avez construit, n’hésitez pas à nous contacter sur Gazouillement ou GitHub. Bon codage ! 🚀