Budgets & Kill-Switch

Agent-Arbeit kann frei, verbrauchsbasiert oder extern durchgereicht sein. Darum prüfst du vor kostenrelevanten Aktionen Wallet und Budgetregeln.

Alle Gateway-Verbrauchs- und Budgetfelder sind in Credits angegeben. Zahlungs- oder Rechnungsfelder können eine Währung wie EUR tragen; das ist dann Beleg- oder Provider-Währung, nicht die Verbrauchseinheit des Agent-Gateway.

Wallet lesen

Nach Owner-OTP-Claim und webRichtung-Freischaltung liest wallet.balance.get den aktuellen Guthabenstand der Owner-Wallet der Organisation. Sie ist lesend und nutzt den Scope billing.wallet:read.

Budget prüfen

Die Capability wallet.agent_budget.guard.check prüft, ob eine geplante Operation innerhalb von Budget, Cap und Kill-Switch liegt. Nutze sie vor einer bezahlten Ziel-Capability; wiederhole die Prüfung, wenn sich Absicht, Parameter oder Kostenschätzung ändern.

Sende an den Guard die Kostenschätzung aus dem Ziel-dry_run. estimated_cost.amount_max ist im dry_run ein Dezimal-String; für estimated_cost_credits übergibst du denselben Wert als JSON-Zahl:

{
  "id": "wallet.agent_budget.guard.check",
  "params": {
    "capability_id": "documents.document.upload",
    "estimated_cost_credits": 0.09,
    "window": "task"
  }
}

Feld	Regel
`capability_id`	Pflicht. Capability, die du danach ausführen willst.
`estimated_cost_credits`	Pflicht. Zahl in Credits. Verwende `dry_run.estimated_cost.amount_max`; `dry_run.estimated_cost.currency` muss `credits` sein.
`window`	Optional. `task`, `daily` oder `monthly`; wenn du unsicher bist, beginne mit `task`.

Der Guard wird über /mcp/invoke ausgeführt. Die erfolgreiche Antwort nutzt die normale Invoke-Hülle; die Guard-Entscheidung liegt unter result:

{
  "interface_version": "1.0",
  "status": "succeeded",
  "capability_id": "wallet.agent_budget.guard.check",
  "resolved_version": "1.0.0",
  "audit_id": "audit_123",
  "result": {
    "allowed": true,
    "organization_id": "org_123",
    "wallet_balance_credits": "100.00",
    "estimated_cost_credits": 0.09,
    "policy": {
      "policy_profile_id": "policy_123",
      "task_cap_credits": 0,
      "daily_cap_credits": 10,
      "monthly_cap_credits": 100,
      "burn_rate_hourly_cap_credits": 0,
      "kill_switch_enabled": false
    },
    "ledger": {
      "hour_cost_credits": 0.2,
      "today_cost_credits": 0.5,
      "month_cost_credits": 2
    }
  }
}

Alle Cap- und Ledger-Felder enden auf _credits. Wenn status nicht succeeded ist oder result.allowed nicht true ist, führst du die Ziel-Capability nicht aus.

Cap-Semantik: Ein Cap-Feld begrenzt nur, wenn sein numerischer Wert größer als 0 ist. 0 bedeutet kein aktives Cap in diesem Fenster. Es ist kein Default-Wert, keine Sperre und kein unbekannter Zustand. Eine Antwort mit result.allowed: true und einzelnen Cap-Werten 0 ist deshalb korrekt, wenn Wallet, andere aktive Caps und kill_switch_enabled nicht blockieren.

Nutzinhalt unter result:

Feld	Bedeutung
`allowed`	`true`, wenn Wallet, Caps und Kill-Switch die geplante Operation nicht blockieren.
`organization_id`	Owner-Organisation, deren Wallet und Policy geprüft wurden.
`wallet_balance_credits`	Aktuelles Guthaben der Owner-Wallet als Dezimalstring in Credits.
`estimated_cost_credits`	Geprüfte Schätzung als Zahl in Credits.
`policy.policy_profile_id`	Aktives Policy-Profil oder `null`.
`policy.task_cap_credits`	Cap für diesen Vorgang in Credits; nur Werte `> 0` sind aktiv, `0` bedeutet kein aktives Cap.
`policy.daily_cap_credits`	Tages-Cap in Credits; nur Werte `> 0` sind aktiv, `0` bedeutet kein aktives Cap.
`policy.monthly_cap_credits`	Monats-Cap in Credits; nur Werte `> 0` sind aktiv, `0` bedeutet kein aktives Cap.
`policy.burn_rate_hourly_cap_credits`	Stunden-Burn-Rate-Cap in Credits; nur Werte `> 0` sind aktiv, `0` bedeutet kein aktives Cap.
`policy.kill_switch_enabled`	`true` stoppt neue Agent-Ausführungen.
`ledger.hour_cost_credits`	Bereits gezählte Credits im aktuellen Stundenfenster.
`ledger.today_cost_credits`	Bereits gezählte Credits im aktuellen Tagesfenster.
`ledger.month_cost_credits`	Bereits gezählte Credits im aktuellen Monatsfenster.

Kill-Switch

Ein Kill-Switch stoppt Agent-Ausführungen, bis ein berechtigter Mensch ihn wieder freigibt. Agents behandeln capability_disabled als harte Sperre und versuchen nicht, sie zu umgehen.

Praktischer Ablauf

describe der Ziel-Capability lesen.
Wenn describe.dry_run den Wert required hat, zuerst einen erfolgreichen dry_run mit denselben Parametern ausführen.
Für bezahlte Aktionen einen Kosten-Preflight ausführen und dry_run.estimated_cost.amount_max als JSON-Zahl an wallet.agent_budget.guard.check senden.
Nur bei status: "succeeded" und result.allowed: true die Ziel-Capability ausführen.
Bei Budgetfehler: nicht ausführen, sondern Handover oder Feedback nutzen.

Weiter

dry_run & Kosten-Preflight