Aller au contenu

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

Un tour d'agent dans le runtime du chatSché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.yesnonext turnChatManagercreate, send, permissions, interrupt, closenexus AgentSessionchosen by the provider resolvera turn already running?a message sent meanwhile is queued, not refused:a plain send interrupts the turn,a held message waits and interrupts nothing,send now cuts the turn shortattached images: one image block each,the model must have visionotherwise images_refusedpersist the UserMessageStreamingStatus truesession.send_turnmask vault secrets in every eventfail closed: an event that cannot be maskedbecomes a visible markerretryable error and nothing shown yet:Retrying, same turn, 3 tries,retry_after from the provider else backoffEventMapperAgentEvent to ChatEventunknown cost is never 0emit: persist (except deltas),broadcast, keep the mid-stream snapshotend of turn: a turn stopped on its limit continues by itself,at most 5 in a row, 500 ms apart(CHAT_AUTO_CONTINUE=false turns it off),then the queue drains; a Stop discards automatic entriesanswer_permissioninterrupt (turn and tools)set_model, set_policy_modeclose: provider closed (5 s max),session_closed emitted, session forgottenout of turn: pump_out_of_bandgroup by provider message number,mask, emit background_outputsystem_init lists degraded_featuresmessage_queue, auto_continue, nats, enrichment,plus what the session capabilities do not coverGraphSessionHooksbefore_tool, after_tool, before_compactionsame hook table as the Claude path

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.

DézoomerZoomerPlein écran
Redessiné depuis le diagramme vérifié po-chat-agent-runtime (vérifié 459cab6f). Les libellés sont les noms utilisés dans le code.
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

  1. É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.

  2. É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.

  3. É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.

  4. É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.

  5. É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.

  6. É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.

  7. É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.

  8. É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.

  9. É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.

  10. É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.

  11. É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.

  12. É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é.

  13. É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.

  14. É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é.

  15. É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.