Die Agentenschleife

Wie die Copilot CLI eine Benutzernachricht von Ende zu Ende verarbeitet: vom Prompt bis zu session.idle.

In diesem Artikel

Aufbau

Diagramm: Graphdiagramm, das den beschriebenen Prozess darstellt.

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

Die Toolverwendungsschleife

Wenn Sie session.send({ prompt }) aufrufen, tritt die CLI in eine Schleife ein:

Diagramm: Flussdiagramm mit dem beschriebenen Prozess.

Das Modell sieht den vollständigen Unterhaltungsverlauf für jeden Anruf – Systemaufforderung, Benutzernachricht und alle vorherigen Toolaufrufe und -ergebnisse.

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.

Drehungen – was sie sind

Ein Turn ist ein einzelner LLM-API-Aufruf samt seinen Auswirkungen:

  1. Die CLI sendet den Konversationsverlauf an das LLM.
  2. Die LLM antwortet (möglicherweise mit Toolanforderungen)
  3. Wenn Tools angefordert wurden, führt die CLI sie aus.
  4. assistant.turn_end wird ausgegeben

Eine einzelne Benutzernachricht führt in der Regel zu mehreren Gesprächswechseln. Beispielsweise eine Frage wie "Wie funktioniert X in dieser Codebasis?" kann folgendes erzeugen:

DrehungFunktionsweise des ModellstoolRequests?
1Aufrufe grep und glob Zum Durchsuchen der Codebasis
✅ Ja
2Liest bestimmte Dateien basierend auf Suchergebnissen
✅ Ja
3Liest weitere Dateien für tieferen Kontext
✅ Ja
4Erzeugt die endgültige Textantwort
❌ Nein → Schleife endet

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

Ereignisfluss für eine mehrstufige Interaktion

Diagramm: Flussdiagramm mit dem beschriebenen Prozess.

Wer löst jede Drehung aus?

Actor (Schauspieler)Verantwortung
Ihre AppSendet die erste Eingabeaufforderung über session.send()
Copilot CLIFührt die Tool-Nutzungsschleife aus – führt Tools aus und gibt die Ergebnisse zur nächsten Interaktion an das LLM zurück.
LLMEntscheidet, ob Tools angefordert werden sollen (Schleife fortsetzen) oder eine abschließende Antwort erzeugt werden soll (Stopp).
SDKÜbergibt Ereignisse; steuert die Schleife nicht.

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

session.idle Vs session.task_complete

Dies sind zwei verschiedene Abschlusssignale mit sehr unterschiedlichen Garantien:

session.idle

  • Immer ausgegeben wenn die Tool-Nutzungsschleife endet
  • Kurzlebig: Nicht auf dem Datenträger beibehalten, nicht beim Fortsetzen der Sitzung wiedergegeben
  • Bedeutet: "Der Agent hat die Verarbeitung beendet und ist bereit für die nächste Nachricht"
  • Verwenden Sie dies als zuverlässiges "fertiges" Signal

Die Methode des sendAndWait() SDK wartet auf dieses Ereignis:

// Blocks until session.idle fires
const response = await session.sendAndWait({ prompt: "Fix the bug" });

session.task_complete

  • Optional ausgegeben: Erfordert, dass das Modell es explizit signalisiert.
  • Persistent: im Sitzungsereignisprotokoll auf dem Datenträger gespeichert
  • Bedeutet: "Der Agent hält den Gesamtvorgang für erfüllt"
  • Enthält ein optionales summary Feld.
session.on("session.task_complete", (event) => {
    console.log("Task done:", event.data.summary);
});

Autopilot-Modus: Cli-Nudges für task_complete

Im 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:

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

Dadurch wird die Toolverwendungsschleife effektiv neu gestartet– das Modell sieht den Nudge als neue Benutzermeldung und arbeitet weiterhin. Der Nudge weist das Modell auch an, nichttask_complete vorzeitig aufzurufen:

  • Nennen Sie es nicht, wenn Sie offene Fragen haben – treffen Sie Entscheidungen, und arbeiten Sie weiter
  • Rufen Sie die Funktion nicht auf, wenn ein Fehler auftritt – versuchen Sie stattdessen, den Fehler zu beheben.
  • Rufen Sie sie nicht auf, wenn noch Schritte vorhanden sind– führen Sie sie zuerst aus.

Dadurch wird ein zweistufiger Abschlussmechanismus in Autopilot erstellt:

  1. Das Modell ruft task_complete mit einer Zusammenfassung auf → CLI gibt session.task_complete aus → fertig
  2. Das Modell stoppt, ohne es aufzurufen → CLI gibt einen Anstoß → das Modell fährt fort oder ruft task_complete auf

Warum task_complete möglicherweise nicht angezeigt wird

Im 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:

  • Unterhaltungs-F&A: Das Modell beantwortet eine Frage und hält einfach an – es gibt keine diskrete "Aufgabe", die abgeschlossen werden soll.
  • Modell diskretion: Das Modell erzeugt eine endgültige Textantwort, ohne das Task-Complete-Signal aufzurufen.
  • Unterbrochene Sitzungen: Die Sitzung endet, bevor das Modell einen Abschlusspunkt erreicht.

Die 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).

Welche Option sollten Sie verwenden?

AnwendungsfallSignal
"Warten Sie, bis der Agent die Verarbeitung abgeschlossen hat"
session.idle
✅
"Wissen, wann eine Codierungsaufgabe abgeschlossen ist"
session.task_complete (nach bestem Bemühen)
"Timeout/Fehlerbehandlung"
session.idle

session.error ✅ |

Zählen von LLM-Anrufen

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

So überprüfen Sie die Anzahl der Interaktionen einer Sitzung:

# Count turns in a session's event log
grep -c "assistant.turn_start" ~/.copilot/session-state/<sessionId>/events.jsonl

Weiterführende Lektüre