Conception d’un AI Agent CLI : JSON, codes de sortie et attente
La conception d’un AI Agent CLI nécessite un JSON structuré, de vrais codes de sortie, une attente jusqu’à l’état final, des erreurs stables et une confirmation sécurisée pour l’automatisation en production.
Un AI agent CLI n’est pas simplement un outil en ligne de commande destiné aux humains qui peut aussi être appelé depuis un modèle. Il s’agit d’un protocole opérationnel. L’agent a besoin d’entrées déterministes, de sorties structurées, de codes de sortie pertinents, de catégories d’erreurs stables et d’un moyen d’attendre que l’infrastructure asynchrone atteigne un état final.
Sans ce contrat, l’agent est contraint de déduire la réussite à partir d’un texte tel que « déploiement démarré ». Cette déduction est dangereuse, car une requête acceptée peut ensuite échouer pendant le build, les health checks, le démarrage du conteneur ou le basculement du trafic.
Pourquoi est-il dangereux de supposer qu’un déploiement a réussi ?
La plupart des opérations d’infrastructure sont asynchrones. Une API peut accepter un déploiement et renvoyer un identifiant en quelques millisecondes, alors que le build réel prend plusieurs minutes. Si un agent signale la réussite au moment de l’acceptation, toutes les étapes suivantes reposent sur une prémisse fausse.
Voici la différence :
| Événement | Ce que cela prouve | Ce que cela ne prouve pas |
|---|---|---|
| Requête acceptée | La plateforme a compris la requête | Le code a été buildé |
| Build terminé | Une image ou un artefact a été créé | L’application a démarré |
| Health gate validé | La nouvelle instance a répondu comme prévu | Les parcours métier fonctionnent |
| Trafic basculé | La release est devenue active | Elle restera saine |
| Observation de l’uptime | Le service reste accessible | Chaque fonctionnalité est correcte |
Un humain peut remarquer cette distinction dans un dashboard. Un agent qui opère au moyen de texte a besoin qu’elle soit encodée dans l’interface.
Le contrat de commandes de Dockup sépare la mise en file d’attente de l’exécution complète. Un déploiement sans --wait revient immédiatement avec waited:false ; un déploiement avec --wait se bloque jusqu’à la réussite, l’échec ou l’expiration du délai :
dockup deploy production/api --wait --json
Le timeout par défaut est de 900 secondes. La commande se termine avec 0 uniquement après avoir atteint un état final réussi. Elle renvoie un code différent de zéro avec deploy_failed ou deploy_timeout lorsque le résultat n’est pas une réussite.
Que fournit un CLI JSON structuré à un agent IA ?
Le JSON structuré remplace l’interprétation de texte par des champs nommés. L’agent peut accéder directement à status, deploymentId, target ou code, sans dépendre de la ponctuation, des couleurs, de la largeur des colonnes ou de la formulation.
Un résultat réussi peut être consommé comme une donnée :
{
"ok": true,
"target": "production/api",
"deploymentId": "dep_123",
"waited": true,
"status": "success",
"durationMs": 142381,
"url": "https://api.dockup.tech"
}
Une erreur utilise la même structure de transport :
{
"ok": false,
"error": "Deployment failed",
"code": "deploy_failed"
}
La règle de conception essentielle est que le JSON est écrit sur stdout, tandis que les avertissements qui ne doivent pas corrompre l’analyse sont envoyés sur stderr. Les logs en mode follow utilisent le NDJSON — un objet JSON par ligne — afin qu’un appelant puisse traiter progressivement un flux sans attendre un tableau géant.
Dockup applique --json à l’ensemble de ses commandes. Avec 135 commandes, demander à un agent de déduire les flags à partir de sa mémoire serait fragile. La référence du CLI et la skill fournie contiennent les instructions de commande alignées sur la version utilisée.
La propriété de conception importante n’est pas une découverte ingénieuse. C’est le fait que l’agent reçoit des instructions opérationnelles à jour et structurées, au lieu d’inventer un flag à partir d’un ancien prompt.
Comment les vrais codes de sortie contrôlent-ils l’automatisation des déploiements ?
Le code de sortie du système d’exploitation est le signal de réussite le plus portable pour les shell scripts, les runners CI et les coding agents. Le code 0 signifie que la commande a obtenu le résultat qui lui était défini. Un code différent de zéro signifie que l’appelant doit passer à une branche de récupération, d’escalade ou d’arrêt.
Cet extrait shell est volontairement sans artifice :
if dockup deploy production/api --wait --json > result.json; then
echo "deployment reached success"
else
dockup logs production/api --build --json
exit 1
fi
Il ne recherche pas le mot « success » dans stdout. Il ne suppose pas qu’une réponse HTTP 202 signifie que la production est prête. Il délègue la définition de la réussite au CLI et transmet l’échec au processus parent.
Les vrais codes de sortie sont tout aussi importants pour les commandes exécutées une seule fois dans un conteneur. La commande PRO exec de Dockup renvoie stdout, stderr et le véritable code de sortie de la commande :
dockup exec "npm run migrate" \
-s production/api \
--json
Un agent peut ainsi faire la différence entre une migration terminée et une commande qui s’est simplement lancée. Il s’agit d’un principe fondamental des garde-fous de production pour les agents IA.
Comment l’attente d’un état final remplace-t-elle un polling fragile ?
Les boucles de polling écrites manuellement introduisent des choix de politique implicites : à quelle fréquence interroger le service, quels états sont finaux, combien de temps attendre, si une erreur réseau transitoire doit réinitialiser le délai et que faire lorsqu’un conteneur redémarre.
Un agent risque tout particulièrement de prendre de mauvaises décisions, car il ne connaît peut-être pas la machine à états complète de la plateforme. La plateforme doit gérer elle-même la sémantique d’attente.
Dockup propose deux patterns utiles :
dockup deploy production/api --wait --timeout 1800 --json
dockup push --json
deploy --wait attend explicitement. push attend par défaut après le push et le déclenchement de la release ; --no-wait permet de désactiver ce comportement. Les deux commandes renvoient un code de sortie qui reflète le résultat final.
Le suivi des logs suit le même principe :
dockup logs production/api --build -f --json
Le flux se termine lorsque le build atteint l’état de réussite ou d’échec. Un objet NDJSON final indique done:true, et un build échoué se termine avec un code différent de zéro. L’appelant n’a pas besoin d’implémenter une seconde logique de polling.
Pour vérifier la disponibilité de l’application après un déploiement, la commande uptime de Dockup renvoie des checks à la minute, le temps de réponse moyen et le p95 :
dockup uptime production/api --hours 24 --json
L’attente et la supervision sont deux concepts distincts. --wait indique si ce déploiement a atteint un résultat final ; uptime indique comment le service en fonctionnement s’est comporté au fil du temps.
Quels codes d’erreur un agent doit-il comprendre ?
Des catégories d’erreur stables permettent à un agent d’effectuer une action limitée sans interpréter chaque message possible. Dockup expose notamment les codes suivants :
| Code d’erreur | Signification | Réponse sûre de l’agent |
|---|---|---|
not_logged_in | Aucun token utilisable | S’arrêter et demander une authentification |
not_linked | Aucune cible .dockup pour push | Résoudre la cible ou la transmettre |
no_target | Le service n’a pas pu être identifié | Exécuter services --json |
needs_confirm | Une action destructive ne dispose pas de l’approbation requise | Demander à un humain |
deploy_trigger_failed | Le déploiement n’a pas pu démarrer | Signaler l’erreur de l’API |
deploy_failed | Le build ou le déploiement a échoué | Consulter les logs du build |
deploy_timeout | L’opération est toujours en cours après la limite d’attente | Signaler l’incertitude ou prolonger délibérément l’attente |
Le message d’erreur reste utile comme contexte, mais c’est le code qui détermine la première branche. L’automatisation résiste ainsi à une formulation plus claire ou à une localisation.
La confirmation fait également partie du protocole. Une commande destructive ne doit pas s’exécuter silencieusement parce que l’appelant est non interactif. Dockup refuse ces opérations sans --yes et renvoie needs_confirm. Un agent autonome voit une demande de confirmation, et non une barrière à contourner.
Le modèle de sécurité est approfondi dans les bonnes pratiques de sécurité.
Quel est le contrat minimal d’un CLI prêt pour la production ?
Un AI agent CLI prêt pour la production doit respecter un contrat concis mais strict :
- Toute opération de lecture ou d’écriture dispose d’une sortie lisible par une machine.
- Un échec produit une terminaison de processus avec un code différent de zéro.
- Les mutations asynchrones peuvent attendre un état final documenté.
- Les valeurs secrètes ne sont jamais renvoyées par les commandes de lecture.
- Les actions destructives nécessitent une confirmation explicite.
- Les erreurs disposent de codes stables adaptés au branching.
- Le package du CLI et les instructions destinées à l’agent restent alignés sur la même version.
- Les mutations sont consignées dans un audit trail.
La skill de Dockup transforme ces règles en comportement par défaut pour Claude Code et Codex. Elle indique à l’agent d’utiliser JSON, de s’authentifier avec DOCKUP_TOKEN, de découvrir les cibles exactes, de déployer avec --wait, de protéger les credentials et de s’arrêter sur needs_confirm.
Comparez ce modèle aux concepts plus larges présentés dans agent skills vs MCP. Une skill fournit les connaissances opérationnelles ; le CLI reste l’interface exécutable dont le statut de sortie et la sortie définissent la réalité.
Une matrice de tests pour une commande destinée aux agents
Avant d’exposer une commande d’infrastructure à un agent, testez davantage que le happy path :
| Test | Comportement attendu |
|---|---|
| Requête valide | Résultat JSON et code de sortie 0 |
| Token invalide | Code d’authentification stable et code de sortie différent de zéro |
| Cible inconnue | Code de cible stable et aucune mutation |
| Déploiement long | Attend l’état final ou l’expiration du délai |
| Déploiement échoué | Code de sortie différent de zéro et ID de déploiement permettant le diagnostic |
| Approbation destructive manquante | needs_confirm, aucune suppression |
| Lecture d’un secret | Métadonnées de la clé visibles, valeur masquée |
| Avertissement pendant une sortie JSON | Avertissement sur stderr, JSON valide sur stdout |
Cette matrice a davantage de valeur qu’un progress spinner élégant. La mise en forme destinée aux humains peut être ajoutée par-dessus ; un contrat machine déterministe ne peut pas être reconstitué après coup.
La documentation du CLI Dockup présente les commandes concrètes qui sous-tendent ce modèle, tandis que le sujet du développement assisté par l’IA explique le changement plus large qui mène de l’utilisation manuelle des outils aux workflows pilotés par des agents.
Considérer l’observabilité comme une partie du contrat de commande
Une mutation destinée à un agent doit renvoyer des identifiants permettant les investigations ultérieures. Une réponse de déploiement doit contenir la cible et l’ID de déploiement ; une base de données créée doit disposer d’un slug stable ; un snapshot de volume doit avoir son ID de snapshot. Sans ces références, l’agent peut décrire un événement, mais il ne peut pas l’inspecter, le relancer ou l’annuler de manière fiable.
L’audit trail complète le contrat. La sortie structurée décrit une invocation, tandis que les enregistrements d’audit relient plusieurs invocations au fil du temps. Ensemble, ils permettent aux opérateurs de déterminer si l’agent a agi sur la ressource prévue et si une commande de récupération ultérieure faisait référence au même événement de production.
Garder une interface sans surprise
Un AI agent CLI fiable doit se comporter de manière prévisible en cas de réussite, d’échec, d’expiration du délai et de nouvelle tentative.
Test final de l’interface
L’AI agent CLI doit échouer de manière fidèle à la réalité.
Mettre le workflow en production
Commencez par tester le contrat depuis un shell : vérifiez l’analyse du JSON, une terminaison réussie, un échec forcé, une expiration du délai et une opération destructive bloquée avant de déléguer l’accès à la production.
npm install -g dockup-cli
dockup skill install
La première commande installe le CLI. La seconde installe la skill Dockup correspondante pour Claude Code et Codex. Commencez gratuitement sur app.dockup.ai.
FAQ
Qu’est-ce qui rend un CLI adapté aux agents IA ?
Il lui faut une sortie structurée, de vrais codes de sortie, une attente jusqu’à l’état final, des codes d’erreur stables, le masquage des secrets et une confirmation explicite pour les opérations destructives.
Pourquoi le JSON est-il préférable à une sortie de CLI formatée pour les humains lorsqu’elle est destinée aux agents ?
Le JSON fournit des noms et des types de champs stables. L’agent n’a pas à déduire le sens à partir des couleurs, des tableaux, de la ponctuation ou d’un texte susceptible de changer.
Pourquoi une requête de déploiement acceptée n’est-elle pas synonyme de réussite ?
L’acceptation prouve uniquement que la plateforme a placé l’opération en file d’attente. Le build, le démarrage, le health gate et le basculement du trafic peuvent encore échouer.
Quel est le délai d’attente par défaut d’un déploiement Dockup ?
Le délai par défaut de dockup deploy --wait est de 900 secondes. Il peut être modifié avec l’option --timeout documentée.
Comment un agent doit-il réagir à needs_confirm ?
Il doit s’arrêter et demander une approbation explicite. Ce code signifie que l’action demandée est destructive et qu’elle n’a volontairement pas été exécutée.