Zum Hauptinhalt springen
Die Todo-Verfolgung bietet eine strukturierte Möglichkeit, Aufgaben zu verwalten und Benutzer über den Aufgabenfortschritt zu informieren. Das Claude Agent SDK enthält integrierte Todo-Funktionalität, die dabei hilft, komplexe Arbeitsabläufe zu organisieren und Benutzer über die Aufgabenprogression zu informieren.
Ab TypeScript Agent SDK 0.3.142 und Claude Code v2.1.142 verwenden Sitzungen die strukturierten Task-Tools TaskCreate, TaskUpdate, TaskGet und TaskList anstelle von TodoWrite. Das Python SDK erhält diese Änderung von der Claude Code CLI, die es startet, nicht von der Python-Paketversion: Der Wechsel gilt, sobald diese CLI — die im pip-Paket enthaltene Kopie oder eine, auf die Sie mit cli_path verweisen — v2.1.142 oder später ist. Siehe Zu Task-Tools migrieren für Informationen darüber, wie sich der Überwachungscode ändert. Die Beispiele auf dieser Seite setzen CLAUDE_CODE_ENABLE_TASKS=0, um weiterhin TodoWrite für Sitzungen anzuzeigen, die noch nicht migriert wurden.

Todo-Lebenszyklus

Todos folgen einem vorhersehbaren Lebenszyklus:
  1. Erstellt als pending, wenn Aufgaben identifiziert werden
  2. Aktiviert zu in_progress, wenn die Arbeit beginnt
  3. Abgeschlossen, wenn die Aufgabe erfolgreich beendet wird
  4. Entfernt, wenn alle Aufgaben in einer Gruppe abgeschlossen sind

Wann Todos verwendet werden

Das SDK erstellt Todos für die meisten mehrstufigen Arbeiten, wie zum Beispiel:
  • Komplexe mehrstufige Aufgaben, die 3 oder mehr unterschiedliche Aktionen erfordern
  • Von Benutzern bereitgestellte Aufgabenlisten, wenn mehrere Elemente erwähnt werden
  • Nicht triviale Operationen, die von der Fortschrittsverfolgung profitieren
  • Explizite Anfragen, wenn Benutzer um Todo-Organisation bitten
Es kann Todos für sehr kurze oder einstufige Anfragen überspringen.

Beispiele

Bevor Sie diese Beispiele ausführen, installieren Sie das Claude Agent SDK, indem Sie dem Schnellstart folgen. Jedes Beispiel wird ausgeführt, bis der Agent fertig ist und seine endgültige Ergebnismeldung liefert. Wenn eine Sitzung zuerst ihr Turnus-Limit erreicht, hat diese Ergebnismeldung den Subtyp error_max_turns. Überprüfen Sie subtype, um dieses Ende zu erkennen. Diese Beispiele verwenden Single-Shot-query()-Aufrufe. Nach dem Liefern eines error_max_turns-Ergebnisses wirft query() einen Fehler aus, der Reached maximum number of turns enthält. Jedes Beispiel umhüllt seine Schleife in einem Try-Block, um sauber zu beenden, wenn dies geschieht. Siehe Handle the result für die Ergebnis-Subtypen.

Überwachung von Todo-Änderungen

Echtzeit-Fortschrittsanzeige

Zu Task-Tools migrieren

Die Task-Tools teilen den einzelnen TodoWrite-Aufruf in TaskCreate für jedes neue Element und TaskUpdate für jede Statusänderung auf, wobei TaskList und TaskGet für das Modell verfügbar sind, um die aktuelle Liste zu lesen. Ihr Überwachungscode inspiziert weiterhin tool_use-Blöcke im Assistent-Stream, verwaltet aber eine Zuordnung mit Task-ID als Schlüssel, anstatt die gesamte Liste bei jedem Aufruf zu ersetzen. Die Task-Tools sind ab TypeScript Agent SDK 0.3.142 und Claude Code v2.1.142 die Standardeinstellung, daher ist keine Änderung von options.env erforderlich. Die zugewiesene Task-ID befindet sich nicht in der TaskCreate-Eingabe. Sie kommt im entsprechenden tool_result als { task: { id, subject } } zurück, daher erfassen Sie sie aus dem Ergebnis-Block, um Ihre Zuordnung zu schlüsseln. Das folgende Beispiel zeigt die minimale Änderung an der Schleife Überwachung von Todo-Änderungen. Es liest nur tool_use-Eingaben und überspringt das Erfassen von IDs aus tool_result-Blöcken. Um eine vollständige Liste zu rendern, beobachten Sie ein TaskList-Tool-Ergebnis im Stream oder sammeln Sie TaskCreate-Ergebnisse und TaskUpdate-Eingaben in einer Zuordnung. Der gestreamte tool_use-Input ist die rohe Form, die das Modell ausgegeben hat. Claude Code repariert einige nahezu korrekte, aber fehlerhafte Schlüsselnamen vor der Ausführung, indem es id oder task_id auf taskId und active_form auf activeForm abbildet, aber diese Reparatur wird nicht im Stream widergespiegelt. Lesen Sie TaskUpdate-Eingabefelder defensiv, wie die folgenden Beispiele zeigen, anstatt anzunehmen, dass der kanonische Name immer vorhanden ist.