ADR-008: Prozessarchitektur des Agenten

• Status: Angenommen
• Datum: 2026-03-24
• Verfeinert durch: ADR-0010 (Lifecycle-Modul als alleiniger Status-Writer), ADR-0014 (Step-Modul-Schleife des Walkers; Schritt plan gestrichen)

Kontext

Die Agent Pipeline verarbeitet eingehende Nachrichten in fünf Schritten: Security-Scan, Kontextabruf, Klassifikation, Entwurfserstellung und Routing. Dies sind die Mitglieder der Union AgentStepKind in apps/api/convex/agent/steps/types.ts (security_scan, context_retrieval, classify, draft, route). Ein eigenständiger Schritt zur „Aktionsplanung“ existierte in einem frühen Entwurf, wurde aber mit ADR-0014 vor der Produktivsetzung gestrichen — der Klassifikator wechselte nie in ihn, und der Drafter schrieb eine plan-Zeile, deren Payload lediglich literale JSON-Konstruktion war.

Die einfachste Implementierung wäre eine einzelne Funktion, die alle fünf Schritte nacheinander ausführt. Das schafft jedoch Probleme:

1. Kein partieller Retry — schlägt die Entwurfserstellung fehl (LLM-Timeout, Rate Limit), startet die gesamte Pipeline erneut beim Security-Scan und verschwendet LLM-Aufrufe.
2. Keine Nebenläufigkeit — eine lang laufende Pipeline blockiert den Start der nächsten Nachricht. Eine 10 Sekunden dauernde Entwurfserstellung verzögert alle nachfolgenden Nachrichten.
3. Kein Zustand pro Schritt — Security-Ergebnisse, Klassifikation und Entwurf müssen jeweils an ihrer eigenen Grenze persistiert werden, damit ein Absturz mitten in der Pipeline keine fertige Arbeit verliert.
4. Keine Observability — eine monolithische Funktion liefert eine einzige Zeitmetrik, keine Aufschlüsselung pro Schritt.

Das Serverless-Modell von Convex unterstützt unabhängige Funktionsausführung von Haus aus — eine internalAction kann eingeplant werden, sich selbst neu einplanen und läuft in einem eigenen, transaktionsfreien Kontext, während Mutations atomare Schreibvorgänge bieten. Die Architektur trennt genau entlang dieser Linie: Die LLM-/Rechenarbeit liegt in Actions, und jeder Datenbankschreibvorgang, der die Zustandsmaschine antreibt, liegt in einer einzigen Mutation.

Entscheidung

Eingehende Nachrichten mit einem sich selbst einplanenden Step-Walker (einer internalAction) plus einem Lifecycle-Koordinator (einer internalMutation) verarbeiten. Der Walker führt die Rechenarbeit pro Schritt aus; der Koordinator besitzt jeden Schreibvorgang auf der Zustandsmaschine.

Wie eine Nachricht fließt

Der Walker trägt den input des nächsten Schritts direkt weiter — es gibt keinen gemeinsamen Akkumulator (ADR-0014, Entscheidung D1). Der Lifecycle ist das einzige Modul, das processingStatus anfasst, sodass ein Absturz zwischen dem Status-Patch und dem Schreibvorgang pro Schritt keine halb aktualisierte Zeile mehr hinterlassen kann.

Warum zwei Module statt einer großen Action

Manche Schritte laufen innerhalb eines einzelnen processingStatus statt an einer Zustandsgrenze — zum Beispiel laufen context_retrieval und classify beide, während die Nachricht im Zustand classifying ist. recordStepBegin / recordStepEnd / recordStepFail aus transition herauszulösen erlaubt es jedem Schritt, seine eigene agentAction-Zeile atomar zu markieren, ohne dass der Lifecycle wissen muss, welcher Schritt gerade läuft — und behält zugleich einen einzigen Eigentümer für processingStatus selbst.

Retry-Semantik

Retry ist über alle Schrittarten hinweg einheitlich, nicht pro Schritt differenziert. Es gibt kein exponentielles Backoff und keinen Retry-Zähler pro Typ.

• Bei jeder Ausnahme in execute oder route eines Schritts überführt der Walker die Nachricht nach failed und markiert die laufende agentAction mit errorMessage als fehlgeschlagen (apps/api/convex/agent/walker.ts).
• Ein Cron — retry failed agent actions, alle 5 Minuten (apps/api/convex/crons.ts) — ruft internal.inbox.processingLifecycle.retryFailedActions auf. Diese Mutation nimmt fehlgeschlagene agentActions, deren retryCount < maxRetries ist (wobei maxRetries = 3 für jede Schrittart gilt), setzt jede auf pending zurück und bringt die zugehörige Nachricht zurück auf received, sodass der Walker die Pipeline ab security_scan erneut durchläuft.
• Sobald retryCount den Wert 3 erreicht, bleibt die Action failed und die Nachricht verbleibt in ihrem Zustand failed, damit ein Mensch sie prüfen kann.

Verzweigung bei mehreren Intents

Konsequenzen

Ermöglicht:

• Unabhängiger Retry pro Schritt — ein fehlgeschlagener Schritt wird vom Cron zurückgesetzt und erneut ausgeführt; davor abgeschlossene Schritte behalten ihre persistierte Ausgabe.
• Nebenläufige Verarbeitung — der Walker jeder Nachricht plant unabhängig ein, sodass im Deployment mehrere Nachrichten gleichzeitig verarbeitet werden.
• Observability pro Schritt — jeder Schritt schreibt eine agentActions-Zeile mit status, durationMs, modelUsed und tokenUsage.
• Absturzsicherer Zustand — weil der Lifecycle-Koordinator der alleinige Writer von processingStatus ist und Begleitfelder in derselben Mutation patcht, kann ein Absturz keine Diskrepanz zwischen Status und Daten hinterlassen.

Abwägungen:

• Der Zustand liegt über zwei Tabellen verteilt — die Zustandsmaschine auf Nachrichtenebene ist inboundMessages.processingStatus (siehe apps/api/convex/schema/inbox.ts), das Tracking pro Schritt liegt in agentActions-Zeilen (status, retryCount, durationMs, modelUsed, tokenUsage). Es gibt kein einzelnes stepTimings-Blob — Zeiten pro Schritt liest man, indem man die agentActions einer Nachricht zusammenführt.
• Die Koordinatorlogik erhöht die Komplexität gegenüber einer einfachen sequenziellen Funktion — der Graph der zulässigen Kanten und der Effekt-Reducer müssen sorgfältig getestet werden, damit keine Nachrichten hängen bleiben.
• Geringfügig höhere Latenz als bei einem einzigen Funktionsaufruf, bedingt durch den Scheduling-Overhead zwischen den Schritten (jedes runStep reiht das nächste neu ein).

Verwandt