Comment fournir aux agents IA des outils concrets avec une seule API

Vous créez un agent IA qui aide les utilisateurs dans leurs tâches techniques. L'agent doit rechercher les enregistrements DNS, valider les e-mails, générer des codes QR et vérifier les certificats SSL. Les LLM peuvent raisonner sur ces tâches, mais ils ne peuvent pas passer d'appels réseau ni générer d'images. Votre agent a besoin d'outils.

Le chemin typique est douloureux. Vous connectez une bibliothèque pour le DNS, une autre pour la validation des e-mails, une troisième pour les codes QR. Chacun a sa propre authentification, son propre format de réponse, sa propre gestion des erreurs. La couche d'exécution des outils de votre agent devient une mosaïque de clients API.

Une meilleure approche : donner à l'agent l'accès à une API unique qui couvre toutes ces fonctionnalités. Un jeton d'authentification. Un seul format de réponse. Une limite de taux à suivre. Cet article montre comment câbler le API Botoi (plus de 150 points de terminaison d'outils de développement) en trois architectures d'agent : utilisation de l'outil Claude, appel de fonction OpenAI et MCP.

Le modèle d'utilisation des outils en 30 secondes

Tous les principaux fournisseurs LLM prennent désormais en charge l'utilisation d'outils (également appelés appels de fonctions). Le schéma est le même pour tous :

1. Vous définissez un ensemble d'outils avec des noms, des descriptions et des schémas d'entrée.
2. Vous envoyez un message utilisateur au LLM avec les définitions d'outils.
3. Le LLM décide quel outil appeler et avec quels arguments.
4. Votre code exécute l'appel de l'outil (une requête HTTP, une requête de base de données, une lecture de fichier).
5. Vous renvoyez le résultat de l'outil au LLM.
6. Le LLM utilise le résultat pour formuler sa réponse finale.

La boucle ressemble à ceci en pseudocode :

// The tool-use loop: LLM reasons, picks a tool, you execute it
while (true) {
  const response = await llm.chat(messages);

  if (response.stop_reason === "tool_use") {
    const toolCall = response.tool_calls[0];
    const result = await executeToolCall(toolCall);
    messages.push({ role: "tool", content: result });
  } else {
    return response.content;  // Final answer
  }
}

Le LLM n’exécute jamais l’outil lui-même. Il produit une sortie structurée (nom de l'outil + arguments) et votre code effectue l'exécution. Cela signifie que les outils peuvent être n'importe quoi : une commande shell, une requête de base de données ou un appel API.

Pourquoi l'API de Botoi correspond bien au modèle d'utilisation des outils

Chaque point de terminaison botoi a déjà la forme d’une définition d’outil. Chaque point de terminaison prend une entrée JSON et renvoie une sortie JSON avec une structure cohérente. Voici à quoi ressemble la définition d'un outil de recherche DNS :

// Each botoi endpoint maps to a tool definition
// The OpenAPI spec at /openapi.json provides this automatically
{
  "name": "dns_lookup",
  "description": "Look up DNS records for a domain",
  "parameters": {
    "type": "object",
    "properties": {
      "domain": { "type": "string", "description": "Domain to query" },
      "type": { "type": "string", "enum": ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] }
    },
    "required": ["domain"]
  }
}

Trois choses font que cela fonctionne bien pour les agents :

• Effacer les schémas d’entrée. Chaque point de terminaison accepte un petit corps JSON bien défini. Les LLM sont efficaces pour produire du JSON structuré lorsque le schéma est serré.
• Format de sortie cohérent. Tous les points de terminaison reviennent {"{ success: true, data: { ... } }"} ou {"{ success: false, message: '...' }"}. L'analyseur de résultats de l'outil de votre agent gère chaque point de terminaison de la même manière.
• Spécification OpenAPI pour la découverte automatique. La spécification à api.botoi.com/openapi.json contient des schémas complets pour plus de 150 points de terminaison. Vous pouvez générer des définitions d'outils par programmation au lieu de les écrire à la main.

Architecture 1 : utilisation de l'outil Claude avec le SDK Anthropic

L'API d'utilisation des outils de Claude vous permet de transmettre des définitions d'outils avec vos messages. Lorsque Claude décide d'appeler un outil, il renvoie un tool_use bloc de contenu avec le nom de l’outil et l’entrée. Vous exécutez l'appel et renvoyez le résultat sous forme de tool_result.

Voici un agent fonctionnel capable de rechercher des enregistrements DNS, de vérifier les certificats SSL et de valider les e-mails à l'aide de botoi :

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const BOTOI_KEY = process.env.BOTOI_API_KEY;

// Define botoi endpoints as Claude tools
const tools = [
  {
    name: "dns_lookup",
    description: "Look up DNS records (A, MX, TXT, etc.) for a domain",
    input_schema: {
      type: "object",
      properties: {
        domain: { type: "string", description: "Domain to query" },
        type: { type: "string", enum: ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] },
      },
      required: ["domain"],
    },
  },
  {
    name: "ssl_check",
    description: "Check SSL certificate and security headers for a domain",
    input_schema: {
      type: "object",
      properties: {
        url: { type: "string", description: "Domain or URL to check" },
      },
      required: ["url"],
    },
  },
  {
    name: "email_validate",
    description: "Validate an email address (syntax, MX, disposable check)",
    input_schema: {
      type: "object",
      properties: {
        email: { type: "string", description: "Email address to validate" },
      },
      required: ["email"],
    },
  },
];

// Map tool names to botoi API endpoints
const toolEndpoints = {
  dns_lookup: "/v1/dns/lookup",
  ssl_check: "/v1/ssl",
  email_validate: "/v1/email/validate",
};

async function callBotoiTool(name, input) {
  const endpoint = toolEndpoints[name];
  const res = await fetch(\`https://api.botoi.com\${endpoint}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${BOTOI_KEY}\`,
    },
    body: JSON.stringify(input),
  });
  return await res.json();
}

async function runAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];

  while (true) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 1024,
      tools,
      messages,
    });

    // If Claude wants to use a tool, execute it and feed the result back
    if (response.stop_reason === "tool_use") {
      const toolBlock = response.content.find((b) => b.type === "tool_use");
      const result = await callBotoiTool(toolBlock.name, toolBlock.input);

      messages.push({ role: "assistant", content: response.content });
      messages.push({
        role: "user",
        content: [
          {
            type: "tool_result",
            tool_use_id: toolBlock.id,
            content: JSON.stringify(result),
          },
        ],
      });
    } else {
      // Claude is done; return the final text
      return response.content[0].text;
    }
  }
}

// Usage
const answer = await runAgent(
  "Check the DNS records and SSL certificate for stripe.com"
);
console.log(answer);

Demandez à cet agent « Vérifiez les enregistrements DNS et le certificat SSL pour stripe.com » et Claude effectuera deux appels d'outils en séquence, puis synthétisera les résultats dans un résumé lisible. L'agent gère automatiquement le raisonnement en plusieurs étapes ; Claude choisit les outils à appeler, dans quel ordre, en fonction de la question de l'utilisateur.

Architecture 2 : appel de fonction OpenAI

L'appel de fonction d'OpenAI suit le même modèle avec des noms de champs différents. Les outils sont définis sous un tools tableau avec type: "function". Le modèle revient tool_calls quand il veut exécuter une fonction.

Une différence : GPT peut demander plusieurs appels d’outils en une seule réponse. Le code ci-dessous gère l'exécution d'outils parallèles :

import OpenAI from "openai";

const openai = new OpenAI();
const BOTOI_KEY = process.env.BOTOI_API_KEY;

const tools = [
  {
    type: "function",
    function: {
      name: "dns_lookup",
      description: "Look up DNS records for a domain",
      parameters: {
        type: "object",
        properties: {
          domain: { type: "string" },
          type: { type: "string", enum: ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] },
        },
        required: ["domain"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "qr_generate",
      description: "Generate a QR code SVG from text or a URL",
      parameters: {
        type: "object",
        properties: {
          text: { type: "string", description: "Content to encode" },
          size: { type: "number", description: "Size in pixels (100-1000)" },
        },
        required: ["text"],
      },
    },
  },
];

const toolEndpoints = {
  dns_lookup: "/v1/dns/lookup",
  qr_generate: "/v1/qr/generate",
};

async function callBotoiTool(name, args) {
  const endpoint = toolEndpoints[name];
  const res = await fetch(\`https://api.botoi.com\${endpoint}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${BOTOI_KEY}\`,
    },
    body: JSON.stringify(args),
  });
  return await res.json();
}

async function runAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];

  while (true) {
    const response = await openai.chat.completions.create({
      model: "gpt-4o",
      tools,
      messages,
    });

    const choice = response.choices[0];

    if (choice.finish_reason === "tool_calls") {
      messages.push(choice.message);

      for (const call of choice.message.tool_calls) {
        const args = JSON.parse(call.function.arguments);
        const result = await callBotoiTool(call.function.name, args);

        messages.push({
          role: "tool",
          tool_call_id: call.id,
          content: JSON.stringify(result),
        });
      }
    } else {
      return choice.message.content;
    }
  }
}

const answer = await runAgent(
  "Generate a QR code for https://botoi.com and look up the MX records"
);
console.log(answer);

GPT-4o peut appeler les deux dns_lookup et qr_generate en parallèle lorsque les tâches sont indépendantes. La boucle traite tous les appels d'outils avant de renvoyer les résultats au modèle.

Architecture 3 : agents basés sur MCP

Le Model Context Protocol (MCP) est une approche différente. Au lieu de définir des outils dans votre code, l'agent découvre les outils d'un serveur MCP au moment de l'exécution. Botoi exécute un serveur MCP sur api.botoi.com/mcp avec 44 outils sélectionnés.

Il s’agit de l’option zéro code. Aucune définition d'outil à écrire. Aucune couche d'exécution à construire. Le client MCP (Claude Desktop, Cursor, Claude Code, VS Code) se connecte au serveur, découvre les outils et gère l'exécution.

// Claude Desktop, Cursor, or VS Code: add to your MCP config
{
  "mcpServers": {
    "botoi": {
      "type": "streamable-http",
      "url": "https://api.botoi.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

// Claude Code: one command
// claude mcp add botoi --transport streamable-http https://api.botoi.com/mcp

Après avoir ajouté cette configuration, votre assistant IA peut appeler n'importe lequel des 44 outils par son nom. Demandez "rechercher les enregistrements MX pour github.com" et l'assistant appelle le lookup_dns outil, transmet le domaine et le type d'enregistrement, et renvoie du JSON structuré.

MCP est le bon choix lorsque vous utilisez un assistant IA de manière interactive (dans un IDE ou un client de chat). L'appel de fonction est le bon choix lorsque vous créez un agent de programmation qui s'exécute de manière autonome.

Pourquoi une API unique est importante pour les agents

Lorsque vous connectez des outils pour un agent, la couche d'exécution des outils est la partie qui s'interrompt en production. Chaque API externe que vous ajoutez introduit son propre mode de défaillance. Considérez ce qui se passe lorsque votre agent utilise cinq API différentes :

• Cinq clés API pour effectuer une rotation et stocker en toute sécurité.
• Cinq limites de taux à suivre indépendamment.
• Cinq formats de réponse à normaliser avant de renvoyer les résultats au LLM.
• Cinq chemins de gestion des erreurs avec différents codes d’état et formes d’erreur.
• Cinq tableaux de bord de facturation à surveiller.

Avec une seule API, la fonction d'exécution de votre outil se réduit à un seul modèle :

// Shared helper: route any tool call to the right botoi endpoint
async function executeBotoiTool(name, input) {
  const ENDPOINTS = {
    dns_lookup:      "/v1/dns/lookup",
    ssl_check:       "/v1/ssl",
    email_validate:  "/v1/email/validate",
    qr_generate:     "/v1/qr/generate",
    ip_lookup:       "/v1/ip/lookup",
    hash_generate:   "/v1/hash",
    jwt_decode:      "/v1/jwt/decode",
    pii_detect:      "/v1/pii/detect",
    whois_lookup:    "/v1/whois",
    token_count:     "/v1/token/count",
  };

  const path = ENDPOINTS[name];
  if (!path) throw new Error("Unknown tool: " + name);

  const res = await fetch(\`https://api.botoi.com\${path}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${process.env.BOTOI_API_KEY}\`,
    },
    body: JSON.stringify(input),
  });

  if (!res.ok) {
    const err = await res.json();
    return { error: err.message || "API call failed" };
  }

  return await res.json();
}

Chaque appel d'outil passe par le même en-tête d'authentification, la même forme d'erreur, la même limite de débit. Ajouter un nouvel outil signifie ajouter une ligne au ENDPOINTS carte. Pas de nouvelles dépendances, pas de nouvelles informations d'identification.

Choisir les bons outils pour votre agent

N'enregistrez pas les plus de 150 points de terminaison en tant qu'outils. Les LLM fonctionnent moins bien lorsque la liste d'outils est longue, car ils doivent raisonner sur plus d'options. Choisissez les 5 à 15 outils dont votre agent a besoin pour son cas d'utilisation spécifique.

Quelques archétypes d'agents et les outils qui leur correspondent :

• Agent de surveillance des infrastructures : Recherche DNS, vérification SSL, en-têtes HTTP, vérification des performances du site, vérification de la disponibilité, recherche IP
• Auditeur de sécurité des e-mails : Vérification SPF, vérification DMARC, vérification DKIM, vérification des enregistrements MX, validation des e-mails, vérification des e-mails jetables
• Agent de traitement des données : Format JSON, CSV vers JSON, XML vers JSON, encodage/décodage Base64, HTML vers Markdown, détection PII
• Assistant développeur : Décodage JWT, génération de hachage, génération d'UUID, analyse cron, test regex, nombre de jetons

Commencez étroit. Ajoutez des outils lorsque les utilisateurs de votre agent demandent des fonctionnalités qu'il ne peut pas gérer. Surveillez les outils qui sont appelés et supprimez ceux qui ne se déclenchent jamais.

Points clés

• Raison du LLM ; les outils agissent. Le modèle d'utilisation des outils sépare la planification du LLM de l'exécution des actions du monde réel. Votre agent a besoin d’outils fiables pour combler cette lacune.
• Une API, un chemin d'exécution. Une API unique avec une authentification, un format de réponse et une gestion des erreurs cohérents simplifie la couche d'exécution d'outils dont chaque agent a besoin.
• Trois architectures, même API. L'utilisation de l'outil Claude, l'appel de fonction OpenAI et MCP fonctionnent tous avec les points de terminaison botoi. Choisissez celui qui correspond à votre modèle de déploiement.
• Gardez la liste d’outils petite. Enregistrez 5 à 15 outils par agent. Trop d'options dégradent la précision de la sélection des outils du LLM.
• MCP pour une utilisation interactive, fonction faisant appel à des agents autonomes. MCP gère la découverte et l'exécution des outils pour vous. L'appel de fonction vous donne un contrôle total sur la boucle.

La Documents sur l'API répertoriez chaque point de terminaison avec des schémas de demande/réponse. Le Spécification OpenAPI vous permet de générer des définitions d'outils par programmation. Le Manifeste de l'outil MCP montre les 44 outils sélectionnés disponibles via MCP.