{"meta":{"title":"Boucle de l’agent","intro":"Comment l’interface CLI Copilot traite un message utilisateur de bout en bout : de l’invite à session.idle.","product":"GitHub Copilot","breadcrumbs":[{"href":"/fr/copilot","title":"GitHub Copilot"},{"href":"/fr/copilot/how-tos","title":"Procédures"},{"href":"/fr/copilot/how-tos/copilot-sdk","title":"Kit de développement logiciel (SDK) Copilot"},{"href":"/fr/copilot/how-tos/copilot-sdk/features","title":"Fonctionnalités"},{"href":"/fr/copilot/how-tos/copilot-sdk/features/agent-loop","title":"Boucle d’assistant"}],"documentType":"article"},"body":"# Boucle de l’agent\n\nComment l’interface CLI Copilot traite un message utilisateur de bout en bout : de l’invite à session.idle.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Architecture\n\n![Diagramme : diagramme graphique montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-0.png)\n\nLe **SDK** est une couche de transport : il envoie votre requête au **Copilot CLI** via JSON-RPC et renvoie les événements à votre application.\n**L’interface CLI** est l’orchestrateur qui exécute la boucle d’utilisation de l’outil agentique, en effectuant un ou plusieurs appels d’API LLM jusqu’à ce que la tâche soit effectuée.\n\n## Boucle d’utilisation des outils\n\nLorsque vous appelez `session.send({ prompt })`, le CLI entre dans une boucle :\n\n![Diagramme : Organigramme montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png)\n\nLe modèle voit **l’historique complet des conversations** sur chaque appel : invite système, message utilisateur et tous les appels et résultats d’outils précédents.\n\n**Informations clés :** Chaque itération de cette boucle est exactement un appel d’API LLM, visible sous la forme d’une `assistant.turn_start` / `assistant.turn_end` paire dans le journal des événements. Il n’y a pas d’appels masqués.\n\n## Tours de conversation : définition\n\nUn **tour** est un seul appel d’API LLM et ses conséquences :\n\n1. L’interface CLI envoie l’historique des conversations au LLM\n2. Le LLM répond (éventuellement avec des demandes d’outils)\n3. Si des outils ont été demandés, l’interface CLI les exécute\n4. `assistant.turn_end` est émis\n\nUn message d’utilisateur unique entraîne généralement **plusieurs tours**. Par exemple, une question telle que « Comment fonctionne X dans cette base de code ? » peut produire :\n\n| Tourner                      | Ce que fait le modèle                                                  | toolRequests ? |\n| ---------------------------- | ---------------------------------------------------------------------- | -------------- |\n| 1                            | Appelez `grep` et `glob` pour rechercher dans la base de code          |                |\n| ✅ Oui                        |                                                                        |                |\n| 2                            | Lit des fichiers spécifiques en fonction des résultats de la recherche |                |\n| ✅ Oui                        |                                                                        |                |\n| 3                            | Lit d’autres fichiers pour un contexte plus approfondi                 |                |\n| ✅ Oui                        |                                                                        |                |\n| 4                            | Produit la réponse de texte finale                                     |                |\n| ❌ Non → la boucle se termine |                                                                        |                |\n\nLe modèle décide de chaque tour s’il faut demander plus d’outils ou produire une réponse finale. Chaque appel voit le **contexte cumulé complet** (tous les appels et résultats d’outils précédents), afin qu’il puisse prendre une décision éclairée quant à la quantité d’informations suffisantes.\n\n## Flux d’événements pour une interaction à plusieurs tours\n\n![Diagramme : Organigramme montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png)\n\n## Qui déclenche chaque tour ?\n\n| Acteur                | Responsabilité                                                                                                             |\n| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| **Votre application** | Envoie l’invite initiale via `session.send()`                                                                              |\n| **Copilot CLI**       | Exécute la boucle d’utilisation des outils : exécute des outils et alimente les résultats vers le LLM pour le tour suivant |\n| **LLM**               | Détermine s’il faut demander des outils (continuer la boucle) ou produire une réponse finale (arrêter)                     |\n| **SDK**               | Transmet les événements ; ne contrôle pas la boucle                                                                        |\n\nLa CLI est purement mécanique : « le modèle a demandé des outils → exécution → nouvel appel du modèle ». Le **modèle** est le décideur pour quand arrêter.\n\n## Comparaison de `session.idle` et de `session.task_complete`\n\nIl s’agit de deux signaux d’achèvement différents avec des garanties très différentes :\n\n### `session.idle`\n\n* **Toujours émis** lorsque la boucle d’utilisation de l’outil se termine\n* **Éphémère** : non conservé sur le disque, non relecturé lors de la reprise de session\n* Signifie : « l’agent a arrêté le traitement et est prêt pour le message suivant »\n* **Utilisez-le** comme signal fiable « terminé »\n\nLa méthode du kit de développement logiciel `sendAndWait()` (SDK) attend cet événement :\n\n```typescript\n// Blocks until session.idle fires\nconst response = await session.sendAndWait({ prompt: \"Fix the bug\" });\n```\n\n### `session.task_complete`\n\n* **Émis éventuellement** : exige que le modèle le signale explicitement\n* **Persisté** : enregistré dans le journal des événements de session sur le disque\n* Signifie : « l’agent considère la tâche globale remplie »\n* Porte un champ facultatif `summary`\n\n```typescript\nsession.on(\"session.task_complete\", (event) => {\n    console.log(\"Task done:\", event.data.summary);\n});\n```\n\n### Mode pilote automatique : la CLI invite à déclencher `task_complete`\n\nEn **mode Autopilot** (opération sans tête/autonome), l’interface CLI suit activement si le modèle a appelé `task_complete`. Si la boucle d’utilisation des outils se termine sans cela, le CLI injecte un message utilisateur synthétique pour inciter le modèle :\n\n> *« Vous n’avez pas encore marqué la tâche comme étant terminée à l’aide de l’outil task\\_complete. Si vous planifiez, arrêtez la planification et démarrez l’implémentation. Vous n’avez pas terminé tant que vous n’avez pas terminé la tâche.*\n\nCela redémarre efficacement la boucle d’utilisation de l’outil : le modèle voit le coup de pouce en tant que nouveau message utilisateur et continue de fonctionner. L’incitation indique également au modèle **de ne pas** appeler `task_complete` prématurément :\n\n* Ne l’appelez pas si vous avez des questions ouvertes : prendre des décisions et continuer à travailler\n* Ne l’appelez pas si vous rencontrez une erreur : essayez de le résoudre\n* N’appelez-le pas s’il y a des étapes restantes : effectuez-les d’abord\n\nCela crée un **mécanisme d’achèvement à deux niveaux** dans Autopilot :\n\n1. Le modèle appelle `task_complete` avec un résumé → CLI émet `session.task_complete` → terminé\n2. Le modèle s’arrête sans l’appeler → relances de CLI → le modèle continue ou appelle `task_complete`\n\n### Pourquoi `task_complete` peut ne pas apparaître\n\nEn **mode interactif** (chat normal), le CLI ne sollicite pas `task_complete`. Le modèle peut l’ignorer entièrement. Raisons courantes :\n\n* **Q\\&A conversationnelle** : le modèle répond à une question et s’arrête simplement : il n’y a pas de « tâche » discrète à terminer\n* **Discrétion** du modèle : le modèle produit une réponse de texte finale sans appeler le signal complet de la tâche\n* **Sessions interrompues** : la session se termine avant que le modèle atteigne un point d’achèvement\n\nLe CLI émet `session.idle` dans tous les cas, car il s’agit d’un signal mécanique (la boucle s’est terminée), et non d’un signal sémantique (le modèle estime avoir terminé).\n\n### Laquelle devez-vous utiliser ?\n\n| Cas d’utilisation                                  | Signal |\n| -------------------------------------------------- | ------ |\n| « Attendre que l’agent termine le traitement »     |        |\n| `session.idle`                                     |        |\n| ✅                                                  |        |\n|                                                    |        |\n| « Savoir quand une tâche de codage est effectuée » |        |\n| `session.task_complete` (meilleur effort)          |        |\n| « Délai d’expiration/gestion des erreurs »         |        |\n| `session.idle`                                     |        |\n\n*\n\n`session.error`\n✅\n|\n\n## Comptage des appels LLM\n\nLe nombre de paires dans le journal des `assistant.turn_start` / `assistant.turn_end` événements est égal au nombre total d’appels d’API LLM effectués. Il n’y a pas d’appels masqués pour la planification, l’évaluation ou la vérification de l’achèvement.\n\nPour inspecter le nombre de tour pour une session :\n\n```bash\n# Count turns in a session's event log\ngrep -c \"assistant.turn_start\" ~/.copilot/session-state/<sessionId>/events.jsonl\n```\n\n## Lectures complémentaires\n\n* [Événements de session de streaming](/fr/copilot/how-tos/copilot-sdk/features/streaming-events) : Référence au niveau du champ complet pour chaque type d’événement\n* [Reprise de session et persistance](/fr/copilot/how-tos/copilot-sdk/features/session-persistence) : Enregistrement et reprise des sessions\n* [Travailler avec les hooks](/fr/copilot/how-tos/copilot-sdk/features/hooks) : Interception d’événements dans la boucle (autorisations, outils)"}