Agent Patterns

Budgetkontrolle für KI-Agenten: Wie man Ausgaben in Runtime begrenzt

Praktische Budgetkontrolle in Production: max_steps, max_seconds, max_tool_calls, max_usd, stop reasons, audit logs und alerting.
Auf dieser Seite
  1. Idee in 30 Sekunden
  2. Problem
  3. Lösung
  4. Budget Controls != Rate Limiting
  5. Metriken der Budgetkontrolle
  6. So sieht das in der Architektur aus
  7. Beispiel
  8. Im Code sieht das so aus
  9. So sieht das während der Ausführung aus
  10. Typische Fehler
  11. Selbst-Check
  12. FAQ
  13. Wo Budget Controls im Gesamtsystem liegen
  14. Verwandte Seiten

Idee in 30 Sekunden

Budget controls sind Runtime-Limits, die einen Run stoppen, wenn der Agent Grenzen bei Schritten, Zeit, Tool-Aufrufen oder Kosten überschreitet.

Wann das nötig ist: wenn der Agent externe Tools aufruft, Aktionen retryen kann und mit realem Budget in Production arbeitet.

Problem

Ohne Budgets gerät ein Agent in Production leicht in eine Schleife: mehr Schritte, mehr Tool-Aufrufe, mehr Kosten. Im Demo sieht man das kaum, weil die Last klein ist. In Production wird dieses Verhalten schnell zu einem Incident.

Eine instabile Tool-Antwort startet oft eine Kette: Retry -> neuer Tool-Aufruf -> mehr Tokens -> noch ein Retry. Ohne harte Runtime-Grenze läuft der Run länger und teurer als geplant.

Analogie: das ist wie eine Fahrt ohne Limit auf dem Firmen-Taxi-Account. Solange die Fahrt kurz ist, wirkt alles normal. Wenn sich die Route zieht, steigen die Kosten unbemerkt bis zur Abrechnung.

Lösung

Die Lösung ist, Budget-Prüfungen in die Runtime-Policy-Layer auszulagern. Jeder Agent-Schritt wird gegen vier Limits geprüft: max_steps, max_seconds, max_tool_calls, max_usd.

Die Policy-Layer liefert eine technische Entscheidung: allow oder stop mit explizitem Grund (max_steps, max_seconds, max_tool_calls, max_usd). Diese Entscheidung wird bei jedem Schritt getroffen, nicht nur am Ende des Runs. Das ist eine eigene Systemebene, nicht Teil von Prompt oder Modelllogik.

Budget Controls != Rate Limiting

Das sind unterschiedliche Kontroll-Ebenen:

  • Rate limiting begrenzt die Anfragefrequenz an ein System oder Tool.
  • Budget controls begrenzen die Gesamtkosten eines einzelnen Runs.

Eines ohne das andere funktioniert nicht:

  • ohne budget controls kann ein einzelner Run zu teuer werden
  • ohne rate limiting können viele Runs Abhängigkeiten überlasten

Beispiel:

  • rate limit: nicht mehr als 10 Anfragen pro Minute an search_api
  • budget controls: nicht mehr als max_tool_calls=12 und max_usd=1.00 pro Run

Metriken der Budgetkontrolle

Diese Metriken und Signale wirken bei jedem Agent-Schritt zusammen.

MetrikWas sie kontrolliertWichtige MechanikenWarum
Step budgetRun-Länge in Schrittenmax_steps
stop reason max_steps		Stoppt Schleifen bevor Kosten wachsen
Time budgetRun-Dauer in Sekundenmax_seconds
wall-clock timeout		Verhindert, dass lange Runs Ressourcen blockieren
Tool-call budgetAnzahl der Tool-Aufrufemax_tool_calls
Limit pro Run		Begrenzt Tool-Spam und Retry-Ketten
Spend budgetGeldausgaben pro Runmax_usd
usage-Berechnung		Setzt eine harte finanzielle Grenze
Observability (budget)Sichtbarkeit von Budget-Entscheidungenaudit logs
alerts (Slack / PagerDuty)		Begrenzt Aktionen nicht direkt, hilft aber Überziehungen schnell zu finden und zu erklären

Beispiel für alert:

Slack: 🛑 Agent Support-Bot hit max_usd limit ($100). Run stopped at step 12.

So sieht das in der Architektur aus

Die Budget-Policy-Layer steht zwischen Runtime und Aktionsausführung und prüft Limits vor jedem Schritt. Jede Entscheidung (allow oder stop) wird im audit log gespeichert.

Jeder Agent-Schritt geht vor Ausführung durch diesen Flow: Runtime führt keine Aktion direkt aus — zuerst Budget-Prüfung, dann Ausführung.

Kurz zum Flow:

  • Runtime aktualisiert usage (Schritte, Zeit, Tool-Aufrufe, Kosten)
  • Budget-Policy-Layer prüft Limits
  • allow -> der nächste Schritt wird ausgeführt
  • stop -> stop reason und partial response werden zurückgegeben
  • beide Entscheidungen werden in audit log geschrieben

Beispiel

Ein Support-Agent bearbeitet eine Anfrage und ruft wegen einer instabilen API wiederholt refund.lookup auf.

Mit budget controls:

  • max_tool_calls = 8
  • max_seconds = 45
  • max_usd = 1.00

-> der Run wird beim Erreichen des Limits gestoppt, nicht erst nach unkontrolliertem Kostenwachstum.

Budget controls stoppen den Incident auf Ausführungsebene, statt darauf zu hoffen, dass das Modell selbst stoppt.

Im Code sieht das so aus

Im vereinfachten Schema oben ist der zentrale control flow gezeigt. In der Praxis wird der Budget-Check oft zweimal ausgeführt: vor der Schrittausführung und nach dem Update des tatsächlichen usage. Der Schrittzähler wird vor der Prüfung erhöht, damit der aktuelle Schritt im Budget erfasst wird.

PYTHON
usage.update(step=1)

decision = budget.check(usage, limits)
if not decision.allowed:
    audit.log(run_id, decision.outcome, reason=decision.reason, usage=usage.snapshot())
    alerts.notify_if_needed(run_id, decision.reason, usage.snapshot())
    return stop(decision.reason)

result = tool.execute(args)
usage.update(tool_call=1, usd=result.cost_usd)

decision = budget.check(usage, limits)
if not decision.allowed:
    audit.log(run_id, decision.outcome, reason=decision.reason, usage=usage.snapshot())
    alerts.notify_if_needed(run_id, decision.reason, usage.snapshot())
    return stop(decision.reason)

audit.log(run_id, decision.outcome, reason=decision.reason, usage=usage.snapshot(), result=result.status)
return result

So sieht das während der Ausführung aus

TEXT
Szenario 1: Limit erreicht (stop)

1. Runtime beendet Schritt 9 und aktualisiert das tatsächliche usage.
2. Budget policy sieht, dass max_usd überschritten ist.
3. Entscheidung: stop (max_usd).
4. Audit: decision=stop, reason=max_usd, step=9.
5. Der Nutzer erhält eine partial response mit stop reason.

---

Szenario 2: Limit nicht erreicht (allow)

1. Runtime startet Schritt 4 und aktualisiert usage.
2. Budget policy prüft Limits: alles im Rahmen.
3. Entscheidung: allow.
4. Tool-Aufruf wird ausgeführt.
5. Audit: decision=allow, usage aktualisiert, Ergebnis zurückgegeben.

Typische Fehler

  • nur Tokens begrenzen und max_seconds, max_tool_calls sowie max_usd ignorieren
  • Budgets nur "am Ende" prüfen, nicht vor jedem Schritt
  • keinen expliziten stop reason an Nutzer zurückgeben
  • Budgetlogik über Runtime, Tools und UI verteilen
  • budget decisions (allow / stop) nicht im audit trail loggen
  • kein alerting auf max_usd und max_tool_calls

Im Ergebnis wirkt das System stabil, verliert unter Last aber schnell die Vorhersagbarkeit.

Selbst-Check

Schneller budget-controls Check vor dem Production-Start:

Fortschritt: 0/8

⚠ Grundlegende Governance-Kontrollen fehlen

Vor production brauchen Sie mindestens Zugriffskontrolle, Limits, audit logs und einen Not-Stopp.

FAQ

Q: Reicht ein token budget allein?
A: Nein. Tools können mehr kosten als Tokens. Minimum: max_steps, max_seconds, max_tool_calls, max_usd.

Q: Was zuerst einführen: max_steps oder max_usd?
A: Starte mit max_steps und max_tool_calls, um Schleifen sofort zu stoppen. Danach ergänze max_usd als finanzielle Grenze.

Q: Was soll der Nutzer bei budget stop erhalten?
A: Partial response + expliziter stop reason + kurze Next-Step-Hilfe (Anfrage eingrenzen oder mit höherem Budget erneut starten).

Q: Brauchen wir Budgets pro Tenant?
A: Ja. Unterschiedliche Tarife oder Teams brauchen unterschiedliche Limits, aber die Prüfmechanik sollte gleich bleiben.

Q: Ersetzen budget controls rate limiting?
A: Nein. Rate limiting schützt Abhängigkeiten vor Peaks, budget controls schützen den Run vor runaway-Kosten.

Wo Budget Controls im Gesamtsystem liegen

Budget controls sind eine der Ebenen von Agent Governance. Zusammen mit RBAC, execution limits, approval und audit bilden sie ein einheitliches Ausführungskontrollsystem.

Verwandte Seiten

Weiter zum Thema:

Weiterlesen
Human Approval für KI-Agenten: Wie man write-Aktionen sicher kontrolliert
⏱️ 6 Min. Lesezeit • Aktualisiert 25. März 2026Schwierigkeit: ★★★
In OnceOnly umsetzen
Budgets + permissions you can enforce at the boundary.
In OnceOnly nutzen
# onceonly guardrails (concept)
version: 1
budgets:
  max_steps: 25
  max_tool_calls: 12
  max_seconds: 60
  max_usd: 1.00
policy:
  tool_allowlist:
    - search.read
    - http.get
writes:
  require_approval: true
  idempotency: true
controls:
  kill_switch: { enabled: true }
Integriert: Production ControlOnceOnly
Guardrails für Tool-Calling-Agents
Shippe dieses Pattern mit Governance:
  • Budgets (Steps / Spend Caps)
  • Tool-Permissions (Allowlist / Blocklist)
  • Kill switch & Incident Stop
  • Idempotenz & Dedupe
  • Audit logs & Nachvollziehbarkeit
OnceOnly testenDoku & Beispiele
Integrierter Hinweis: OnceOnly ist eine Control-Layer für Production-Agent-Systeme.

Autor

Nick — Engineer, der Infrastruktur für KI-Agenten in Produktion aufbaut.

Fokus: Agent-Patterns, Failure-Modes, Runtime-Steuerung und Systemzuverlässigkeit.

🔗 GitHub: https://github.com/mykolademyanov

Redaktioneller Hinweis

Diese Dokumentation ist KI-gestützt, mit menschlicher redaktioneller Verantwortung für Genauigkeit, Klarheit und Produktionsrelevanz.

Der Inhalt basiert auf realen Ausfällen, Post-Mortems und operativen Vorfällen in produktiv eingesetzten KI-Agenten-Systemen.