Intégration de l'agent IA, pas de l'humain

Demandez à Claude Code de configurer un SaaS typique pour vous. Il ouvre un navigateur, trouve un formulaire d'inscription qu'il ne peut pas remplir, récupère la documentation, choisit le mauvais chemin d'installation parmi trois options, copie un exemple de configuration obsolète, modifie un fichier dans ~/.config/, vous invite à redémarrer votre éditeur - et ne sait ensuite pas à quoi servent les outils qu'il vient d'enregistrer.

Vingt minutes. Quelques milliers de jetons. Une installation à moitié fonctionnelle.

Le problème n'est pas l'agent. Le problème est que le flux d’intégration a été conçu pour un humain lisant une page Web. Nous avons reconstruit le nôtre à partir de zéro en partant de l’hypothèse inverse : c’est un agent qui gère tout cela, pas un humain. Cet article passe en revue les six changements concrets qui découlent de cette décision.

L'ensemble du flux est une commande, pas une page

Le changement le plus important : il n'y a pas d'étape « allez sur cette page et cliquez sur vous inscrire ». L'ensemble du flux est une seule commande :

npx @agentled/cli setup

L'agent l'exécute dans son propre shell. Bash s'exécute sur la machine de l'utilisateur, de sorte que le navigateur s'ouvre sur la machine de l'utilisateur — l'agent n'a jamais besoin d'afficher du HTML ni de cliquer sur quoi que ce soit. Avec le recul, cela semble évident. Ce n'est pas ainsi que la plupart des SaaS sont intégrés.

Pourquoi c'est important : chaque étape qui nécessite que l'agent « examine » une interface utilisateur est un récepteur de jetons et un mode d'échec. Chaque étape qui constitue une commande shell est une primitive que l'agent connaît déjà. L'humain doit encore faire une chose : se connecter lorsque le navigateur apparaît, mais c'est la seule action que l'agent ne peut pas effectuer lui-même.

Des outils sans playbook signifient un agent confus

Le flux installe deux choses, pas une :

• Le serveur MCP — les outils. create_workflow, add_step, upsert_knowledge_text, start_workflow, le reste.
• La compétence AgentLed — le manuel de jeu. Protocole d'exécution à sec, règles de création incrémentielles, types d'étapes valides, modèles de test efficaces en termes de crédit.

C’est le changement manqué par la plupart des plateformes. Donner des outils à un agent sans playbook, c'est comme déposer un ingénieur junior dans votre base de code avec un accès API et sans README. Ils feront quelque chose. Ce sera cher et probablement faux.

La compétence est automatiquement acheminée vers le bon endroit par client : ~/.claude/skills/agentled/ pour Claude Code ou Claude Desktop, ~/.codex/instructions/agentled/ pour Codex. Les clients sans surface de compétence native (Cursor, Windsurf aujourd'hui) sont ignorés avec un indice, MCP toujours connecté. L'agent acquiert la compétence lors de sa prochaine session et a désormais des opinions sur la façon d'utiliser les outils : quand effectuer un essai à sec avant la publication, quels types d'étapes sont valides pour quel cas d'utilisation, comment tester de manière incrémentielle sans brûler de crédits.

C'est la différence entre un agent qui dispose de plus de 100 intégrations disponibles et un agent qui sait laquelle contacter dès votre première invite.

Créez un dossier de travail, n'obligez pas l'agent à en inventer un

Le flux crée agentled_<workspace-slug>/ dans le répertoire actuel avec des sous-dossiers documentés :

agentled_<workspace-slug>/
  README.md
  worklog.md
  decisions/                 # YYYY-MM-DD-<slug>.md
  workflows/                 # local pipeline JSON drafts
  groups/                    # WorkflowGroup specs
  kg/                        # local mirrors of KG schemas and text drafts
  executions/                # debug bundles for failed runs
  drafts/                    # scratch space

Un dossier par espace de travail, afin qu'un agent jonglant avec deux espaces de travail ne traverse jamais les flux.

Pourquoi c'est important : les agents écriront des artefacts quelque part. Sans convention d'échafaudage, ils dispersent les brouillons et les journaux de travail JSON à la racine du dépôt, les mélangent avec la base de code réelle et les perdent lors de la session suivante. Le dossier est un contrat — "c'est votre espace de travail, voici la structure, le README explique la règle de synchronisation." L'agent lit le fichier README au démarrage de la session et s'insère dans la convention.

Bonus : les dossiers par espace de travail signifient qu'un agent qui a travaillé sur l'espace de travail A et qui est interrogé sur l'espace de travail B n'a pas à deviner quel journal de décisions s'applique. Il regarde agentled_<active-workspace>/ et c'est la source de la vérité.

Une enquête de connaissances au lieu d'un formulaire « décrivez votre entreprise »

La sixième étape du flux lit knowledge.company.profile à partir du graphique de connaissances de l'espace de travail. S'il est défini, il imprime un résumé d'une ligne et continue. S'il est manquant, il demande une fois à l'utilisateur le nom de l'entreprise, le site Web et le cas d'utilisation, puis réécrit le profil détaillé sur la même clé via upsert_knowledge_text.

C’est là que la plupart des flux d’intégration se trompent deux fois :

• Ils ignorent complètement l'étape "Parlez-nous de votre entreprise" - et chaque flux de travail ultérieur doit ensuite l'obtenir à nouveau auprès de l'utilisateur, au milieu d'un travail sans rapport.
• Ou bien ils le demandent sous forme de formulaire d'inscription - et la réponse meurt dans un onglet "Paramètres de l'entreprise" auquel l'agent ne peut pas accéder.

Le stocker en tant que clé de graphe de connaissances connue signifie que chaque flux de travail que l'agent crée pour cet espace de travail peut lire le même contexte canonique. ICP, ton, intégrations qui intéressent l'équipe, marché cible – tout est là, structuré, interrogeable. La prochaine fois que l'agent rédige une séquence de sensibilisation, il n'a pas besoin de demander à nouveau à l'utilisateur ce que fait son entreprise.

La sonde est idempotente : elle lit ce que l'invite écrit, de sorte que la question ne se relance jamais lors des exécutions suivantes. Réexécuter la configuration trois fois ne signifie pas répondre trois fois au même questionnaire.

Informez l'agent du redémarrage, pas l'utilisateur

La dernière étape du flux imprime quelque chose comme : "Redémarrez votre client MCP pour récupérer cet espace de travail." L'agent lit ce résultat, le comprend et le présente explicitement à l'utilisateur : "Vous devez redémarrer Claude Code (reconnexion /mcp ou nouvelle session) avant que les nouveaux outils n'apparaissent."

L'utilisateur n'a pas besoin de remarquer l'absence des outils MCP et de comprendre pourquoi par lui-même.

Petite chose. Énorme delta UX. Le mode d'échec par défaut de chaque installation de MCP est "J'ai exécuté le truc, pourquoi ne vois-je pas les outils ?" - résolu en indiquant à l'agent en texte brut la sortie standard et en lui faisant confiance pour le relais.

Idempotent et version vérifiée, car l'agent sera réexécuté

La première étape du flux est une vérification de version qui avertit si la CLI est obsolète. L'ensemble du flux est idempotent : l'exécuter deux fois ne demande pas à nouveau les informations sur l'entreprise, n'encombre pas la configuration MCP, ne réinitialise pas l'authentification.

L'agent peut l'exécuter à chaque fois qu'il soupçonne que quelque chose ne va pas. Ceci est important car l'agent réexécutera souvent l'installation de manière défensive - c'est l'étape de débogage la moins chère. Un script d'installation non idempotent punit cet instinct et entraîne l'agent à éviter une nouvelle exécution, ce qui est le contraire de ce que vous souhaitez.

Le modèle : chaque hypothèse "un humain lit ceci" est remplacée

Six équipes. Un modèle commun à tous : chaque hypothèse selon laquelle « un humain lit ceci » est remplacée par « un agent exécute ceci ».

• Une seule commande, pas une page.
• Outils livrés avec leur propre playbook.
• Un dossier de travail avec un README que l'agent lit au démarrage.
• Contexte métier en tant que clé interrogeable, pas en tant qu'onglet de paramètres.
• Redémarrez les instructions dans la sortie standard, pas une bannière de notification.
• Idempotent, car l'agent va réessayer.

Aucune de ces fonctionnalités n’est une fonctionnalité d’IA. Ce sont des changements de superficie. Mais la différence entre un agent qui obtient votre produit en 30 secondes et un autre qui abandonne après avoir brûlé 0,40 $ en jetons est exactement l'écart entre ces six agents et un assistant d'inscription traditionnel.

L'utilisateur a toujours un travail, juste un plus petit

Pour être clair : l’utilisateur n’est pas parti. L'utilisateur se connecte toujours lorsque le navigateur apparaît et décrit toujours son entreprise dans un anglais simple la première fois que la sonde de connaissances se déclenche.

C'est toute la surface humaine. Tout le reste - installer la CLI, câbler le serveur MCP dans le bon fichier de configuration pour l'éditeur détecté, échafauder le dossier de l'espace de travail, écrire le profil d'entreprise dans le graphe de connaissances, dire à l'utilisateur de redémarrer - est le travail de l'agent, car l'agent est celui qui a un accès au shell et une fenêtre contextuelle. Le travail du flux est de permettre à l'agent de faire tout cela facilement sans rien inventer.

Essayez-le

Ouvrez Claude Code, Codex ou Cursor. Dites à votre agent :

Run npx @agentled/cli setup and then build me a workflow that scores
my last 50 inbound leads against our ICP.

C'est toute l'intégration. L'agent installe, authentifie, connecte MCP, apprend son playbook, écrit le profil de votre entreprise dans le graphique de connaissances de l'espace de travail, vous demande une entrée de test, exécute le flux de travail à sec, vous montre le résultat et itère jusqu'à ce que le résultat corresponde à ce que vous souhaitiez. Vous vous connectez une fois et décrivez le travail. C'est ça.

Les modèles décrits ci-dessus – commande unique, outils plus playbook, dossier échafaudé, sonde de connaissances, redémarrage relayé par un agent, réexécution idempotente – sont des conventions ouvertes et non un verrouillage de la plate-forme. La version que nous livrons chez AgentLed est une implémentation. Le problème est la forme : lorsque votre utilisateur est un agent, votre intégration cesse d'être une page Web et devient une fonction que l'agent peut appeler.

La forme sur laquelle nous avons atterri se trouve dans PR #37 si vous souhaitez lire l'ensemble de modifications, et le référentiel plus large de meilleures pratiques sur github.com/Agentled/agentic-ops rassemble les modèles que la compétence installe aux côtés des outils.