Comment tester des agents IA appelant vos APIs sans perdre de données

Un agent de codage IA a exécuté un script, l’a vu réussir, puis a vu une table de base de données de production disparaître. Le post-mortem de Hacker News est devenu viral avec un titre simple : « L’IA n’a pas supprimé votre base de données, vous l’avez fait. » Le constat est juste : l’agent a suivi une définition d’outil, l’outil a appelé un vrai point de terminaison, ce point de terminaison n’avait pas de garde-fous, et un humain avait donné les clés à un processus qui ne s’arrête pas devant DELETE FROM users. Un autre fil r/ClaudeAI a décrit une boucle de facturation qui a consommé des centaines de dollars en jetons avant d’être détectée. Surface différente, même échec : personne n’avait testé l’API.

Essayez Apidog aujourd’hui

💡 Si vous déployez des agents autonomes qui appellent vos API, ce guide est pour vous. Vous allez voir comment simuler les points de terminaison externes pendant le développement, isoler les opérations destructrices, tester les contrats de schéma d’outils, définir des budgets par agent et rejouer les scénarios d’échec avant la production. Nous utiliserons Apidog pour l’échafaudage de test, car il prend en charge OpenAPI nativement, exécute des serveurs de maquette sans code de liaison et fournit des scénarios adaptés aux séquences d’appels d’outils.

TL;DR

Les agents échouent en production quand leurs outils appellent des API sans garde-fous : limites de débit absentes, pas d’idempotence, suppressions directes, schémas divergents. La correction tient en quatre pratiques :

1. valider les définitions d’outils de l’agent contre la spécification OpenAPI ;
2. exécuter un serveur de maquette pour les points de terminaison destructeurs ;
3. imposer des budgets par agent et des clés d’idempotence ;
4. rejouer les scénarios d’échec en CI.

Apidog permet d’importer OpenAPI, de générer des maquettes et d’exécuter des scénarios depuis un seul projet.

Introduction

Il y a peu, « tester un agent IA » signifiait surtout envoyer une invite à Claude ou GPT et évaluer la réponse. Ce n’est plus suffisant.

Aujourd’hui, un agent :

1. choisit un outil ;
2. remplit des arguments ;
3. appelle une API ;
4. déclenche des effets réels dans une base de données, un processeur de paiement ou un service tiers.

Une mauvaise définition d’outil ou une limite de débit manquante n’est donc pas un détail d’implémentation. C’est un incident de production potentiel.

Le point clé : la couche modèle compte, mais la couche API est l’endroit où vous contrôlez réellement les dégâts. Cet article montre comment tester les intégrations API des agents IA avec des garde-fous reproductibles : contrats, maquettes, idempotence, budgets et scénarios CI.

Pourquoi les échecs d’agents ressemblent à des échecs d’API

Dans beaucoup de post-mortems d’agents, le modèle n’est pas le vrai protagoniste. L’API l’est.

Injection d’invite

Un utilisateur télécharge un PDF contenant des instructions cachées. L’agent lit le PDF, puis appelle votre point de terminaison /admin/users avec delete_all=true.

Le modèle n’a pas « décidé » de supprimer les utilisateurs. Il a suivi des instructions. La correction n’est pas seulement de renforcer l’invite, mais de s’assurer que l’API n’expose jamais delete_all=true à un jeton issu d’une session utilisateur standard.

OWASP classe ce risque dans son Top 10 LLM. La mitigation fiable se fait côté API : autorisation, isolation des permissions et validation du contexte.

Schémas d’outils divergents

Votre spécification OpenAPI indique :

amount:
  type: integer
  description: Montant en cents

Mais la définition d’outil de l’agent indique :

{
  "amount": {
    "type": "number",
    "description": "Montant en dollars"
  }
}

Résultat : un remboursement de 19 cents peut devenir 19 dollars. Le modèle n’est pas fautif ; il utilise le schéma fourni. Le problème est une dérive de contrat non testée.

Limites de débit absentes

Un agent entre dans une boucle de réessai et appelle un point de terminaison d’e-mail transactionnel 1 000 fois en deux minutes. Chaque appel coûte de l’argent, envoie potentiellement un vrai e-mail et peut faire signaler votre compte fournisseur.

Le modèle n’est pas malveillant. L’API n’avait tout simplement pas de limite.

Idempotence absente

L’agent appelle POST /payments, reçoit un timeout réseau, puis réessaie. Si le premier appel a bien réussi côté serveur, le client est facturé deux fois.

La couche agent ne peut pas deviner l’état réel de la transaction. L’API doit fournir un mécanisme d’idempotence.

Les quatre garde-fous nécessaires à chaque intégration agent-API

1. Tester les contrats de schéma d’outil

Votre spécification OpenAPI doit être la source de vérité. Les définitions d’outils de l’agent doivent être validées contre cette source à chaque PR.

Voici une vérification Python minimale pour comparer une définition d’outil à une opération OpenAPI :

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Retourne une liste d'erreurs. Liste vide = validation OK."""
    errors = []

    op = openapi_spec["paths"][tool_def["path"]][tool_def["method"].lower()]
    api_schema = op["requestBody"]["content"]["application/json"]["schema"]
    tool_schema = tool_def["input_schema"]

    api_props = set(api_schema.get("properties", {}).keys())
    tool_props = set(tool_schema.get("properties", {}).keys())

    for missing in api_props - tool_props:
        if missing in api_schema.get("required", []):
            errors.append(f"Champ requis manquant dans l'outil : {missing}")

    for extra in tool_props - api_props:
        errors.append(f"Champ défini dans l'outil mais absent de l'API : {extra}")

    for prop, api_def in api_schema.get("properties", {}).items():
        if prop in tool_schema.get("properties", {}):
            tool_def_prop = tool_schema["properties"][prop]

            if api_def.get("type") != tool_def_prop.get("type"):
                errors.append(
                    f"Type incohérent pour {prop}: "
                    f"API={api_def.get('type')} "
                    f"outil={tool_def_prop.get('type')}"
                )

    return errors

À intégrer dans votre CI :

python scripts/validate_agent_tools.py

Règle recommandée : si la liste d’erreurs n’est pas vide, le build échoue.

2. Utiliser des maquettes pour les points de terminaison destructeurs

Les agents ont besoin d’un environnement d’entraînement. Cet environnement ne doit pas être la production.

Pour chaque point de terminaison qui modifie l’état :

• POST
• PUT
• PATCH
• DELETE

créez une réponse de maquette qui respecte le même contrat que l’API réelle, sans déclencher l’opération.

Avec Apidog, vous pouvez générer ces maquettes depuis OpenAPI, puis pointer l’URL de base de l’agent vers le serveur de maquette. Si l’agent tente d’appeler DELETE /users/{id} pendant un test, la maquette répond, mais aucune donnée réelle n’est supprimée.

Ce modèle s’intègre bien dans une approche de développement axé sur le contrat.

3. Ajouter des clés d’idempotence aux écritures

Chaque point de terminaison d’écriture appelé par un agent devrait accepter une clé d’idempotence. L’agent génère un UUID pour une opération logique et le réutilise lors des réessais.

Exemple Express :

const idempotencyCache = new Map();

function idempotency(req, res, next) {
  const key = req.headers['idempotency-key'];

  if (!key) {
    return res.status(400).json({
      error: 'Missing Idempotency-Key header'
    });
  }

  if (idempotencyCache.has(key)) {
    const cached = idempotencyCache.get(key);
    return res.status(cached.status).json(cached.body);
  }

  const originalJson = res.json.bind(res);

  res.json = function (body) {
    idempotencyCache.set(key, {
      status: res.statusCode,
      body
    });

    setTimeout(() => {
      idempotencyCache.delete(key);
    }, 24 * 60 * 60 * 1000);

    return originalJson(body);
  };

  next();
}

app.post('/payments', idempotency, createPayment);

Même logique pour :

• paiements ;
• remboursements ;
• envois d’e-mails ;
• création de tickets ;
• mises à jour CRM ;
• opérations de provisioning.

4. Définir des budgets par agent

Un agent doit avoir des limites strictes :

• budget de jetons ;
• nombre d’appels API par minute ;
• budget monétaire ;
• durée maximale d’exécution ;
• profondeur maximale d’appels d’outils.

Exemple de limites initiales :

agent_budget:
  max_tokens_per_session: 50000
  max_api_calls_per_minute: 30
  max_cost_cents_per_task: 500
  max_tool_call_depth: 10

Quand une limite est atteinte, l’API ou la passerelle doit répondre :

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Budget-Exceeded: max_api_calls_per_minute

Le planificateur de l’agent peut alors arrêter la tâche, escalader vers un humain ou demander une approbation.

Tester les appels API de l’agent avec Apidog

Voici un flux de travail concret dans Apidog.

Vous avez besoin de deux artefacts :

1. la spécification OpenAPI de l’API appelée par l’agent ;
2. les définitions d’outils utilisées par l’agent.

Étape 1 : importer la spécification OpenAPI

Dans Apidog :

1. créez un nouveau projet ;
2. importez votre fichier OpenAPI 3.x ;
3. vérifiez que les chemins, schémas, exemples et méthodes sont bien détectés ;
4. corrigez les schémas incomplets avant d’écrire les tests.

Si votre API n’est pas encore documentée en OpenAPI, commencez par là. La fiabilité agent-API dépend d’une source de vérité unique. Le guide de flux de travail API design-first détaille cette approche.

Étape 2 : définir des réponses de maquette

Pour chaque point de terminaison destructeur :

1. ouvrez le point de terminaison dans Apidog ;
2. ajoutez une réponse de maquette ;
3. générez une charge utile conforme au schéma ;
4. remplacez les valeurs par des données clairement factices.

Exemples de conventions utiles :

{
  "id": "mock_user_1970_001",
  "email": "mock_user_001@example.test",
  "created_at": "1970-01-01T00:00:00Z"
}

Objectif : si une donnée de test fuit dans un journal ou un outil d’observabilité, elle doit être immédiatement identifiable.

Ensuite, démarrez le serveur de maquette Apidog. L’agent peut utiliser une URL de base du type :

https://mock.apidog.com/m1/votre-identifiant-de-projet/

Pendant le développement, l’agent appelle la maquette. En staging, il appelle une base de données isolée. En production, il passe par les garde-fous réels.

Étape 3 : écrire un scénario représentant la séquence de l’agent

Les scénarios Apidog permettent d’enchaîner des appels API avec des assertions.

Pour un agent de triage de tickets, le scénario peut être :

1. POST /auth/token avec des identifiants de test ;
2. capturer le jeton Bearer ;
3. GET /tickets?status=open ;
4. capturer le premier ID de ticket ;
5. POST /tickets/{id}/triage avec une catégorie ;
6. vérifier le statut 200 ;
7. capturer assigned_to ;
8. POST /notifications avec un message ;
9. vérifier que le message respecte une expression régulière.

Ce scénario reproduit ce que l’agent fera réellement, mais sur une infrastructure sans risque.

Pour un manuel plus complet, consultez les tests API pour les ingénieurs QA.

Étape 4 : exécuter les scénarios en CI

Intégrez les scénarios dans votre pipeline.

Commande type :

apidog run -t scenario-id --env test

À exécuter sur chaque PR qui modifie :

• la spécification OpenAPI ;
• les définitions d’outils ;
• les schémas de requête ou réponse ;
• les politiques d’autorisation ;
• les points de terminaison utilisés par l’agent.

Exemple GitHub Actions simplifié :

name: Agent API Tests

on:
  pull_request:
    paths:
      - "openapi/**"
      - "agent-tools/**"
      - "src/api/**"

jobs:
  api-scenarios:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run Apidog scenarios
        run: apidog run -t scenario-id --env test

Étape 5 : comparer deux versions de modèle

Quand vous changez de modèle, ne comparez pas seulement les réponses textuelles. Comparez les appels d’outils.

Procédure :

1. exécutez l’agent avec le modèle A ;
2. capturez la trace des appels d’outils ;
3. exécutez le même scénario avec le modèle B ;
4. comparez les chemins, méthodes et corps de requête.

Différences à surveiller :

• champ requis omis ;
• format de date différent ;
• valeur de priority modifiée ;
• appel supplémentaire non attendu ;
• endpoint alternatif utilisé ;
• ordre d’opérations différent.

Ce type d’évaluation est utile lors de l’adoption d’un nouveau modèle, comme décrit dans l’article sur l’intégration API GPT-5.5.

Techniques avancées et astuces de pro

Fixez la température à zéro dans les tests

Les tests d’intégration doivent être reproductibles.

Pendant les tests :

{
  "temperature": 0,
  "seed": 1234
}

Vous testez le comportement des appels d’outils, pas la créativité du modèle.

Capturez toutes les traces d’appels d’outils

Pour chaque exécution, enregistrez :

• le nom de l’outil ;
• la méthode HTTP ;
• le chemin ;
• les arguments ;
• le code de réponse ;
• le temps de réponse ;
• l’ID de corrélation.

Exemple de trace :

{
  "tool": "triage_ticket",
  "method": "POST",
  "path": "/tickets/123/triage",
  "arguments": {
    "category": "billing",
    "priority": "high"
  },
  "status": 200,
  "correlation_id": "run_abc123"
}

Comparez ces traces aux exécutions précédentes. Si l’agent commence soudainement à appeler /users deux fois, vous devez le voir avant la facture ou l’incident.

Ne donnez jamais d’identifiants de production à un agent

Utilisez :

• des comptes de service à portée limitée ;
• des jetons courts ;
• des permissions minimales ;
• un proxy de signature pour les appels sensibles ;
• des environnements séparés pour maquette, staging et production.

Les secrets de production ne doivent pas être lisibles par l’agent dans un fichier .env.

Séparez les clés de lecture et d’écriture

La plupart des agents lisent plus qu’ils n’écrivent. Donnez-leur des clés en lecture seule par défaut.

Les clés d’écriture doivent être réservées aux tâches qui passent par :

• une approbation humaine ;
• une limite de budget ;
• une validation de schéma ;
• un journal d’audit.

Utilisez HTTP 423 pour les actions verrouillées

Pour une action nécessitant une confirmation humaine, évitez de répondre seulement 403.

Répondez plutôt :

HTTP/1.1 423 Locked
Content-Type: application/json

{
  "error": "human_approval_required",
  "confirmation_url": "https://admin.example.com/approvals/req_123"
}

403 signifie « interdit ». 423 signifie « verrouillé pour le moment ». C’est plus exploitable pour un planificateur d’agent.

Échouez en mode fermé en cas de dérive de schéma

Si la définition d’outil ne correspond plus à OpenAPI :

• ne logguez pas seulement un avertissement ;
• ne laissez pas passer le build ;
• échouez la PR.

Le coût d’un build rouge est inférieur au coût d’une opération destructrice en production.

Erreurs courantes à éviter

• Coder en dur l’URL de maquette dans les invites. Utilisez des variables d’environnement.
• Ignorer l’idempotence sur les « petits » endpoints. Toute écriture en a besoin.
• Journaliser les corps complets en production. Anonymisez les e-mails, jetons et PII.
• Laisser les agents accéder directement à la base de données. Passez par l’API.
• Faire confiance au score de confiance du modèle. Il ne mesure pas la sécurité de l’appel API.

Si vos agents appellent plusieurs services internes, les modèles de test de microservices montrent comment étendre les scénarios à plusieurs services.

Alternatives et outillage

Si vous utilisez déjà LangSmith, gardez-le pour les évaluations au niveau de l’agent et ajoutez une couche de test API. Si vous cherchez une alternative à Postman, Apidog est un excellent remplaçant. Si vous partez de zéro, choisissez un outil qui gère OpenAPI, les maquettes et les scénarios dans le même projet.

Cas d’utilisation réels

Un agent met à jour des lignes de base de données

Une équipe Customer Success crée un agent qui met à jour des champs de compte à partir de tickets support.

Garde-fous appliqués :

• clés d’idempotence sur chaque écriture ;
• base de données bac à sable ;
• 200 relectures de scénarios dans Apidog ;
• validation stricte des énumérations.

Les tests détectent deux cas où l’agent tente d’écrire subscription_status avec une valeur absente de l’énumération. L’équipe ajoute une validation de schéma, puis déploie sans incident.

Un agent appelle une API de paiements

Une équipe fintech développe un agent de remboursement automatisé.

Limites définies :

• maximum 5 remboursements par session ;
• maximum 50 dollars par remboursement ;
• idempotence obligatoire ;
• validation de contrat contre OpenAPI à chaque PR.

La suite de tests de contrat protège l’intégration contre les changements de schéma.

Un agent trie les issues GitHub

Une équipe plateforme construit un agent de triage inspiré de Clawsweeper.

Avant lancement :

• API GitHub simulée dans Apidog ;
• 50 scénarios de test ;
• cas limites couverts : issues supprimées, labels manquants, entrée utilisateur malformée ;
• traces d’appels d’outils comparées entre versions.

Les tests détectent plusieurs plantages avant production.

Checklist de mise en œuvre

À copier dans votre backlog :

• [ ] Importer la spécification OpenAPI dans un outil de test.
• [ ] Générer des maquettes pour tous les endpoints d’écriture.
• [ ] Pointer l’agent vers les maquettes en développement.
• [ ] Ajouter une validation CI entre OpenAPI et définitions d’outils.
• [ ] Exiger Idempotency-Key sur chaque endpoint d’écriture.
• [ ] Ajouter des suppressions logiques par défaut.
• [ ] Séparer les clés lecture/écriture.
• [ ] Définir un budget par agent.
• [ ] Retourner 429 quand le budget est dépassé.
• [ ] Retourner 423 pour les actions avec approbation humaine.
• [ ] Capturer les traces d’appels d’outils.
• [ ] Rejouer les scénarios à chaque PR.
• [ ] Anonymiser les logs de production.
• [ ] Interdire l’accès direct à la base de données.

Conclusion

Le point à retenir : l’agent n’est pas le problème principal. L’API est soit le problème, soit la solution, selon qu’elle a été testée.

Les cinq pratiques à appliquer :

1. traiter les schémas d’outils comme des contrats ;
2. simuler les points de terminaison destructeurs ;
3. exiger l’idempotence sur toutes les écritures ;
4. définir des budgets stricts par agent ;
5. rejouer les scénarios en CI.

Les incidents viraux ne seront pas les derniers. Chaque équipe qui déploie des agents rencontrera au moins une fois une boucle, une dérive de schéma, une action destructrice ou un réessai dangereux. Les équipes qui s’en sortent vite sont celles qui avaient déjà mis les garde-fous.

Téléchargez Apidog et commencez par le serveur de maquette. Pour une perspective QA, consultez les outils de test API pour les ingénieurs QA. Pour écrire des définitions d’outils plus sûres, consultez comment rédiger des fichiers AGENTS.md.

FAQ

Comment tester les appels API des agents IA sans dépenser d’argent en jetons ?

Exécutez l’agent contre un serveur de maquette pendant le développement. Les maquettes Apidog renvoient des réponses réalistes sans appeler les services réels. Fixez la température à 0 et utilisez un petit jeu d’invites reproductibles. La liste de contrôle des tests de l’ingénieur QA couvre cette configuration.

Quelle est la différence entre tester l’agent et tester l’API ?

Le test d’agent vérifie si le modèle choisit le bon outil et remplit correctement les arguments. Le test d’API vérifie si le point de terminaison se comporte correctement quand il est appelé. Il faut tester les deux couches séparément.

Ai-je besoin de clés d’idempotence sur chaque point de terminaison ?

Oui, sur chaque point de terminaison d’écriture. Les lectures sont idempotentes par nature. Les écritures ne le sont pas, et les agents réessaient. Une clé d’idempotence évite les doublons lors des timeouts, erreurs 500 ou réessais automatiques.

Comment empêcher l’injection d’invite de déclencher de mauvais appels API ?

Ne vous reposez pas uniquement sur l’invite. L’API doit appliquer l’autorisation selon le contexte utilisateur original. Si l’utilisateur ne peut pas appeler /admin/delete-all-users, l’agent agissant pour lui ne doit pas pouvoir le faire non plus. Le Top 10 LLM d’OWASP détaille ce risque.

Puis-je utiliser Apidog avec Claude ou GPT directement ?

Oui. Pendant les tests, pointez les définitions d’outils vers l’URL de maquette Apidog via une variable d’environnement. Ensuite, remplacez cette URL par staging ou production selon l’environnement.

Quel est le bon plafond budgétaire pour un agent ?

Commencez strict, puis ajustez avec les métriques. Par exemple :

• 50 000 jetons par session ;
• 30 appels API par minute ;
• 5 dollars par tâche ;
• 10 appels d’outils imbriqués.

Surveillez deux semaines, augmentez les limites réellement atteintes et baissez celles qui ne le sont jamais.

Comment détecter une dérive de schéma entre les outils de mon agent et mon API ?

Comparez en CI la définition JSON de l’outil avec le schéma OpenAPI du point de terminaison correspondant. Faites échouer le build en cas de divergence. L’extrait Python plus haut fournit une base simple à intégrer dans GitHub Actions ou GitLab CI.