Principes de conception CLI agent-first

En mars 2026, Justin Poehnelt — l’ingénieur Google DevRel à l’origine du [[fr/cli-google-workspace-gws|CLI gws]] — a publié « You Need to Rewrite Your CLI for AI Agents ». L’argument central : l’expérience développeur humain optimise pour la découvrabilité et l’indulgence, tandis que l’expérience développeur agent optimise pour la prévisibilité et la défense en profondeur. Les sept principes qu’il articule s’appliquent à tout outil conçu pour une consommation par des agents, pas seulement à gws.

1. Payloads JSON bruts plutôt que des flags ad hoc

Les CLI traditionnels utilisent des espaces de nommage de flags plats : --title "Q1 Budget" --locale "en_US". Cela fonctionne pour des inputs simples mais se casse pour des structures imbriquées — on se retrouve avec des conventions de sérialisation inventées (--filter.key=value --filter.operator=eq) qui ne correspondent pas proprement à l’API sous-jacente.

L’approche agent-first : accepter des payloads d’API complets via des flags --json et --params qui correspondent directement au schéma de l’API. Les LLM peuvent les générer sans perte de traduction parce que la structure JSON est le contrat d’API :

# CLI human-first : flags plats sérialisés vers un appel API
gws drive files create --title "Q1 Budget" --mime-type "application/vnd.google-apps.spreadsheet"

# CLI agent-first : passer directement le payload API
gws drive files create --json '{"name": "Q1 Budget", "mimeType": "application/vnd.google-apps.spreadsheet"}'

L’agent n’a pas besoin d’apprendre les conventions de flags personnalisées du CLI. Il génère le payload API qu’il connaît déjà.

2. Introspection de schéma remplaçant la documentation

Intégrer de la documentation statique dans les system prompts des agents est coûteux en tokens et sujet à la péremption. Quand l’API se met à jour, les docs dans votre prompt sont erronées.

L’alternative : rendre l’outil lui-même interrogeable pour son schéma. gws schema drive.files.list produit les signatures complètes des méthodes en JSON lisible par machine — paramètres, corps de requête, types de réponse, scopes OAuth. Le Discovery Document est la source de vérité unique, et il est toujours à jour.

# L'agent interroge le schéma au moment de la tâche plutôt que de charger des docs périmées au démarrage
gws schema gmail.users.messages.list

Cette approche se connecte à l’observation sur l’asymétrie des données d’entraînement LLM : les agents sont meilleurs avec les outils qu’ils peuvent inspecter dynamiquement qu’avec les outils qu’ils doivent mémoriser.

3. Discipline de fenêtre de contexte

Un seul email Gmail peut consommer une fraction significative de la fenêtre de contexte d’un LLM. Les réponses longues sont coûteuses, et un outil qui retourne des murs de JSON brûlera rapidement le contexte.

Deux mécanismes adressent cela :

Les field masks limitent ce que l’API retourne à ce dont l’agent a besoin uniquement :

# Sans field mask : retourne tous les champs de chaque objet fichier
gws drive files list --params '{"pageSize": 10}'

# Avec field mask : retourne uniquement id, name, mimeType
gws drive files list --params '{"pageSize": 10, "fields": "files(id,name,mimeType)"}'

La pagination NDJSON (--page-all) émet un objet JSON par page plutôt que de bufferiser la réponse entière. Cela rend les grands ensembles de résultats traçables en streaming — l’agent peut traiter et supprimer chaque page plutôt que de tout garder en contexte.

Les deux techniques traitent le contexte comme une ressource rare à préserver, pas un buffer à remplir.

4. Durcissement des inputs contre les hallucinations

Le cadrage de Poehnelt : « Les agents hallucinent. Construisez en conséquence. »

C’est le principe le plus facile à rejeter et le plus important à ne pas rejeter. Quand un agent génère des inputs pour un CLI, il produira parfois des valeurs subtilement incorrectes. La question est de savoir si ces valeurs incorrectes causent une corruption silencieuse des données ou sont interceptées à la couche d’input.

gws valide les inputs avant d’exécuter :

Validation des chemins de fichiers empêche le directory traversal — les agents hallucinent parfois des chemins comme ../../.ssh/authorized_keys
Rejet des caractères de contrôle — rejeter tout ce qui est en dessous d’ASCII 0x20
Injection de paramètres de requête — rejeter ? et # dans les identifiants de ressource (les agents intègrent parfois des paramètres de requête dans des IDs de ressource)
Prévention du double-encodage — rejeter % pour prévenir les problèmes d’encodage URL

Ce ne sont pas des patterns d’attaque hypothétiques. Ce sont des modes de défaillance observés en faisant tourner des agents IA contre de vraies API. La couche de validation est la différence entre un mauvais output qui échoue vite et un mauvais output qui corrompt silencieusement des données.

5. Livrer des skills d’agents, pas seulement des commandes

La sortie --help décrit la syntaxe. Elle n’encode pas la sagesse opérationnelle.

Les skills sont des fichiers Markdown structurés avec du frontmatter YAML — un par surface d’API plus des recettes de workflow de haut niveau — qui disent aux agents ce que le texte d’aide ne dit pas :

« Toujours utiliser --dry-run pour les opérations de mutation »
« Toujours confirmer avec l’utilisateur avant d’exécuter des commandes d’écriture/suppression »
« Lors du listing de fichiers, utiliser des field masks pour éviter les grandes réponses »
« Pour les grandes boîtes mail, paginer plutôt que demander tous les messages à la fois »

Le dépôt en livre 100+. Ils sont chargés dans le contexte de l’agent en même temps que le CLI, so l’agent dispose de conseils opérationnels sans nécessiter un system prompt qui énumère chaque cas limite :

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive

C’est un pattern à emprunter : si vous construisez un outil que des agents utiliseront, livrez les fichiers de skill en même temps que l’outil. Laissez l’agent les charger à la demande plutôt que d’intégrer tout dans un system prompt.

6. Livraison multi-surface

Le même binaire de base devrait fonctionner comme un CLI humain, un serveur MCP, un outil de scripting et une cible d’automatisation headless. Forcer un choix entre ces modes signifie que certains cas d’usage légitimes sont des citoyens de seconde classe.

gws livre :

Mode CLI : utilisation interactive standard en terminal
Mode serveur MCP : gws mcp -s drive,gmail expose Workspace comme des outils structurés via stdio
Extension Gemini CLI : s’enregistre comme outil pour l’agent Gemini
Mode headless/CI : credentials via variables d’environnement, sans prompts interactifs

# Mode MCP pour l'intégration Claude Code
gws mcp -s drive,gmail,calendar

# Mode headless pour usage en pipeline
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json
gws drive files list

La décision de conception clé : ne pas optimiser le CLI pour un consommateur et bricoler le support pour les autres. Concevoir l’interface de base pour fonctionner sur toutes les surfaces, puis ajouter des adaptateurs de protocole spécifiques à la surface.

7. Rails de sécurité

Deux mécanismes de sécurité adressent les modes de défaillance distincts de l’usage CLI piloté par agent :

--dry-run valide les requêtes auprès de l’API sans les exécuter. Les agents devraient utiliser dry-run par défaut pour toute opération de mutation et ne procéder qu’après confirmation de l’utilisateur sur l’action prévue. C’est le conseil « toujours confirmer avant écriture/suppression » des fichiers de skill, rendu mécanique.

--sanitize passe les réponses par Google Cloud Model Armor pour se défendre contre l’injection de prompt intégrée dans les données. Le modèle de menace : un corps d’email malveillant demande à l’agent de transférer tous les messages à un attaquant. Sans sanitisation, un agent lisant des emails via gws gmail et agissant ensuite sur le contenu est vulnérable à exactement cela. Model Armor supprime les patterns d’injection des réponses avant qu’ils n’atteignent le contexte du modèle.

Le flag sanitize est opt-in — il ajoute latence et coût — mais pour tout workflow où l’agent lit des données qu’il n’a pas créées et agit ensuite dessus, il devrait être considéré comme non-optionnel.

Implications de conception

Pour la plupart des CLI, la conception agent-first signifie ajouter ces capacités à un outil existant plutôt que le reconstruire from scratch : un chemin d’input --json en plus des flags, une sous-commande schema, un répertoire de fichiers de skill, une validation des inputs et un flag --dry-run. Rien de tout cela ne nécessite de réécrire l’outil de base. La livraison multi-surface et la pagination NDJSON sont les deux décisions qui requièrent une planification avant la v1.0.