Relisez votre agent pendant qu'il travaille

À 10 h 40, vous lancez une exécution gérée sur le service de facturation : "Documenter comment installer et lancer le service en local." À 11 h 02, une pull request arrive avec un nouveau docs/setup.md. Il est correct. La ligne 12 dit aux nouveaux arrivants de lancer go build ./..., qui ignore les build tags dont le service a besoin : leur premier build échoue donc d'une façon que la doc n'explique jamais. Et quelque part vers la sixième minute, l'agent a décidé que la section Docker du README était obsolète, et l'a réécrite. Personne ne lui avait rien demandé.

Rien de tout cela n'est difficile à corriger en relecture. Ce que la relecture ne peut pas rendre, ce sont les vingt minutes entre les deux. L'agent a fait ces choix tôt, sans personne pour les vérifier, et a construit tout le reste dessus. La correction, c'est alors une deuxième exécution qui repart de rien, relit les mêmes fichiers et ouvre une deuxième pull request.

C'est ainsi que fonctionnaient les exécutions d'agents gérées d'Archyl jusqu'ici. La page d'une exécution avait un fil d'événements et une zone d'orientation, ce qui permettait de suivre les appels d'outils si vous gardiez l'onglet ouvert, sur un ordinateur ou depuis votre téléphone. Mais ce que l'agent comptait faire, et ce qu'il avait écrit jusque-là, vous deviez le reconstituer à partir des payloads des appels d'outils, ou le découvrir dans la pull request. Pour un audit nocturne des dépendances, ça va. Pour une modification que vous allez relire de toute façon, cela place la relecture au moment où elle coûte le plus cher.

Les exécutions ont maintenant une boucle de relecture. Voici ce qui a changé :

La suite de ce billet refait la même tâche, à la nouvelle manière, dans l'ordre où vous la vivriez. La tâche est un exemple ; chaque message cité plus bas a le format que l'agent reçoit réellement.

Le plan d'abord

Avant de toucher à un fichier, l'agent doit appeler propose_plan avec un résumé en une phrase et quelques étapes concrètes. Le prompt en demande de 3 à 8, et l'outil en refuse plus de 12, pour qu'un plan reste lisible d'un coup d'œil. Le panneau Plan, en haut de la page de l'exécution, en fait une checklist. Au fil du travail, l'agent marque chaque étape En cours, Terminée ou Ignorée, parfois avec une courte note, et le panneau affiche l'étape en cours et la progression (2/4).

Par défaut, le plan est partagé et l'agent démarre tout de suite. Activez Relire le plan d'abord, dans la rubrique Coordination du profil d'agent, et il vous attend. Le panneau passe en mode relecture, où vous pouvez renommer des étapes, ajouter des détails, et ajouter, supprimer ou réordonner des étapes.

Pour la doc d'installation, l'agent a proposé cinq étapes. La quatrième était "Mettre à jour la section Docker du README", la réécriture que personne n'avait demandée. Vous la supprimez, vous ajoutez un détail à l'étape 2, et le bouton qui affichait Approuver le plan affiche maintenant Approuver le plan modifié. Voici ce que l'agent reçoit en retour :

The plan was approved with edits. Follow this plan:
1. Read the Makefile, docker-compose.yml and the config loader
2. Write prerequisites and environment variables — take values from .env.example, never from a real .env
3. Document the build, test and run commands
4. Link docs/setup.md from the README
Call update_plan when each step starts and when it is done or skipped.

Votre version modifiée est le plan que suit l'agent, et celui que la checklist reflète. Quand un plan est faux, et pas seulement un peu à côté, Demander des modifications envoie vos remarques à la place. L'agent le retravaille et propose une nouvelle révision, et les révisions précédentes restent dans le fil : vous voyez ce que vos remarques ont changé.

Tant qu'un plan n'est pas approuvé, l'agent ne peut ni écrire de fichiers, ni modifier le modèle d'architecture via les outils d'Archyl, ni pousser sur un dépôt via un connecteur. Ce n'est pas une phrase du prompt qu'il pourrait se convaincre de contourner. Les appels sont refusés, et l'agent lit :

changes are refused until your plan is approved: call propose_plan and wait for the review

Si personne ne relit le plan dans l'heure, l'exécution échoue, sans avoir rien modifié. Un profil qui exige une relecture ne peut pas s'en passer simplement parce que personne ne s'est présenté.

Des questions, quand une personne doit trancher

Certaines décisions ne devraient pas revenir à l'agent seul : une exigence ambiguë, un compromis sans gagnant évident, une opération destructrice. Pour celles-là, il dispose de ask_human. Ses instructions lui disent de ne jamais demander ce qu'il peut trouver lui-même, et il a droit à 5 questions au plus par exécution : il ne peut pas vous renvoyer le travail une question à la fois.

À mi-chemin de l'étape 2, l'agent trouve une STAGING_DATABASE_URL dans la configuration. La documenter serait utile, sauf que le staging demande un accès VPN que les nouveaux arrivants n'ont pas pendant leur première semaine. Rien dans le dépôt ne le dit, alors il pose la question.

La question apparaît au-dessus du fil, avec des Réponses suggérées quand l'agent en propose ("Laisser le staging de côté", "Le mentionner, avec une note sur l'accès VPN"), et une zone pour votre propre réponse (Cmd/Ctrl + Enter l'envoie). Toute personne qui peut modifier le projet peut répondre, et le fil indique qui l'a fait. L'agent lit The human answered: Leave staging out et poursuit.

Une question restée sans réponse pendant une heure ne fait pas échouer l'exécution. L'agent continue selon son propre jugement et indique dans son bilan l'hypothèse qu'il a retenue. C'est l'inverse du plan, et la différence tient à l'enjeu : un plan non relu signifie que rien n'a été convenu, alors qu'une question sans réponse n'est qu'une décision de plus, du genre de celles que l'agent prend tout au long de l'exécution.

Ce que coûte l'attente

Pendant que l'agent attend une relecture du plan ou une réponse, l'exécution affiche En attente de vous, et la liste des exécutions la range sous Action requise. Un bandeau au-dessus du fil indique ce qu'il attend, En attente de votre relecture du plan ou L'agent a une question, et vous y amène.

L'attente ne compte pas dans la limite de temps de l'exécution. Son échéance est repoussée du temps passé à attendre : une exécution limitée à 30 minutes qui vous a attendu 20 minutes dispose toujours de 30 minutes de travail. Elle garde en revanche sa place d'exécution simultanée. Une exécution En attente d'approbation n'a pas encore démarré, elle ne détient donc rien, mais une exécution qui vous attend est au milieu d'une conversation, avec son espace de travail ouvert, prête à reprendre dès que votre réponse lui parvient.

Le diff, au fil de l'écriture

La page d'une exécution a maintenant deux vues : Activité, le fil d'événements, et Modifications. Modifications liste chaque fichier que l'agent écrit, au moment où il l'écrit, avec un statut (Ajouté, Modifié ou Bloqué) et les lignes ajoutées et supprimées, par fichier et pour l'ensemble de l'exécution. Sélectionnez un fichier pour voir ce que chaque écriture a changé (Modification 2 sur 3), et pas seulement l'état final.

Le Guard, la vérification de conformité appliquée à chaque écriture de fichier, qui tourne désormais dans le worker, apparaît ici aussi. Une écriture qu'il a refusée apparaît comme Bloqué : le diff montre ce que l'agent a tenté d'écrire, avec la règle enfreinte, même si ce contenu n'a jamais atteint le fichier. Une écriture qu'il a seulement signalée passe, avec un avertissement sur le fichier. Un refus que vous trouviez autrefois dans un résultat d'outil est désormais un diff que vous pouvez lire.

Deux limites : les diffs longs sont tronqués au-delà de 600 lignes, et les fichiers de plus de 128 Ko apparaissent sans diff.

Un commentaire sur la ligne 12

Revenons à go build ./.... Inutile d'attendre la pull request. Dans Modifications, cliquez sur le numéro de ligne, écrivez le commentaire, puis Envoyer à l'agent (Cmd/Ctrl + Enter). À son étape suivante, l'agent le reçoit comme un commentaire de code review, avec le fichier, la ligne et son contenu :

[Review comment from a human operator on docs/setup.md, line 12 of the file as you wrote it]
> go build ./...
Use the make target instead, it sets the build tags.
Address the comment in that file, then carry on with your plan.

Il corrige la ligne, puis revient à son étape. Sous la ligne, le commentaire affiche En file d'attente jusqu'à ce que l'agent le prenne en compte, puis Transmis. Il apparaît aussi dans Activité, et chaque fichier de la liste indique son nombre de commentaires. La correction, quand elle arrive, prend la forme de la modification suivante du fichier : le diff où vous avez laissé le commentaire est aussi celui où vous la vérifiez.

Vous pouvez commenter les lignes ajoutées, inchangées et supprimées. Un commentaire sur une ligne supprimée parvient à l'agent comme un commentaire sur "the lines you removed", ce qui permet de lui dire de remettre une vérification. Les commentaires sont acceptés pendant que l'agent travaille ou vous attend, et un agent en attente les lit quand il reprend. Un commentaire encore En file d'attente à la fin de l'exécution affiche Non transmis. Les écritures bloquées par le Guard ne se commentent pas.

La zone d'orientation est toujours là, pour réorienter l'agent en texte libre sans annuler l'exécution ("laisse tomber la migration, concentre-toi sur le handler"). Un commentaire de ligne, c'est le même mécanisme, épinglé à une ligne. Ce qu'il vous épargne, c'est le préambule : "dans docs/setup.md, là où tu as écrit go build" est déjà dans le message.

L'exécution qui n'avait rien à relire

Pendant que je construisais Modifications, j'ai demandé à une exécution d'ajouter de la documentation à l'un de nos dépôts Git, et j'ai regardé la vue rester vide. Aucun fichier, aucun diff, rien à commenter.

Le projet n'avait pas de dépôt lié, donc Archyl n'avait rien cloné. En revanche, l'exécution avait un connecteur GitHub, et l'agent a fait ce qui était raisonnable avec les outils à sa disposition : il a écrit les fichiers directement sur GitHub avec l'outil push_files du connecteur. Rien n'est passé par un espace de travail. Donc rien n'est passé par le Guard, rien n'est apparu dans Modifications, et la boucle de relecture que j'étais en train de construire n'avait rien à relire.

Désormais, l'agent travaille dans un espace de travail dans les deux cas :

• Un dépôt est lié au projet. Archyl le clone au démarrage de l'exécution, comme avant.
• Pas de dépôt lié, mais un connecteur GitHub est attaché. L'agent clone lui-même le dépôt dont parle la tâche, en appelant open_repository avec les identifiants du connecteur, avant de toucher au moindre fichier. Cela ne fonctionne qu'avec le serveur MCP hébergé de GitHub (api.githubcopilot.com), et le jeton doit avoir accès au dépôt.

Une fois un espace de travail ouvert, les outils du connecteur qui écrivent dans un dépôt (push_files, create_or_update_file, delete_file, create_pull_request) sont refusés, et l'agent lit :

a repository workspace is open: change files with write_file and edit_file instead. Archyl commits your changes and opens the pull request when the run ends.

C'est cette règle qui fait passer chaque modification par le Guard, dans Modifications, et dans une seule pull request.

Quand l'exécution se termine

Archyl commite les modifications de l'espace de travail sur archyl/agent-<run id>, en utilisant les huit premiers caractères de l'ID de l'exécution, et ouvre une pull request vers la branche dont le clone est parti. Le lien se trouve en haut de Modifications (Ouvrir la pull request) et dans le résultat. La façon dont l'exécution se termine décide de ce qui est publié :

Sur GitLab, le brouillon est une merge request Draft:. Sur Bitbucket, la branche est poussée sans pull request. Une exécution qui n'a modifié aucun fichier ne publie rien.

Vos commentaires deviennent l'exécution suivante

La relecture ne s'arrête pas avec l'exécution. La pull request est ouverte, et vous lisez le diff final dans Modifications. Un commentaire sur une exécution terminée n'a plus d'agent à atteindre, il devient donc une note pour la suivante : Garder pour la suite le conserve dans votre navigateur. Une barre au-dessus des fichiers les compte (3 commentaires pour une suite) et propose Poursuivre avec ces commentaires.

Chaque exécution terminée, quelle que soit son issue, propose deux boutons. Relancer ouvre la fenêtre de lancement avec la même tâche et le même profil, pour une nouvelle exécution repartie de zéro : le bon choix quand la première tentative est partie dans une direction sur laquelle vous ne voulez pas construire. Poursuivre lance une nouvelle exécution qui reprend le travail de celle-ci, avec ses instructions préremplies à partir de vos commentaires pour la suite, si vous en avez laissé, un par ligne :

- docs/setup.md:28 — Say that make seed needs the database container running.
- docs/setup.md:44 — Add how to run the tests for a single package.
- README.md:18 (removed line) — Keep the troubleshooting note for port 5432, setup.md doesn't have it.

Modifiez-les comme vous voulez. Le profil est par défaut celui de l'exécution, et vous pouvez choisir les connecteurs.

Même branche, même pull request

Une suite, ce n'est pas simplement une nouvelle exécution avec un prompt plus long. Elle part de la branche publiée par l'exécution précédente, commite dessus et ajoute ses modifications à la même pull request au lieu d'en ouvrir une autre. Si l'exécution précédente avait ouvert son dépôt via le connecteur GitHub, la suite le rouvre sur cette branche avant que l'agent ne démarre.

L'agent sait aussi sur quoi il construit. La tâche précédente, ce que cette exécution a fait (son résumé de bilan, ou la raison de son arrêt) et l'endroit où se trouve son travail figurent tous en tête de son prompt (les ID, l'URL et le résumé sont des exemples) :

# Continuing a previous run
This run continues the work of run `4f1c2a9e-7b3d-4e0a-9c6f-2d8b1a5e3c70`. Build on what it did rather than starting over.

## What it was asked
Document how to set up and run the service locally.

## What it did
Added docs/setup.md with prerequisites, environment variables and the make targets, and linked it from the README. Left the staging database out, as answered.

Its changes are on the branch `archyl/agent-4f1c2a9e`, which your workspace starts from. Your changes are added to its pull request: https://github.com/acme/billing/pull/212. If the workspace could not start from that branch, the run feed says so and your changes go to a new pull request.

The task below is what the person wants now, often review comments on that work: address each of them.

Les relecteurs voient une seule pull request grandir, pas une traînée de pull requests. Le Copilot cloud agent de GitHub gère les suites de la même façon : vous mentionnez @copilot dans un commentaire sur une pull request, et par défaut il pousse des commits sur la branche de cette pull request (GitHub Docs). Une pull request par unité de travail, c'est la bonne forme, et les suites s'y tiennent.

Ce qui se passe aux limites :

• La branche a disparu, fusionnée puis supprimée par exemple. La suite part de la branche par défaut et ouvre une nouvelle pull request, et une ligne orange dans le fil le signale : "Impossible de récupérer la branche archyl/agent-4f1c2a9e de l'exécution précédente. Cette exécution part de la branche par défaut et ouvrira une nouvelle pull request."
• La pull request est en brouillon. Elle le reste. Marquez-la comme prête pour la revue une fois le travail terminé.
• Uniquement les branches d'agents. Archyl poursuit sur les branches que ses agents ont créées, celles sous archyl/, et ne commite jamais sur une branche créée par une personne.

Les deux exécutions sont liées l'une à l'autre : la nouvelle affiche Suite de l'exécution, la précédente Poursuivie dans. Une exécution encore en cours ne peut pas être poursuivie. Commentez plutôt ses lignes.

La suite conserve aussi son contexte d'architecture. Sa session de travail est ouverte pour la tâche précédente plus la suite, et pas pour la suite seule : elle retrouve donc les mêmes éléments d'architecture et la même mémoire que l'exécution qu'elle poursuit. C'est plus important qu'il n'y paraît. "Préciser que make seed a besoin du container de base de données en marche" ne nomme aucun service, et une session ouverte sur cette seule ligne n'aurait pas grand-chose à quoi se rattacher.

Ce que ça ne fait pas

Le worker n'a pas de shell. Il lit, écrit, modifie, liste et cherche des fichiers, mais il ne peut ni builder le projet ni lancer les tests. Dans cet exemple, il peut lire le Makefile, pas lancer make build pour vérifier que la doc est juste. Un diff propre n'est pas un build qui passe, et c'est toujours la CI qui fait ce travail.

Un commentaire de ligne est une indication, pas un gate. Il n'y a pas d'état résolu, et rien ne vérifie que l'agent a traité un commentaire. Vous voyez sa modification suivante dans le diff, et c'est à vous de juger.

Les notes pour la suite vivent dans un seul navigateur. Tant que vous n'avez pas poursuivi l'exécution, vos collègues ne voient pas les commentaires que vous avez gardés pour la suite. Les commentaires envoyés à un agent en cours de travail, eux, sont différents : ils sont dans le fil, visibles de tous.

La relecture du plan suppose que quelqu'un est là. C'est un paramètre par profil, désactivé par défaut, et chaque exécution de ce profil le respecte, exécutions planifiées comprises. Une exécution à 3 h du matin sur un profil où la relecture est activée attend une heure, puis échoue sans rien modifier. Les questions attendent une heure aussi, puis l'agent décide seul.

Le clone via connecteur ne fonctionne qu'avec GitHub. open_repository fonctionne avec le serveur MCP hébergé de GitHub. Pour tout autre hébergeur, liez le dépôt au projet.

Par où commencer

Choisissez une petite tâche que vous relirez de toute façon, et lancez-la sur un profil où Relire le plan d'abord est activé. Gardez la page de l'exécution ouverte. Modifiez le plan avant de l'approuver, même si vous vous contentez de supprimer l'étape que vous n'auriez pas demandée. Dans Modifications, commentez la première ligne que vous auriez signalée dans la pull request, et regardez-la passer de En file d'attente à Transmis. Quand l'exécution se termine, laissez le reste en commentaires pour la suite et cliquez sur Poursuivre.

Laissez la relecture du plan désactivée sur les profils qu'utilisent vos plannings, sauf si quelqu'un sera réveillé pour relire.

Les plans, les questions, le diff en direct, les commentaires de ligne et les suites font partie des exécutions d'agents gérées d'Archyl. Chaque paramètre et chaque libellé cités plus haut se trouvent dans la documentation des exécutions d'agents gérées. À lire aussi : les agents gérés rendent désormais des comptes au Harness, pour le Guard et les sessions de travail sur lesquels tout cela repose, et le lancement des exécutions d'agents gérées.