Docs · Internals
Ce qui se passe dans un tour d'agent
Le runtime d'agent est la partie du backend qui pilote une session nexus pour le chat. Cette page suit un tour, puis ce qui l'entoure : les images, la file, les portées de permission, le contenu du graphe dans une invite et la chronologie de chaque appel d'outil.
Ce que ça fait
Il persiste ton message (ou le met en file quand un tour tourne), démarre le tour, masque les secrets dans chaque événement, convertit les événements au format du chat et les diffuse.
Un tour qui échoue avec une erreur réessayable avant d'avoir rien montré est rejoué. Un tour qui a déjà montré du contenu, ou qui a échoué pour de bon, ne l'est jamais.
Ce qu'une session ne sait pas faire est listé dans degraded_features, dans l'événement de début de session, pour que le tableau de bord puisse te le dire : par exemple les sous-agents sur un agent ACP, les images sur un modèle sans vision, ou les outils de Project Orchestrator sur un agent qui refuse les serveurs MCP par session.
Le schéma
Fais glisser pour te déplacer. Pince, Ctrl + molette ou les touches + et - pour zoomer ; flèches pour bouger ; 0 ou double-clic pour ajuster. Choisis un nœud pour allumer ses liens.
Description textuelle du schéma
Schéma de flux. Le ChatManager envoie un message. Si un tour tourne déjà, le message est mis en file au lieu d'être refusé : un envoi simple interrompt le tour, un message retenu attend sans rien interrompre, et « envoyer maintenant » écourte le tour. Sinon les images jointes deviennent des blocs d'image, le message utilisateur est persisté et le tour démarre. Chaque événement du provider est masqué des secrets du coffre, en échec fermé. Une erreur réessayable sans rien montré est rejouée jusqu'à trois fois. Les événements sont convertis d'AgentEvent en ChatEvent, puis émis : persistés, diffusés et gardés dans un instantané de mi-flux. En fin de tour, un tour arrêté sur sa limite continue de lui-même jusqu'à cinq fois de suite, puis la file se vide. À part, la sortie hors tour est regroupée et émise comme sortie de fond, les commandes de session comme answer_permission, interrupt, set_model et close vont à la session, des hooks du graphe s'exécutent avant et après les outils, et l'événement de début de session liste les fonctions dégradées.
Lecture guidée
Étape 1. Un tour à la fois
Un message envoyé pendant qu'un tour tourne est mis en file, pas refusé. Envoyé comme message ordinaire, il interrompt le tour en cours et est lu ensuite, comme sur Claude Code. Retenu dans la file, il est listé, attend la fin du tour et n'interrompt rien ; « Envoyer maintenant » écourte le tour pour lui. La décision se prend sous le verrou de la file.
Étape 2. Persister et envoyer
Le contexte du graphe pour le tour et les pièces jointes sont placés devant ton message. Puis il est persisté, l'état de flux passe à vrai et send_turn démarre le flux.
Étape 3. Masquer
Chaque événement du provider passe par le masqueur de secrets du coffre avant d'être stocké ou diffusé. Il échoue fermé : un événement impossible à masquer devient un marqueur visible, et un événement terminal retenu termine quand même le tour.
Étape 4. Réessayer
Un done.error ou error réessayable sans rien montré émet un événement Retrying et rejoue le même tour, jusqu'à 3 essais. Il attend retry_after quand le provider en donne un, sinon il temporise.
Étape 5. Convertir
EventMapper convertit les événements neutres en événements de chat. Rejouer une conversation enregistrée de 21 messages donne les mêmes événements de chat que l'ancien chemin. Un coût inconnu reste inconnu, jamais 0.
Étape 6. Émettre
emit ajoute provider, capabilities, tool_policy, engine et degraded_features à l'événement de début de session, persiste l'événement (sauf les deltas de flux et l'état de flux), le diffuse et garde l'instantané de mi-flux pour les clients qui se reconnectent.
Étape 7. Hors tour, commandes, fermeture
La sortie qui arrive hors tour est regroupée par numéro de message du provider, masquée et émise comme background_output. Les réponses de permission, interrupt, les changements de modèle et de politique vont à la session. Close ferme le provider (5 secondes au plus), émet session_closed et oublie la session.
Étape 8. Hooks du graphe
GraphSessionHooks branche la même table de hooks que le chemin Claude sur before_tool, after_tool et before_compaction : du contexte peut être ajouté, un appel refusé ou son entrée remplacée, et un hook en échec est ignoré. Seuls le moteur natif et Claude Code les reçoivent, pas Codex ni ACP.
Étape 9. Images jointes
Les images jointes à un message sont lues dans le magasin de documents et envoyées après le texte, dans l'ordre, comme blocs d'image, sur Claude Code et sur un modèle natif. Le modèle décide : un modèle natif dont le catalogue dit qu'il voit les reçoit, un modèle sans vision les refuse par une erreur images_refused, et le tour n'est pas envoyé. Claude Code accepte png, jpeg, gif et webp, jusqu'à 5 Mio une fois décodées.
Étape 10. Fin de tour : auto-continue et file
Quand un tour s'arrête sur sa limite de tours, le runtime le poursuit tout seul après 500 ms, 5 fois d'affilée au plus ; seul CHAT_AUTO_CONTINUE=false coupe cela. Ensuite les messages en file partent l'un après l'autre jusqu'à ce que la file soit vide. Un Stop jette les entrées automatiques.
Étape 11. Portées de permission
Une demande de permission peut recevoir la réponse une fois, pour la session ou, dans une conversation qui a un propriétaire et un projet, toujours. Quel que soit ton choix, le provider ne reçoit jamais que « une fois » : PO garde l'autorisation et répond lui-même aux demandes suivantes qu'elle couvre, parce que les moteurs comparent de façon lâche (une commande n'est coupée que sur ; & |) et qu'une comparaison trop large a déjà transformé l'approbation d'une commande en une autre. Une autorisation de session ne couvre que l'appel identique, gardé en mémoire de cette session. Pour une commande, elle ne s'applique que si chaque programme de la ligne figure sur une courte liste de programmes qui n'exécutent rien venant du projet ; le shell et les patchs de Codex, et tout agent ACP, reçoivent toujours « une fois », et un outil inconnu est refusé avec une erreur typée pour que tu répondes une fois. Une autorisation n'autorise jamais ce que la politique du moteur refuse, car seules les demandes que le moteur a posées lui parviennent.
Étape 12. Règles durables
Une règle « toujours » est plus stricte encore : aucun outil de fichier, et une seule commande simple, sans opérateur, redirection ni joker. Elle appartient à une personne et à un projet, dans un dossier privé de la machine qui possède la session ; un lien symbolique, un propriétaire étranger ou un fichier que d'autres peuvent écrire est ignoré, et chaque règle relue est revérifiée, donc une règle modifiée à la main en quelque chose de plus large ne vaut rien. Une personne peut lister ses règles et en révoquer une (GET et DELETE sur /api/chat/permission-rules). Une session sans propriétaire ne garde aucune règle durable, et « toujours » n'y est pas proposé.
Étape 13. Le contenu du graphe est une donnée
Les notes, décisions, personas, skills, le profil de l'utilisateur, le contexte de fichiers et les descriptions d'outils MCP tiers sont écrits par des personnes, des agents et des paquets importés. Avant d'entrer dans une invite, un tel texte est enveloppé dans un conteneur untrusted_data muni d'un nonce aléatoire : il ne peut contenir ni la balise fermante, ni le nonce, ni une clôture de code, ni un titre, ni des caractères de changement de sens d'écriture, et l'invite dit au modèle de le traiter comme une donnée. Cela réduit le risque qu'un modèle obéisse à une instruction cachée dans une note ; cela ne l'exclut pas. Les instructions d'un état de protocole sont volontairement hors du conteneur : qui peut éditer une définition de protocole est cru comme l'opérateur.
Étape 14. Chronologie de chaque appel d’outil
Le serveur date lui-même chaque appel d'outil, à la milliseconde, sur les deux moteurs du chat (le chemin du CLI Claude Code et le moteur agent), si bien que la frise de la conversation ne dépend pas de ce qu'un provider rapporte. L'horloge démarre quand le moteur prend l'appel en charge, avant qu'une permission soit demandée, et note quand tu as répondu ; un événement tool_timing est stocké et envoyé juste après le résultat. Un début d'exécution que le moteur n'a pas vu, comme pour une session distante, Codex ou ACP, est omis plutôt que deviné.
Étape 15. Questions d’un modèle natif
Le moteur natif offre son propre outil AskUserQuestion, affiché comme la même carte de question que sur Claude Code. La réponse est un tour utilisateur : le tour se termine une fois les appels de l'étape faits, et ta réponse lance le suivant. Un modèle sans outils ne le reçoit pas.
Pourquoi c'est conçu ainsi
Échouer fermé sur les secrets
Masquer un événement qu'on ne sait pas lire serait deviner : l'événement est remplacé par un marqueur visible plutôt que passé en clair.
Ne jamais rejouer ce que tu as vu
Rejouer un tour qui a déjà produit du contenu dupliquerait le texte et les appels d'outils. Seul un échec réessayable avant toute sortie est rejoué.
Dire ce qui manque
Les fonctions que le runtime ne reprend pas, et les capacités que la session n'a pas, sont écrites dans l'événement de début de session au lieu de disparaître en silence.
Inconnu n'est pas zéro
Un provider qui ne rapporte aucun coût laisse le coût inconnu. Afficher 0 ressemblerait à un tour gratuit.
Ce qui n'est pas établi
- Ce chemin n'a jamais tourné contre le vrai CLI Claude, un vrai endpoint de modèle ni un vrai agent Codex ou ACP : seulement des faux providers et des faux exécutables, plus un vrai harnais natif pour les tâches de fond et l'annulation. NATS a été testé contre un courtier de test en processus, jamais contre un vrai serveur ni deux vraies instances. Comme sur l'ancien chemin, la mémoire n'enregistre un tour que si elle est configurée.
Sources publiques
Où vérifier chaque affirmation, dans les dépôts publics.