Notion a publié discrètement le guide de design de son outil en ligne de commande, ntn. Ce n'est pas un communiqué de presse. Ce n'est pas une annonce produit. C'est un document interne de quelques pages, rédigé pour les ingénieurs qui construisent cet outil.
Et pourtant, il contient une des phrases les plus importantes que j'ai lues cette année sur l'avenir des logiciels :
"We build for two audiences from the start: humans in a terminal and programs that invoke the CLI as a subprocess. The non-TTY case covers shell scripts, CI pipelines, and AI agents."
Traduction directe : Notion conçoit son outil de ligne de commande en considérant les agents IA comme une audience de première classe. Pas comme une intégration future. Pas comme un cas d'usage avancé. Comme un utilisateur à part entière, dès le départ, au même niveau que l'humain.
C'est ça, l'agent-first. Et ce document explique, mieux que n'importe quel article de fond, pourquoi ce changement est fondamental, et irréversible.
Depuis que les interfaces graphiques existent, le design de tout logiciel part d'une question implicite : que voit l'humain ? La forme suit l'usage humain. Les boutons, les menus, les formulaires, les messages d'erreur : tout est conçu pour être lu, interprété et actionné par un cerveau humain.
L'agent-first inverse ce point de départ. La question devient : que voit la machine ?
Un agent IA n'est pas un utilisateur comme les autres. Il ne lit pas la documentation pour comprendre comment utiliser un outil. Il ne tolère pas les ambiguïtés. Il ne peut pas cliquer sur "Confirmer" dans une fenêtre modale, résoudre un CAPTCHA, ou appeler le support si quelque chose ne va pas. Il exécute dans une boucle autonome (action, résultat, décision, action suivante) sans humain entre chaque étape.
Cette contrainte semble technique. Elle ne l'est pas. Elle est profondément une question de design.
Voici la phrase clé du guide Notion, celle qui résume tout :
"A CLI that is good for humans is good for agents, and a CLI that is good for agents is good for humans."
Ce n'est pas une coïncidence bienveillante. C'est une propriété structurelle. Les contraintes qu'imposent les agents révèlent les imperfections de design qui existaient déjà. Un outil ambigu pour un agent était déjà ambigu pour un développeur. Un message d'erreur inutilisable pour un agent était déjà frustrant pour un humain. L'agent ne dégrade pas le design, il l'ausculte.
Le guide de design ntn n'est pas une liste de préférences esthétiques. C'est une architecture de décision. Chaque principe répond à la même question : comment ce choix sert-il à la fois l'humain et l'agent ?
Imaginez un outil qui, quand vous lui demandez une liste de fichiers, vous retourne en même temps les fichiers et le message "Opération réussie !" mélangés dans la même réponse. Pour un humain, c'est lisible : il fait le tri naturellement. Pour un agent, c'est un problème : il reçoit un bloc de texte hétérogène qu'il doit déchiffrer avant de pouvoir utiliser quoi que ce soit.
Le guide Notion tranche clairement : les données d'un côté, les messages de l'autre. Toujours. Ce qui est résultat reste propre et exploitable. Ce qui est commentaire (confirmation, avertissement, indicateur de progression) ne vient pas polluer la réponse.
Pour l'humain, c'est plus clair. Pour l'agent, c'est la condition de base pour fonctionner.
Un outil conçu en agent-first ne retourne pas du texte brut. Il propose plusieurs formats de sortie selon qui le consomme : une présentation lisible pour l'humain dans son terminal, et un format structuré, typiquement du JSON, pour les programmes et les agents.
La différence est fondamentale. Du texte libre, ça se lit. Du JSON, ça se traite. Un agent qui reçoit une réponse structurée peut l'utiliser directement, la passer à l'étape suivante, la croiser avec d'autres données. Un agent qui reçoit du texte doit d'abord l'interpréter, et l'interprétation introduit des erreurs.
Ce n'est pas un détail technique. C'est la frontière entre un outil qu'un agent peut orchestrer et un outil qu'il ne peut pas utiliser.
Un agent ne peut pas cliquer sur un bouton. Il ne peut pas répondre à une fenêtre de confirmation. Il ne peut pas se connecter via un navigateur. Si un outil exige ces interactions pour fonctionner, il est tout simplement hors de portée pour un agent, peu importe à quel point il est puissant par ailleurs.
Le guide Notion en fait une règle absolue : chaque fonctionnalité qui demande une action humaine doit avoir un chemin alternatif qui n'en demande pas. La connexion peut se faire via des variables d'environnement. La confirmation peut être passée en paramètre. Le choix de workspace peut être précisé à l'avance.
Mieux encore : l'outil détecte automatiquement dans quel contexte il s'exécute. Si c'est un humain, il propose l'interface habituelle. Si c'est un agent ou un script, il bascule seul sur le chemin non-interactif. L'utilisateur, humain ou machine, n'a rien à configurer.
Voici la différence entre une erreur traditionnelle et une erreur agent-first :
# Erreur traditionnelle
Error 401: Unauthorized
# Erreur agent-first
error: No auth token found for the current workspace.
hint: Run `ntn login` first, or set NOTION_API_TOKEN.La première réponse bloque tout traitement automatique. La seconde permet à un agent de décider : est-ce que j'ai le token dans mon contexte ? Je peux le configurer et réessayer. Sinon, j'escalade à l'humain.
Le guide va plus loin : chaque type d'erreur doit avoir un code de sortie sémantique. Code 4 pour un échec d'authentification, code 5 pour une erreur réseau. Un agent qui orchestre plusieurs outils peut alors brancher sa logique sur le type d'échec, pas seulement sur le fait qu'il y a eu un échec. Sans cette distinction, l'agent doit parser le message texte pour prendre cette décision, et le parsing de texte libre est une source d'erreurs.
Le guide Notion formule un principe qu'il appelle progressive disclosure, et il le connecte explicitement aux agents :
"Don't overwhelm the user with docs. Make docs discoverable. This is good for humans, and it is good for token-efficiency and roaming RAG with agents."
L'aide courte affiche l'essentiel. L'aide complète ajoute les détails. Les commandes avancées sont cachées par défaut mais pleinement fonctionnelles. L'arbre de commandes est prévisible : si une commande existe pour les workers, elle existe probablement aussi pour les fichiers.
Pour un humain, c'est de la bonne UX. Pour un agent, c'est de l'économie de tokens : il peut explorer l'outil par inférence sans télécharger 50 pages de documentation avant de commencer.
Le guide Notion cristallise une tendance qui s'est construite sur plusieurs années et qui atteint son point de bascule maintenant.
Les LLMs ont résolu le problème de compréhension. Pendant longtemps, les agents automatisés ne pouvaient pas interpréter des contextes ambigus, adapter leur comportement à des situations imprévues, ou raisonner sur une erreur pour décider de la prochaine action. Ce problème est résolu. Un agent propulsé par un modèle de dernière génération peut lire une description d'outil, comprendre une instruction en langage naturel, décider quelle action entreprendre.
Les protocoles standard ont émergé. Anthropic a publié le Model Context Protocol (MCP) fin 2024 : un standard ouvert qui définit comment un modèle IA se connecte à des outils et des sources de données externes. Un serveur MCP = compatible avec tout système qui implémente le protocole. Google a complété le tableau avec le protocole Agent2Agent (A2A) pour la communication entre agents. Pour la première fois, il existe une infrastructure commune. J'ai d'ailleurs détaillé les implications concrètes de cette mutation dans mon article sur WebMCP et l'architecture agent-ready.
L'économie rend le changement inévitable. OpenAI a documenté en production ce que donne un workflow entièrement agent-first : trois ingénieurs, un million de lignes de code, cinq mois, zéro ligne écrite à la main. Une multiplication par dix de la vélocité. Ce n'est pas une promesse marketing : c'est un résultat publié avec les détails de l'architecture. Quand les gains économiques sont de cet ordre, le marché bascule.
Ces trois facteurs réunis créent une pression irréversible. Ils ne se présentent pas séparément : ils convergent maintenant, simultanément.
Stripe illustre parfaitement ce que l'agent-first signifie en dehors du monde du CLI.
Stripe a passé quinze ans à construire des APIs développeur-friendly. Des centaines d'endpoints, une documentation exhaustive, des SDK dans tous les langages. Puis, début 2024, ils ont publié le Stripe Agent Toolkit : un ensemble d'intégrations officielles qui expose les capacités de Stripe aux agents IA.
Ce qu'ils ont curé est aussi important que ce qu'ils ont exposé. Sur des centaines d'endpoints, le toolkit en sélectionne 15 à 20 : créer un lien de paiement, récupérer l'historique d'un client, émettre un remboursement, mettre à jour un abonnement. Les opérations qui ont du sens pour un agent autonome.
Trois décisions de Stripe méritent attention :
L'idempotence par défaut. Stripe impose des clés d'idempotence sur toutes les mutations depuis toujours. Pour un agent qui peut réessayer une requête échouée, c'est critique : sans idempotence, un retry provoque un double-paiement. Ce n'était pas conçu pour les agents, mais ça les sert parfaitement.
Les erreurs lisibles par des LLMs. "No such customer: 'cus_abc123'" est une erreur qu'un agent peut traiter. Il peut raisonner : le customer_id est invalide, je dois d'abord chercher le bon ID. Un code 400 générique ne lui permet pas ce raisonnement.
La granularité des permissions. Le toolkit permet aux développeurs de contrôler exactement quelles opérations un agent peut utiliser. Pas "accès à Stripe", mais "accès à ces 5 opérations spécifiques". Cette granularité n'est pas seulement une bonne pratique de sécurité. C'est ce qui permet de donner aux agents une autonomie réelle sans risque incontrôlé.
La leçon de Stripe : l'agent-first n'exige pas de reconstruire votre infrastructure. L'API de Stripe n'a pas changé. Ce qui a changé, c'est la couche d'interface : la façon dont les capacités sont exposées, décrites, et bornées pour un usage autonome.
L'agent-first n'est pas réservé aux équipes d'ingénierie qui construisent des CLIs ou des APIs. Il redéfinit des responsabilités à tous les niveaux.
Pour ceux qui construisent des produits. Votre API n'est plus seulement une interface pour des développeurs humains. C'est une surface que des agents vont appeler, souvent sans supervision directe. Chaque endpoint, chaque message d'erreur, chaque format de réponse doit être pensé avec cette audience en tête. La question n'est plus "mon API est-elle RESTful ?" mais "un agent peut-il utiliser mon API de façon fiable ?"
Pour ceux qui utilisent des outils. La question pratique qui émerge est simple et radicale : les outils de votre stack quotidien sont-ils agents-compatibles ? Votre CRM expose-t-il un serveur MCP ? Votre outil d'analytics retourne-t-il du JSON structuré ? Les outils qui n'ont qu'une interface web (sans API structurée, sans output machine-lisible) deviennent des goulots d'étranglement dans un workflow agentique. L'humain redevient le pont entre l'agent et l'outil. C'est exactement ce que j'observe dans ma propre pratique, documentée dans mon article sur le marketing OS et les agents autonomes.
Pour les architectes de systèmes. Le changement le plus profond est celui-ci : on passe des workflows aux négociations. Dans un workflow traditionnel, chaque étape a un contrat fixe : input, process, output. Dans un système agentique, les composants ne s'appellent plus avec des API statiques : ils communiquent des intentions. Les workflows ne sont plus pré-codés. Ils sont émergents. Ce n'est plus une question d'automatisation. C'est une question d'architecture du comportement.
Cette mutation touche aussi la façon dont votre expertise est référencée par les LLMs. Si vos contenus ne sont pas structurés pour être compris par des agents, ils n'existent pas dans leurs réponses. J'ai détaillé cette mécanique dans mon article sur l'architecture de la citabilité.
Notion a publié un guide de design CLI. En surface, c'est un document technique pour des ingénieurs. En profondeur, c'est une déclaration de principe sur l'avenir des logiciels : les agents IA sont des utilisateurs légitimes de nos outils, et nos outils doivent être conçus en conséquence.
Ce n'est pas une direction que certaines entreprises vont prendre. C'est une direction que l'économie et les standards vont imposer à toutes.
La question n'est pas "est-ce que je dois m'intéresser à l'agent-first ?" Elle est : mes outils, mes produits, mes systèmes seront-ils de ceux que les agents peuvent utiliser, ou de ceux qu'ils vont contourner ?
Le guide Notion a une réponse claire pour ceux qui construisent :
"Make simple things simple. Make complex things discoverable and memorable."
C'est valable pour les humains. C'est valable pour les agents. Et c'est valable dès maintenant.
Sources : Notion ntn Design Guidelines · OpenAI Harness Engineering · Stripe Agent Toolkit · Model Context Protocol