Wie eine Agent Runtime gebaut ist, die man betreiben kann

1. Systemarchitektur

Die Trennung von Control Plane und Data Plane ist keine Stilfrage, sondern eine Betriebsnotwendigkeit. Die Control Plane muss klein, gut gesichert und hochverfügbar sein; sie enthält Entscheidungen, Identitäten und Zustand. Die Data Plane darf groß, austauschbar und volatil sein; sie enthält Rechenlast. Ein Node in der Data Plane kann jederzeit verschwinden, ohne dass ein Lauf verloren geht.

Der Scheduler ist die Komponente, die am häufigsten unterschätzt wird. Er hält kein Ausführungsergebnis, sondern Leases: Ein Worker erhält für einen Lauf ein zeitlich begrenztes Nutzungsrecht und muss es verlängern. Verschwindet der Worker, läuft das Lease ab und ein anderer Worker übernimmt. Genau daraus entsteht die Wiederaufnahme — nicht aus einem Watchdog, der Prozesse beobachtet.

Die Registry hält zwei Arten von Einträgen: MCP-Server mit ihren Werkzeugbeschreibungen und Agent Cards für A2A. Beide sind versioniert und signaturgeprüft. Ein Agent fragt die Registry zur Laufzeit, welche Werkzeuge für seine Identität und seine Aufgabe verfügbar sind — statisch konfigurierte Listen altern zu schnell.

2. Execution-Modell

Ein Agenten-Lauf wird als Zustandsmaschine mit persistiertem Verlauf modelliert. Jeder Schritt erzeugt ein Ereignis, das vor seiner Wirkung geschrieben wird. Der Zustand ist die Faltung aller Ereignisse eines Laufs — keine Variable, die man verlieren kann.

Event-Sourcing und Snapshotting

Reines Event-Sourcing ist für Audits und Replay ideal und für lange Läufe unpraktisch: Wer nach 40 Minuten wieder aufsetzt, will nicht 3.000 Ereignisse einspielen. Deshalb kombinieren wir beides. Das Event Log bleibt die Wahrheit, Snapshots sind eine Beschleunigung. Ein Snapshot wird geschrieben, wenn eine der drei Bedingungen zutrifft: 50 Ereignisse seit dem letzten Snapshot, 60 Sekunden Laufzeit, oder ein Wechsel des Sub-Agenten. Bei der Wiederaufnahme wird der jüngste Snapshot geladen und nur der Rest des Logs eingespielt.

Der Preis dafür ist Speicher, und zwar deutlich mehr, als Teams erwarten. In unseren Messungen liegt das Volumen bei mehrstufigen Läufen mit großen Tool-Rückgaben im Bereich einiger hundert Kilobyte je Lauf. Deshalb werden große Nutzlasten nicht im Ereignis gespeichert, sondern als Referenz auf einen Objektspeicher — das Ereignis enthält Hash, Größe und Schema, nicht den Inhalt.

Idempotenz und Exactly-once

Exactly-once existiert in verteilten Systemen nicht als Eigenschaft der Übertragung, sondern nur als Eigenschaft der Wirkung. Die Runtime erzeugt für jeden Schritt mit Seiteneffekt einen deterministischen Schlüssel aus Lauf-ID, Schrittname und Versuchszähler des Schritts — nicht des Aufrufs. Dieser Schlüssel geht an das Zielsystem. Ist das Zielsystem idempotenzfähig, liefert es beim zweiten Aufruf dasselbe Ergebnis statt einer zweiten Buchung.

Ist es das nicht, bleibt eine Lücke — und die verschweigen wir nicht. In diesem Fall schreibt die Runtime vor dem Aufruf ein tool.attempted-Ereignis mit allen Parametern. Nach einem Absturz sieht die Wiederaufnahme diesen Eintrag ohne zugehöriges Ergebnis und ruft nicht blind erneut auf, sondern folgt der konfigurierten Strategie: nachfragen, prüfen oder eskalieren. Automatisch wiederholt wird nur, was als sicher wiederholbar deklariert ist.

Ausfall mitten im Tool-Call

Der unangenehmste Fall: Der Worker verschwindet, während ein schreibender Aufruf unterwegs ist. Weder Runtime noch Anwendung wissen, ob die Aktion gewirkt hat. Der Ablauf ist dann:

1. Das Lease läuft ab, der Scheduler gibt den Lauf frei.
2. Ein anderer Worker übernimmt, lädt Snapshot und Restlog.
3. Er findet tool.attempted ohne tool.ok oder tool.failed.
4. Bei idempotenzfähigem Ziel: erneuter Aufruf mit demselben Schlüssel. Bei nicht idempotenzfähigem Ziel: Statusabfrage, falls das Werkzeug eine anbietet — sonst Eskalation an einen Menschen.

Der vierte Punkt ist der Grund, warum wir bei der Anbindung von Werkzeugen so hartnäckig auf Idempotenz und Statusabfragen bestehen. Es ist billiger, einen Konnektor sauber zu bauen, als jeden Ausfall manuell aufzulösen.

import { step, ctx } from "@hostspezial/agent-sdk";

// safety: "idempotent" erlaubt automatischen Retry nach Absturz.
// "at-most-once" verbietet ihn — dann entscheidet der Fehlerpfad.
const booking = await step(ctx, "book-credit-note", {
  idempotencyKey: `${ctx.runId}:book-credit-note`,
  safety: "idempotent",
  retry: { attempts: 3, backoff: "exponential" },
  // Wird nach unklarem Abbruch gerufen, bevor erneut ausgefuehrt wird.
  verify: async () => ctx.tools.erp.findCreditNote({ ref: ctx.runId }),
}, () => ctx.tools.erp.createCreditNote({ amount: 189.0, ref: ctx.runId }));

from hostspezial.agents import step, Safety

# safety=IDEMPOTENT erlaubt automatischen Retry nach Absturz.
# AT_MOST_ONCE verbietet ihn — dann entscheidet der Fehlerpfad.
booking = step(
    ctx,
    "book-credit-note",
    idempotency_key=f"{ctx.run_id}:book-credit-note",
    safety=Safety.IDEMPOTENT,
    retry={"attempts": 3, "backoff": "exponential"},
    # Wird nach unklarem Abbruch gerufen, bevor erneut ausgefuehrt wird.
    verify=lambda: ctx.tools.erp.find_credit_note(ref=ctx.run_id),
    fn=lambda: ctx.tools.erp.create_credit_note(amount=189.0, ref=ctx.run_id),
)

3. Context- und Memory-Layer

Der Kontext eines Agenten ist die teuerste und flüchtigste Ressource im System. Wir trennen ihn in drei Schichten mit unterschiedlicher Lebensdauer und unterschiedlichem Zugriffspfad.

Working Memory

Der aktuelle Arbeitskontext eines Laufs: Aufgabe, Zwischenergebnisse, letzte Tool-Rückgaben. Lebt genau so lange wie der Lauf, liegt im Event Log und wird bei jedem Modellaufruf neu zusammengesetzt.

Episodic Memory

Verdichtete Erinnerung an frühere Läufe desselben Vorgangs — etwa alle bisherigen Interaktionen zu einem Ticket. Strukturiert abgelegt und über Schlüssel abgerufen, nicht über Ähnlichkeitssuche.

Semantic Memory

Organisationswissen: Dokumente, Richtlinien, Produktdaten. Abruf über RAG mit Vektordatenbank und Metadatenfilter. Unabhängig vom einzelnen Lauf.

Kompaktierung bei langen Läufen

Ohne Gegenmaßnahme wächst der Kontext monoton, bis er das Fenster sprengt oder unbezahlbar wird. Wir kompaktieren in drei Stufen, jeweils ausgelöst durch einen Schwellwert der Kontextlänge: Erstens werden vollständige Tool-Rückgaben durch Zusammenfassung plus Referenz ersetzt — das Original bleibt im Event Log abrufbar. Zweitens werden abgeschlossene Teilaufgaben zu einem Ergebnisabsatz verdichtet. Drittens, erst dann, greift eine modellgestützte Zusammenfassung des bisherigen Verlaufs.

Die Reihenfolge ist wichtig: Die ersten beiden Stufen sind verlustarm und deterministisch, die dritte kostet Tokens und führt Ungenauigkeit ein. Wer sofort zusammenfassen lässt, verliert Details, die er später braucht.

Vektorsuche oder strukturierter Abruf

Eine Beobachtung aus der Praxis, die vielen Projekten Geld spart: Ein großer Teil dessen, was als RAG gebaut wird, ist in Wahrheit eine Datenbankabfrage. „Alle offenen Rechnungen dieses Kunden“ ist keine Ähnlichkeitssuche, sondern ein SELECT mit zwei Bedingungen. Vektorsuche ist stark bei unstrukturiertem Text und schwach bei Filtern, Aggregationen und Vollständigkeitsgarantien.

Unsere Regel: Strukturiert abfragen, wo es Struktur gibt. Vektorsuche nur für Freitext, dann aber mit Metadatenfilter, damit die Ergebnismenge fachlich begrenzt bleibt. Und immer mit Quellenangabe im Ergebnis, damit der Trace zeigt, worauf sich eine Entscheidung stützt.

Cache-Ökonomie

Prompt-Caching ist der wirksamste einzelne Kostenhebel bei mehrstufigen Läufen — unter einer Bedingung: Der stabile Teil des Kontexts muss am Anfang stehen und zwischen Aufrufen unverändert bleiben. Wir strukturieren den Kontext deshalb streng nach Volatilität: erst Systeminstruktion und Werkzeugbeschreibungen, dann Organisationswissen, dann laufbezogene Fakten, zuletzt der volatile Verlauf. Ein einziges Zeitstempel-Feld an der falschen Stelle zerstört die Cache-Wirkung für den gesamten Lauf.

4. Tool-Layer und MCP

MCP ist der vertikale Bus: ein Agent, viele Werkzeuge. Als Transport nutzen wir Streamable HTTP, weil es Fortschrittsmeldungen bei langsamen Werkzeugen erlaubt und mit vorhandenen Proxys und Firewalls funktioniert.

Entscheidend für die Betriebsqualität ist die Schema-Validierung in beide Richtungen. Eingaben zu prüfen ist selbstverständlich. Ausgaben zu prüfen ist der Punkt, den fast alle Eigenbauten auslassen — obwohl die Rückgabe eines Werkzeugs direkt in den Modellkontext fließt und damit Verhalten beeinflusst. Wir validieren Rückgaben gegen das deklarierte Schema, begrenzen ihre Größe und markieren sie als Daten, nicht als Instruktion.

Die Registry verschiebt Discovery von der Startzeit in die Laufzeit. Der Agent fragt: Welche Werkzeuge gibt es für meine Domäne, die meine Identität nutzen darf? Die Antwort ist gefiltert nach Scopes, Vertrauensstufe und Version. Neue Werkzeuge stehen ohne Deployment zur Verfügung; zurückgezogene verschwinden, ohne tote Verweise zu hinterlassen. Der Preis: Die Werkzeugliste ist nicht mehr statisch überprüfbar — deshalb muss die Eval-Suite auch gegen die Registry laufen.

5. Agent-zu-Agent

A2A ist der horizontale Bus: Agent zu Agent, über Organisationsgrenzen hinweg. Seit das Protokoll unter neutraler Governance der Linux Foundation steht und ACP darin aufgegangen ist, hat sich die Protokoll-Fragmentierung von 2025 weitgehend erledigt — das reduziert das Risiko, auf ein totes Format zu setzen, erheblich.

Ein Agent veröffentlicht seine Selbstbeschreibung als Agent Card unter /.well-known/agent-card.json: Fähigkeiten, Endpunkte, Authentifizierungsverfahren, Betreiber. Wir prüfen die Signatur dieser Karte verpflichtend. Ohne Signatur ist eine Registry angreifbar: Wer einen Eintrag fälscht, lenkt Aufgaben samt Kontext an einen fremden Endpunkt.

Bei der Delegation unterscheiden wir zwei Modi. Streaming liefert Fortschritt und Zwischenergebnisse zurück — passend, wenn ein Mensch zusieht oder Teilergebnisse verwertbar sind. Fire-and-forget mit späterem Callback passt für lange, unbeobachtete Aufgaben. In beiden Fällen gilt: Delegation umfasst zeitlich begrenzte Rechte, nie eine Vollmacht. Der ausführende Schritt bleibt standardmäßig auf unserer Seite, der Partner liefert einen Vorschlag.

6. Identität und Autorisierung

Der Agent ist ein eigener Principal. Er handelt nicht unter dem Konto eines Menschen, sondern mit einer eigenen Kennung, eigenen Scopes und eigener Spur im Audit-Log. Technisch: OAuth 2.1 mit Resource Indicators nach RFC 8707. Das ausgestellte Token gilt für genau ein Zielsystem und ist bei einem anderen wertlos.

Credentials sind kurzlebig — standardmäßig zehn Minuten — und werden je Lauf ausgestellt, nicht je Deployment. Bei Sub-Agenten gilt strikte Teilmengenbildung: Ein Sub-Agent kann nur Scopes erhalten, die der Eltern-Lauf besitzt, und in der Regel weniger. Die Policy Engine lehnt jede Anforderung ab, die diese Regel verletzt — unabhängig davon, was im Prompt steht.

Der praktische Effekt ist die Begrenzung des Blast Radius. Ein kompromittierter Retrieval-Agent kann lesen, was er ohnehin lesen durfte. Er kann keine Gutschrift auslösen, weil er den Scope nie besessen hat und ihn sich auch nicht beschaffen kann. Details unter Agent Identity.

7. Sandboxing und Containment

Jeder nicht selbst gebaute MCP-Server läuft isoliert: eigener Container, kein Zugriff auf das Host-Dateisystem, keine Zugangsdaten anderer Werkzeuge, begrenzter Speicher, begrenzte Laufzeit, keine Persistenz zwischen Aufrufen. Ausgehende Verbindungen sind grundsätzlich blockiert; erlaubt sind nur namentlich gelistete Ziele mit Port.

Das agentische Lieferkettenrisiko hat sich als eigene Kategorie etabliert. Ein MCP-Server, ein Connector oder ein Prompt-Template kann sich zur Laufzeit anders verhalten als deklariert — und die Tool-Beschreibung selbst ist bereits ein Einflusskanal, weil sie im Modellkontext landet. Unsere Maßnahmen: gepinnte Versionen, Signaturprüfung, Egress-Allowlist, Größenbegrenzung von Rückgaben und die konsequente Trennung von Daten und Instruktion im Kontext.

Was das nicht leistet, steht in Abschnitt 11. Kurz: Wir begrenzen den Schaden, wir verhindern nicht jede Beeinflussung.

8. Observability

Jeder Tool-Call, jeder Modellaufruf und jede Freigabe erzeugt einen OpenTelemetry-Span. Die Attribute sind so gewählt, dass Fehlersuche und Audit aus derselben Quelle bedient werden: Agenten-Identität und -Version, Lauf-ID und Schritt, Werkzeugname, sanitisierte Parameter, Policy-Entscheidung, Latenz, Token-Verbrauch, Modell und Routing-Entscheidung, Cache-Treffer, Fehlerklasse.

Sanitisierung geschieht im Collector, nicht in der Anwendung — sonst hängt Datenschutz an der Disziplin einzelner Entwickler. Klartextwerte personenbezogener Felder werden gehasht oder verworfen; Feldnamen, Typen und Wertebereiche bleiben erhalten, weil sie für die Fehlersuche gebraucht werden.

Deterministisches Replay spielt einen Lauf gegen die aufgezeichneten Modell- und Tool-Antworten erneut ab. Das erlaubt drei Dinge: eine Fehlentscheidung reproduzieren, eine Prompt-Änderung gegen einen realen Fall prüfen und eine geänderte Policy gegen die Vergangenheit testen. Die Eval-Suite läuft in der CI; jeder produktive Fehlschlag wird als Fixture aufgezeichnet und zum Testfall. Nach einigen Monaten Betrieb ist diese Sammlung der wertvollste Teil des Projekts.

9. Kostenmodell

Inferenz hat Training als dominante Workload abgelöst. Für die Architektur folgt daraus, dass Kostensteuerung eine Entwurfsentscheidung ist und keine Aufgabe der Buchhaltung. Drei Hebel wirken, in dieser Reihenfolge:

1. Model-Routing. Routine mit einem kleinen Modell, Eskalation zum großen nur bei Unsicherheit oder höherem Einsatz. Die Entscheidung trifft nicht das Modell selbst, sondern eine explizite Regel — sonst eskaliert es zuverlässig immer.
2. Cache-Quote. Kontext nach Volatilität sortieren, damit der stabile Teil zwischen Aufrufen wiederverwendbar bleibt.
3. Kontext-Kompaktierung. Verlustarme Stufen zuerst, modellgestützte Zusammenfassung zuletzt.

Abgerechnet und gesteuert wird nicht der Token, sondern der erfolgreich abgeschlossene Task. Diese Zahl enthält Fehlversuche, Retries und Eskalationen und ist damit die einzige, die sich mit den Kosten des bisherigen manuellen Prozesses vergleichen lässt. Ein Budget-Cap je Lauf verhindert, dass eine Schleife still teuer wird: Bei Erreichen endet der Lauf mit budget_exceeded, der Zustand bleibt einsehbar.

10. Benchmark

Zahlen ohne Methodik sind wertlos, deshalb steht sie hier vollständig. Die folgenden Werte stammen aus einem internen Testaufbau und sind nicht als Zusicherung zu lesen.

Methodik

• Aufbau: drei Worker-Nodes, ein Zustandsspeicher mit synchroner Replikation, Werkzeuge und Modell-Endpunkte im selben Rechenzentrum.
• Last: 1.000 Läufe je Szenario, 20 gleichzeitig, aufgezeichnete reale Eingaben statt synthetischer Prompts.
• Recovery-Messung: harter Abbruch eines Workers zu einem zufälligen Zeitpunkt während eines Laufs; gemessen wird die Zeit bis zum ersten Ereignis nach der Wiederaufnahme, nicht bis zum Laufende.
• Kosten: Modellkosten plus Plattformanteil, ohne einmalige Einrichtung. Fehlversuche sind eingerechnet.
• Nicht gemessen: Wartezeiten auf menschliche Freigaben, Latenz externer Werkzeuge außerhalb des Rechenzentrums, Kaltstart nach längerer Inaktivität.

Wer diese Zahlen für eine Entscheidung braucht, sollte sie nicht glauben, sondern nachmessen — mit den eigenen Werkzeugen und den eigenen Eingaben. Genau dafür ist die Sandbox da.

11. Wofür das nicht gebaut ist

Dieser Abschnitt ist kein Pflichtprogramm, sondern der ehrlichste Teil der Seite. Es gibt Anforderungen, für die diese Architektur die falsche Wahl ist:

Wie es weitergeht

Wenn Sie bis hierher gelesen haben, ist der nächste sinnvolle Schritt kein Gespräch, sondern ein Lauf. Der Quickstart beschreibt den Weg zum ersten eigenen Agenten in fünf Minuten; die Preisseite rechnet vor, was der Betrieb bei Ihrem Volumen kostet. Wer zuerst wissen will, ob das überhaupt die richtige Bauform ist, findet in den Vergleichen die Argumente gegen uns.