Sollten lang laufende KI-Agenten ihren Fortschritt protokollieren? Heartbeats gegen die Frage „Ist das Ding stehen geblieben?“

Bei langen KI-Aufgaben ist nicht unbedingt der Fehler das Unheimlichste. Es ist die Stille.

Ein Mensch kann Haushalt erledigen, einkaufen, essen und zurückkommen – die KI zeigt immer noch „in Arbeit“. Dann gibt es zwei sehr unterschiedliche Möglichkeiten:

1. Sie führt gewissenhaft eine riesige Testsuite aus.
2. Sie ist vor Stunden irgendwo hängen geblieben.

Ein Ladeindikator kann das nicht unterscheiden. Auch fehlende Commits beweisen keinen Stillstand: Tests, Recherche, Vergleiche, Generierung oder externe Wartezeiten können lange ohne sichtbares Artefakt bleiben.^[1]

Darum braucht lang laufende KI neben Intelligenz noch etwas anderes: Observability, also beobachtbaren Betriebszustand.

1. Fazit――wenn eine Aufgabe länger dauern kann, sollte ihr aktueller Standort sichtbar sein

Ein lang laufender Agent sollte nicht nur am Ende Bericht erstatten. Auch der Zwischenzustand sollte lesbar sein.^[1]

Er muss nicht jede Minute „ich lebe noch“ melden. Wichtig ist, dass man erkennen kann:

• Woran arbeitet er gerade?
• Was ist fertig?
• Was bleibt übrig?
• Läuft gerade ein Test?
• Gibt es einen Blocker?
• Wann wurde Aktivität zuletzt bestätigt?
• Wann gab es zuletzt eine materielle Änderung?

Ein praktisches Konfigurationsbeispiel: Nach ungefähr 10 Minuten ohne sichtbares Artefakt wird ein Heartbeat aktualisiert; ist der Heartbeat älter als 20 Minuten, wird der Zustand als STALE_UNKNOWN gelesen, nicht automatisch als „gestoppt“.^[1]

Stille bedeutet zuerst „unbekannt“, nicht „fehlgeschlagen“.

2. Warum die Commit-Historie allein nicht reicht

Git-Commits sind hervorragende Belege für materielle Änderungen, aber schwache alleinige Belege für aktuelle Aktivität.

Eine einstündige Regression-Suite kann völlig gesund laufen, ohne einen einzigen Commit zu erzeugen. Umgekehrt verschmutzt ein nutzloser Heartbeat-Commit alle zehn Minuten nur die Historie.^[1]

Darum trennen:

Heartbeat = aktueller Zustand Material change = Beleg dafür, dass Code, Verträge, Artefakte oder Verifikation wirklich geändert wurden

Mit getrennten Feldern wie lastHeartbeatAt und lastMaterialChangeAt lässt sich „30 Minuten kein Commit, aber vor 5 Minuten TESTING-Heartbeat“ korrekt verstehen.^[1]

Das Ziel sind nicht mehr Commits, sondern interpretierbare Stille.

3. Was sollte mindestens protokolliert werden?

Für einen langen Run sind diese Felder hilfreich:^[1]

• runId
• state: RUNNING / BLOCKED / COMPLETED / STALE_UNKNOWN usw.
• phase: READING / IMPLEMENTING / TESTING / VERIFYING usw.
• workingOn
• startedAt
• lastHeartbeatAt
• lastMaterialChangeAt
• branch / baseSha / headSha / PR
• completedMilestones / remainingMilestones
• blockers
• tests
• nextCheckpoint

Damit ist ein Sechs-Stunden-Job nicht mehr „eine sechs Stunden lange Blackbox“, sondern lesbar als:

IMPLEMENTING → TESTING → INTEGRATING → VERIFYING

Eine sehr intelligente Blackbox bleibt eine Blackbox. Nach ein paar Stunden macht das Menschen nervös.

4. Während Tests sind Heartbeats besonders wichtig

Ein langer Test sieht von außen fast genauso aus wie ein eingefrorener Agent.

Vor einem langen Test sollten protokolliert werden:^[1]

• phase = TESTING
• Name der Testsuite
• Umfang
• ein objektiver Zähler wie 84 / 127, wenn die Gesamtzahl feststeht
• ob bereits ein Fehler aufgetreten ist

Frei erfundene Prozente wie „82 % fertig“ bei Design oder Debugging sollte man vermeiden. Niemand weiß, was die restlichen 18 % eigentlich bedeuten.

Prozente sind sinnvoll, wenn der Nenner objektiv feststeht:

• 84 / 127 tests
• 3 / 5 acceptance gates

„Implementierung zu 82 % fertig“ ist die KI-Version von „bin gleich da“ von jemandem, der vielleicht noch zu Hause sitzt.

5. „Ist es stehen geblieben?“ stufenweise lesen

Eine praktische Heartbeat-Policy kann die Aktualität so einteilen:^[1]

Alter	Interpretation
0–10 Minuten	CURRENT
10–20 Minuten	HEARTBEAT_OVERDUE
Mehr als 20 Minuten	STALE_UNKNOWN

STALE_UNKNOWN ist nicht FAILED.

Danach in dieser Reihenfolge prüfen:

1. aktuellen Fortschrittseintrag
2. Check / Status
3. branch / PR
4. letzten Commit
5. erst zuletzt schätzen

Ist der Heartbeat alt, erscheint aber danach ein neuer PR oder Commit, hat der Agent oft weitergearbeitet und nur die Statusmeldung vergessen.

Auch KI kann den Klassiker: Arbeit erledigt, Stundenzettel vergessen.

6. Diese Fehler beim Fortschrittsmanagement vermeiden

Keine Heartbeat-only-Commits auf main

Sie verschmutzen die Historie, erhöhen Konflikte und können unnötige CI- oder Deploy-Vorgänge auslösen. Besser sind veränderbare leichte Oberflächen wie Issue-Kommentar, Check, Status oder ein nicht-produktiver Ops-Bereich.^[1]

Nicht für jeden Heartbeat einen neuen Kommentar erzeugen

Ein veränderbarer Datensatz pro Run ist deutlich lesbarer. Alle zehn Minuten ein neuer Kommentar macht Fortschrittskontrolle zur Archäologie.^[1]

Stille nicht sofort mit Fehler gleichsetzen

Ist nur der Heartbeat alt, verwende STALE_UNKNOWN. Ein Fehlerzustand braucht positive Fehlerbelege.^[1]

Keine Geheimnisse in Fortschrittslogs

Keine API-Keys, Tokens, Passwörter, privaten URLs, rohen privaten Chats, personenbezogenen Daten oder vertraulichen Dateien.^[1]

Sichere Arbeit nicht stoppen, nur weil Observability ausfällt

Wenn die Progress-API ausfällt, auf einen anderen Sink wechseln und unabhängige sichere Arbeit fortsetzen.^[1]

7. Praktisches Template

State: RUNNING
Phase: TESTING

Run ID: agent-20260916-long-task
Started: 10:00
Last heartbeat: 14:05
Last material change: 13:42

Branch: feat/long-task
Head SHA: abc1234
PR: #123

Working on:
- regression tests

Completed:
- runtime implementation
- contract update

Remaining:
- regression completion
- merge verification
- production readback

Blockers:
- none

Tests:
- 84 / 127 passed so far
- no failure observed

Next checkpoint:
- finish regression, then integration

Damit wird aus „Ist es stehen geblieben?“ ein „Okay, es testet gerade“.

Fortschrittssichtbarkeit soll die KI nicht primär unter Druck setzen. Sie verhindert, dass Menschen aus Unsicherheit neu starten, unterbrechen oder dieselben Anweisungen doppelt senden.

8. Zusammenfassung――Intelligenz und Sichtbarkeit getrennt entwerfen

Bei lang laufender KI muss man unterscheiden:^[1]

• kein Commit ≠ gestoppt
• Heartbeat ≠ materieller Fortschritt
• alter Heartbeat ≠ Fehler
• ein Blocker ≠ globaler Stillstand
• Stille beim Test ≠ eingeschlafen

Wenn eine KI sechs Stunden arbeiten kann, sollte ein Mensch sie nicht sechs Stunden beobachten müssen.

Das bessere Design lautet: Wenn man zurückkommt, sieht man sofort, wo sie gerade steht.

Der ideale Langzeit-Agent ist nicht der Agent, der ununterbrochen redet.

Er arbeitet ruhig – aber sobald man hinschaut, ist seine Position klar.

---

Quellen (1)

1. docs/article-pipeline/agent-work-observability.md — internal operational design for long-running AI progress observability, heartbeat cadence, stale classification, testing visibility, privacy, concurrency, and terminal conditions. Updated 2026-09-15