{"meta":{"title":"Die Agentenschleife","intro":"Wie die Copilot CLI eine Benutzernachricht von Ende zu Ende verarbeitet: vom Prompt bis zu session.idle.","product":"GitHub Copilot","breadcrumbs":[{"href":"/de/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/de/enterprise-cloud@latest/copilot/how-tos","title":"Vorgehensweisen"},{"href":"/de/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/de/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"Funktionen"},{"href":"/de/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/agent-loop","title":"Agenten-Schleife"}],"documentType":"article"},"body":"# Die Agentenschleife\n\nWie die Copilot CLI eine Benutzernachricht von Ende zu Ende verarbeitet: vom Prompt bis zu session.idle.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Aufbau\n\n![Diagramm: Graphdiagramm, das den beschriebenen Prozess darstellt.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-0.png)\n\nDas **SDK** ist eine Transportschicht – es sendet Ihren Prompt über JSON-RPC an die **Copilot CLI** und gibt Ereignisse an Ihre App zurück. Die **CLI** ist der Orchestrator, der die agentische Toolverwendungsschleife ausführt und einen oder mehrere LLM-API-Aufrufe ausführt, bis die Aufgabe abgeschlossen ist.\n\n## Die Toolverwendungsschleife\n\nWenn Sie `session.send({ prompt })` aufrufen, tritt die CLI in eine Schleife ein:\n\n![Diagramm: Flussdiagramm mit dem beschriebenen Prozess.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png)\n\nDas Modell sieht den **vollständigen Unterhaltungsverlauf** für jeden Anruf – Systemaufforderung, Benutzernachricht und alle vorherigen Toolaufrufe und -ergebnisse.\n\n**Schlüsselerblick:** Jede Iteration dieser Schleife ist genau ein LLM-API-Aufruf, der als ein `assistant.turn_start` / `assistant.turn_end` Paar im Ereignisprotokoll sichtbar ist. Es gibt keine verborgenen Aufrufe.\n\n## Drehungen – was sie sind\n\nEin **Turn** ist ein einzelner LLM-API-Aufruf samt seinen Auswirkungen:\n\n1. Die CLI sendet den Konversationsverlauf an das LLM.\n2. Die LLM antwortet (möglicherweise mit Toolanforderungen)\n3. Wenn Tools angefordert wurden, führt die CLI sie aus.\n4. `assistant.turn_end` wird ausgegeben\n\nEine einzelne Benutzernachricht führt in der Regel zu **mehreren Gesprächswechseln**. Beispielsweise eine Frage wie \"Wie funktioniert X in dieser Codebasis?\" kann folgendes erzeugen:\n\n| Drehung                 | Funktionsweise des Modells                              | toolRequests? |\n| ----------------------- | ------------------------------------------------------- | ------------- |\n| 1                       | Aufrufe `grep` und `glob` Zum Durchsuchen der Codebasis |               |\n| ✅ Ja                    |                                                         |               |\n| 2                       | Liest bestimmte Dateien basierend auf Suchergebnissen   |               |\n| ✅ Ja                    |                                                         |               |\n| 3                       | Liest weitere Dateien für tieferen Kontext              |               |\n| ✅ Ja                    |                                                         |               |\n| 4                       | Erzeugt die endgültige Textantwort                      |               |\n| ❌ Nein → Schleife endet |                                                         |               |\n\nDas Modell entscheidet jeweils, ob weitere Tools angefordert oder eine endgültige Antwort erstellt werden sollen. Jeder Aufruf sieht den **vollständigen gesammelten Kontext** (alle vorherigen Toolaufrufe und -ergebnisse), sodass er eine fundierte Entscheidung darüber treffen kann, ob er über genügend Informationen verfügt.\n\n## Ereignisfluss für eine mehrstufige Interaktion\n\n![Diagramm: Flussdiagramm mit dem beschriebenen Prozess.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png)\n\n## Wer löst jede Drehung aus?\n\n| Actor (Schauspieler) | Verantwortung                                                                                                                      |\n| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| **Ihre App**         | Sendet die erste Eingabeaufforderung über `session.send()`                                                                         |\n| **Copilot CLI**      | Führt die Tool-Nutzungsschleife aus – führt Tools aus und gibt die Ergebnisse zur nächsten Interaktion an das LLM zurück.          |\n| **LLM**              | Entscheidet, ob Tools angefordert werden sollen (Schleife fortsetzen) oder eine abschließende Antwort erzeugt werden soll (Stopp). |\n| **SDK**              | Übergibt Ereignisse; steuert die Schleife nicht.                                                                                   |\n\nDie CLI ist rein mechanisch: „Modell fordert Tools an → ausführen → Modell erneut aufrufen.“ Das **Modell** ist der Entscheidungsträger für den Zeitpunkt der Beendigung.\n\n## `session.idle` Vs `session.task_complete`\n\nDies sind zwei verschiedene Abschlusssignale mit sehr unterschiedlichen Garantien:\n\n### `session.idle`\n\n* **Immer ausgegeben** wenn die Tool-Nutzungsschleife endet\n* **Kurzlebig**: Nicht auf dem Datenträger beibehalten, nicht beim Fortsetzen der Sitzung wiedergegeben\n* Bedeutet: \"Der Agent hat die Verarbeitung beendet und ist bereit für die nächste Nachricht\"\n* **Verwenden Sie dies** als zuverlässiges \"fertiges\" Signal\n\nDie Methode des `sendAndWait()` SDK wartet auf dieses Ereignis:\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* **Optional ausgegeben**: Erfordert, dass das Modell es explizit signalisiert.\n* **Persistent**: im Sitzungsereignisprotokoll auf dem Datenträger gespeichert\n* Bedeutet: \"Der Agent hält den Gesamtvorgang für erfüllt\"\n* Enthält ein optionales `summary` Feld.\n\n```typescript\nsession.on(\"session.task_complete\", (event) => {\n    console.log(\"Task done:\", event.data.summary);\n});\n```\n\n### Autopilot-Modus: Cli-Nudges für `task_complete`\n\nIm **Autopilot-Modus** (Headless-/autonomer Betrieb) verfolgt die CLI aktiv, ob das Modell `task_complete` aufgerufen hat. Wenn die Toolverwendungsschleife ohne sie endet, fügt die CLI eine synthetische Benutzernachricht ein, die das Modell angibt:\n\n> *\"Sie haben die Aufgabe noch nicht mit dem task\\_complete Tool als abgeschlossen markiert. Wenn Sie planen, beenden Sie die Planung, und beginnen Sie mit der Implementierung. Sie sind erst fertig, wenn Sie die Aufgabe vollständig abgeschlossen haben.\"*\n\nDadurch wird die Toolverwendungsschleife effektiv neu gestartet– das Modell sieht den Nudge als neue Benutzermeldung und arbeitet weiterhin. Der Nudge weist das Modell auch an, **nicht**`task_complete` vorzeitig aufzurufen:\n\n* Nennen Sie es nicht, wenn Sie offene Fragen haben – treffen Sie Entscheidungen, und arbeiten Sie weiter\n* Rufen Sie die Funktion nicht auf, wenn ein Fehler auftritt – versuchen Sie stattdessen, den Fehler zu beheben.\n* Rufen Sie sie nicht auf, wenn noch Schritte vorhanden sind– führen Sie sie zuerst aus.\n\nDadurch wird ein **zweistufiger Abschlussmechanismus** in Autopilot erstellt:\n\n1. Das Modell ruft `task_complete` mit einer Zusammenfassung auf → CLI gibt `session.task_complete` aus → fertig\n2. Das Modell stoppt, ohne es aufzurufen → CLI gibt einen Anstoß → das Modell fährt fort oder ruft `task_complete` auf\n\n### Warum `task_complete` möglicherweise nicht angezeigt wird\n\nIm **interaktiven Modus** (normaler Chat) fordert die CLI nicht zur Eingabe von `task_complete` auf. Das Modell kann es vollständig überspringen. Häufige Gründe:\n\n* **Unterhaltungs-F\\&A**: Das Modell beantwortet eine Frage und hält einfach an – es gibt keine diskrete \"Aufgabe\", die abgeschlossen werden soll.\n* **Modell diskretion**: Das Modell erzeugt eine endgültige Textantwort, ohne das Task-Complete-Signal aufzurufen.\n* **Unterbrochene Sitzungen**: Die Sitzung endet, bevor das Modell einen Abschlusspunkt erreicht.\n\nDie CLI gibt `session.idle` trotzdem aus, weil es sich um ein mechanisches Signal handelt (die Schleife ist beendet) und nicht um ein semantisches (das Modell denkt, dass es fertig ist).\n\n### Welche Option sollten Sie verwenden?\n\n| Anwendungsfall                                                 | Signal |\n| -------------------------------------------------------------- | ------ |\n| \"Warten Sie, bis der Agent die Verarbeitung abgeschlossen hat\" |        |\n| `session.idle`                                                 |        |\n| ✅                                                              |        |\n|                                                                |        |\n| \"Wissen, wann eine Codierungsaufgabe abgeschlossen ist\"        |        |\n| `session.task_complete` (nach bestem Bemühen)                  |        |\n| \"Timeout/Fehlerbehandlung\"                                     |        |\n| `session.idle`                                                 |        |\n\n*\n\n`session.error`\n✅\n|\n\n## Zählen von LLM-Anrufen\n\nDie Anzahl der `assistant.turn_start` / `assistant.turn_end` Paare im Ereignisprotokoll entspricht der Gesamtzahl der LLM-API-Aufrufe. Es gibt keine versteckten Aufrufe zur Planung, Bewertung oder Prüfung des Abschlusses.\n\nSo überprüfen Sie die Anzahl der Interaktionen einer Sitzung:\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## Weiterführende Lektüre\n\n* [Ereignisse einer Streaming-Sitzung](/de/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/streaming-events): Vollständige Referenz auf Feldebene für jeden Ereignistyp\n* [Wiederaufnahme und Persistenz der Sitzung](/de/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/session-persistence): Wie Sitzungen gespeichert und fortgesetzt werden\n* [Arbeiten mit Hooks](/de/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/hooks): Abfangen von Ereignissen in der Schleife (Berechtigungen, Werkzeuge)"}