agentHints : Apprendre aux CLIs à communiquer avec les agents

Il s'agit d'une série en 10 parties expliquant comment Apidog a développé Apidog CLI, un outil en ligne de commande pour les tests d'API et la gestion du cycle de vie des API. Lisez dans l'ordre ou accédez à n'importe quel article qui vous intéresse :

La sortie CLI traditionnelle est destinée aux humains. Les Agents ont besoin de résultats structurés, des raisons d'échec et des suggestions d'étapes suivantes. agentHints transforme l'expérience produit en des directives lisibles par machine.

Le fossé de la sortie CLI

La sortie CLI traditionnelle est conçue pour les humains.

Cela fonctionne pour les personnes. Les humains peuvent :

• Interpréter les messages vagues
• Décider quoi faire ensuite
• Se souvenir du contexte des commandes précédentes
• Appliquer des connaissances spécifiques au domaine pour continuer

Mais les Agents fonctionnent différemment.

Ce dont les Agents ont réellement besoin

Les Agents ne se contentent pas de lire les résultats. Ils doivent relier les résultats à la prochaine chaîne de tâches.

Un humain voit "Ressource créée avec succès" et sait : "Je devrais probablement vérifier ce qui a été créé, puis peut-être exécuter des tests."

Un Agent voit "Ressource créée avec succès" et... n'a aucune idée de ce qu'il doit faire ensuite.

agentHints : La solution

Apidog CLI ajoute agentHints à sa sortie.

Voici à quoi ressemble une réponse typique :

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Test case created successfully.",
    "nextSteps": [
      "Read the created test case back to confirm structure.",
      "Add assertions if the test case needs response validation.",
      "Add the test case to a test scenario for integration testing.",
      "Run related tests after adding to scenario."
    ]
  }
}

Trois composants :

Le problème de l'inertie d'exécution

Voici un problème réel que nous avons observé :

Après avoir créé une ressource avec succès, le modèle continue souvent directement à générer la prochaine écriture.

Exemple :

Agent: Creates test case
CLI: Returns success
Agent: Immediately creates test scenario (without reading back)
Agent: Immediately runs tests
Result: Scenario has wrong structure, tests fail

Dans les processus métier complexes, l'exécution continue mécanique n'est pas appropriée.

L'approche la plus correcte est souvent :

1. Créer la ressource
2. Relire d'abord
3. Confirmer la structure
4. Puis procéder

Pourquoi la relecture est importante

Ignorer la relecture cause de réels problèmes :

Si la structure réelle n'est pas relue, l'Agent continue facilement d'écrire en se basant sur sa propre supposition, et non sur des données réelles.

agentHints comme navigateur

agentHints transforme l'expérience produit en suggestions d'étapes suivantes lisibles par machine.

Il apparaît exactement là où l'Agent doit prendre des décisions.

Exemple après la création d'un cas de test :

{
  "agentHints": {
    "nextSteps": [
      "Read back the created test case with --with-case-detail flag.",
      "Validate any updates with cli-schema before writing.",
      "Run tests after completing test scenario."
    ]
  }
}

L'Agent :

1. Lit la sortie
2. Analyse agentHints
3. Suit nextSteps[0] : relit le cas de test
4. Confirme la structure réelle
5. Puis procède avec des informations précises

Transformation du rôle du CLI

Cela modifie la signification du CLI dans le flux de travail de l'Agent.

Le CLI devient un navigateur d'état léger.

Arbres de flux de travail intégrés

Apidog CLI intègre des milliers de flux de travail structurés en arbre.

Ce ne sont pas seulement des suggestions codées en dur. Elles sont :

Exemple après une mise à jour réussie du scénario de test :

{
  "agentHints": {
    "summary": "Test scenario updated successfully.",
    "nextSteps": [
      "Run the test scenario to verify changes.",
      "Check the test report for any failures.",
      "If failures occur, read back scenario steps for debugging."
    ]
  }
}

Exemple après un échec de validation :

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": [...]
  },
  "agentHints": {
    "summary": "Validation failed. Fix the errors and re-validate.",
    "nextSteps": [
      "Review the error details in the output.",
      "Adjust the JSON file based on error suggestions.",
      "Re-run cli-schema validate before writing."
    ]
  }
}

Même les échecs deviennent navigables.

La boucle plus sûre avec agentHints

Traçons un flux de travail complet avec agentHints :

Step 1: Agent creates test case
        ↓
CLI Output: success + agentHints
        ↓
agentHints.nextSteps[0]: "Read back the created test case"
        ↓
Step 2: Agent reads back (with actual structure)
        ↓
CLI Output: test case structure + agentHints
        ↓
agentHints.nextSteps[0]: "Add assertions if needed"
        ↓
Step 3: Agent adds assertions (based on actual structure)
        ↓
CLI Output: success + agentHints
        ↓
agentHints.nextSteps[0]: "Run tests"
        ↓
Step 4: Agent runs tests
        ↓
CLI Output: test report

Chaque étape est guidée. Pas de sauts à l'aveugle. Pas d'hypothèses.

Comparaison : Avec et sans agentHints

Et ensuite ?

Maintenant que le CLI peut guider les Agents à travers les étapes suivantes, la question restante est :

Comment les Agents savent-ils quel flux de travail suivre en premier lieu ?

Dans la Partie 5, SKILL : Livrer l'expérience opérationnelle sous forme de code, nous explorerons comment SKILL encapsule les connaissances de flux de travail – quand utiliser les commandes, quelle séquence suivre, et quels champs ne devraient pas être devinés.

Points clés à retenir

• La sortie CLI traditionnelle est orientée vers l'humain ; les Agents ont besoin de directives structurées
• agentHints fournit un résumé + des suggestions d'étapes suivantes dans la sortie JSON
• L'inertie d'exécution pousse les Agents à ignorer la relecture ; agentHints empêche cela
• Le CLI se transforme d'exécuteur en navigateur
• Les arbres de flux de travail intégrés rendent chaque étape navigable
• Même les échecs deviennent exploitables avec agentHints

Téléchargez Apidog pour concevoir, simuler, tester et documenter les API dans un seul espace de travail. En savoir plus sur Apidog CLI pour les tests d'API en ligne de commande, l'automatisation CI et les flux de travail des Agents IA.

bouton