Was Sie versionieren, damit sich das Ergebnis eines Agenten später erklären lässt

Nicht nur der Prompt verändert das Verhalten

Teams versionieren meist den Code und manchmal den Prompt. Die übrigen Eingaben verändern sich unbemerkt, obwohl jede das Ergebnis eines Falls beeinflussen kann:

• Die Modellkennung und Einstellungen wie Effort oder Ausgabelimits
• Tool-Beschreibungen, bei denen laut dem Leitfaden von Anthropic zum Schreiben von Tools schon kleine Formulierungsänderungen die Ergebnisse spürbar verschieben können
• Die Tool-Implementierung, etwa ein MCP-Server, der nach eigenem Zeitplan ausgerollt wird
• Geschäftsregeln und Schwellen, oft in einer Konfigurationstabelle, die der Betrieb pflegt
• Ein Suchindex, der jede Nacht neu aufgebaut wird
• Der Workflow-Code, die Framework-Version und die Bewertungslogik der Evals

Ein Manifest pro Release

Sammeln Sie diese Referenzen in einer Datei, die beim Release erzeugt und mit dem Code gespeichert wird. Ihre Kennung wird zur Agentenversion. Das Beispiel ist hypothetisch; Commit-Referenzen und Versionen sind Platzhalter.

agent: invoice-matching
release: 2026.10.3
model:
  id: claude-sonnet-5-5          # exact ID sent to the provider
  settings: {effort: medium, max_tokens: 4000}
prompt: prompts/invoice-agent.md@3f2a91c
examples: examples/invoice-fewshot.jsonl@3f2a91c
tool_descriptions: tools/descriptions.yaml@3f2a91c
tool_servers:
  erp-mcp: 1.8.2
policy: ap-tolerance-policy v4
retrieval_index: supplier-terms build 2026-10-20
workflow_code: 3f2a91c
lockfile: uv.lock@3f2a91c
test_set: invoice-cases v12, passed 2026-10-21

Vermerken Sie das Release an jedem Falldatensatz und jedem Span. Die OpenTelemetry-Semantik-Konventionen für Agenten-Spans enthalten dafür das Attribut gen_ai.agent.version, noch mit dem Status Development. Halten Sie die genaue Modellkennung fest, die Sie senden. Die Modellübersicht von Anthropic sagt zum Beispiel, dass jede aktuelle Claude-Modell-ID ein festgelegter Snapshot ist, und nennt zugleich Termine für die Abschaltung, ein weiterer Grund, sich nicht darauf zu verlassen, eine alte Version später erneut auszuführen.

Rekonstruktion ist kein Replay

Um einen Fall später zu erklären, brauchen Sie das Release, die Eingaben so, wie der Agent sie gelesen hat, jeden Tool-Aufruf mit Ergebnis, die Modellausgaben und alle menschlichen Entscheidungen. Checkpoints helfen dabei. In LangGraph enthält jeder Checkpoint die Zustandswerte, Metadaten, einen Zeitstempel und einen Verweis auf den vorherigen Checkpoint, und get_state_history listet sie für einen Thread auf.

Ein Replay ist etwas anderes. Dieselbe Dokumentation erklärt, dass das Fortsetzen ab einem früheren Checkpoint die späteren Knoten erneut ausführt, einschließlich Modellaufrufen und API-Anfragen; es entsteht also ein neuer Lauf gegen die heutigen Systeme. Nutzen Sie die gespeicherte Aufzeichnung, um die Vergangenheit zu erklären, und neue Läufe gegen das aktuelle Release für Regressionstests. Beachten Sie auch, dass die Persistenz-Dokumentation von LangGraph empfiehlt, Checkpoints zu bereinigen oder eine Aufbewahrungsregel festzulegen; die für Erklärungen nötige Aufbewahrung muss daher bewusst entschieden werden.

Fälle, die über ein Release hinweg laufen

Ein Fall, der am Montag auf eine Freigabe wartet, wird womöglich nach dem Release am Mittwoch fortgesetzt. Durable-Workflow-Engines behandeln das als bekanntes Problem. Die Temporal-Dokumentation erklärt, dass Workflow-Code für das Replay deterministisch sein muss, dass das Hinzufügen, Entfernen oder Umordnen bestimmter Schritte ohne Versionierung bei laufenden Workflows zu einem Nichtdeterminismus-Fehler führt und dass Worker Versioning und Patching für solche Änderungen bereitstehen.

Unabhängig vom Framework brauchen Sie eine Regel: Laufende Fälle werden entweder mit dem Release abgeschlossen, mit dem sie begonnen haben, oder über eine ausdrückliche Migration ihres gespeicherten Zustands auf das neue überführt. Vermerken Sie das Release an jedem Schritt, nicht nur am Fall, damit sich auch ein gemischter Fall erklären lässt.

Häufige Lücken

Die Lücken liegen meist außerhalb des Haupt-Repositorys: ein Prompt, der in einer Anbieterkonsole bearbeitet wird, ein Tool-Server, den ein anderes Team ausrollt, eine in der Datenbank geänderte Schwelle, ein über Nacht aktualisierter Index. Jede davon gehört entweder ins Manifest oder wird pro Fall mit dem verwendeten Wert festgehalten. Behandeln Sie jede Änderung an einem Eintrag im Manifest als Release, das durch das Testset läuft. Ein nützlicher erster Schritt: Schreiben Sie das Manifest für den Agenten, den Sie heute betreiben, und markieren Sie jedes Feld, das Sie nicht ausfüllen können.