# Die Agentenschleife

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

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

## Aufbau

![Diagramm: Graphdiagramm, das den beschriebenen Prozess darstellt.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-0.png)

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.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png)

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:

| Drehung                 | Funktionsweise des Modells                              | toolRequests? |
| ----------------------- | ------------------------------------------------------- | ------------- |
| 1                       | Aufrufe `grep` und `glob` Zum Durchsuchen der Codebasis |               |
| ✅ Ja                    |                                                         |               |
| 2                       | Liest bestimmte Dateien basierend auf Suchergebnissen   |               |
| ✅ Ja                    |                                                         |               |
| 3                       | Liest weitere Dateien für tieferen Kontext              |               |
| ✅ Ja                    |                                                         |               |
| 4                       | Erzeugt 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.](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png)

## Wer löst jede Drehung aus?

| Actor (Schauspieler) | Verantwortung                                                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Ihre App**         | Sendet die erste Eingabeaufforderung über `session.send()`                                                                         |
| **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.          |
| **LLM**              | Entscheidet, 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:

```typescript
// 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.

```typescript
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, **nicht**`task_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?

| Anwendungsfall                                                 | Signal |
| -------------------------------------------------------------- | ------ |
| "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:

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

## Weiterführende Lektüre

* [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
* [Wiederaufnahme und Persistenz der Sitzung](/de/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/session-persistence): Wie Sitzungen gespeichert und fortgesetzt werden
* [Arbeiten mit Hooks](/de/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/hooks): Abfangen von Ereignissen in der Schleife (Berechtigungen, Werkzeuge)