Budżety i Kill-Switch

Praca agenta może być bezpłatna, rozliczana według zużycia lub przekazywana na zewnątrz. Dlatego przed działaniami wpływającymi na koszty sprawdzasz portfel i reguły budżetowe.

Wszystkie pola zużycia i budżetu w Gateway są podawane w Credits. Pola płatności lub fakturowania mogą zawierać walutę taką jak EUR; jest to wtedy waluta dokumentu lub dostawcy, a nie jednostka zużycia Agent-Gateway.

Odczyt portfela

Po Owner-OTP-Claim i aktywacji webRichtung, wallet.balance.get odczytuje aktualny stan salda portfela właściciela organizacji. Jest tylko do odczytu i wykorzystuje zakres billing.wallet:read.

Sprawdzanie budżetu

Capability wallet.agent_budget.guard.check sprawdza, czy planowana operacja mieści się w ramach budżetu, limitu i Kill-Switch. Użyj jej przed płatną docelową capability; powtórz sprawdzenie, jeśli zmieni się intencja, parametry lub szacunek kosztów.

Wyślij do Guard szacunek kosztów z docelowego dry_run. estimated_cost.amount_max w dry_run jest ciągiem dziesiętnym; dla estimated_cost_credits przekazujesz tę samą wartość jako liczbę JSON:

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

Pole	Reguła
`capability_id`	Wymagane. Capability, którą chcesz wykonać po sprawdzeniu.
`estimated_cost_credits`	Wymagane. Liczba w Credits. Użyj `dry_run.estimated_cost.amount_max`; `dry_run.estimated_cost.currency` musi być `credits`.
`window`	Opcjonalne. `task`, `daily` lub `monthly`; jeśli nie jesteś pewien, zacznij od `task`.

Guard jest wykonywany przez /mcp/invoke. Pomyślna odpowiedź używa normalnej otoczki Invoke; decyzja Guard znajduje się w 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
    }
  }
}

Wszystkie pola Cap i Ledger kończą się na _credits. Jeśli status nie jest succeeded lub result.allowed nie jest true, nie wykonujesz docelowej capability.

Semantyka Cap: Pole Cap ogranicza tylko wtedy, gdy jego wartość numeryczna jest większa niż 0. 0 oznacza brak aktywnego limitu w tym oknie. Nie jest to wartość domyślna, blokada ani nieznany stan. Odpowiedź z result.allowed: true i poszczególnymi wartościami Cap 0 jest zatem prawidłowa, jeśli portfel, inne aktywne limity i kill_switch_enabled nie blokują.

Zawartość w result:

Pole	Znaczenie
`allowed`	`true`, jeśli portfel, limity i Kill-Switch nie blokują planowanej operacji.
`organization_id`	Organizacja właściciela, której portfel i zasady zostały sprawdzone.
`wallet_balance_credits`	Aktualne saldo portfela właściciela jako ciąg dziesiętny w Credits.
`estimated_cost_credits`	Sprawdzony szacunek jako liczba w Credits.
`policy.policy_profile_id`	Aktywny profil zasad lub `null`.
`policy.task_cap_credits`	Limit dla tej operacji w Credits; tylko wartości `> 0` są aktywne, `0` oznacza brak aktywnego limitu.
`policy.daily_cap_credits`	Dzienny limit w Credits; tylko wartości `> 0` są aktywne, `0` oznacza brak aktywnego limitu.
`policy.monthly_cap_credits`	Miesięczny limit w Credits; tylko wartości `> 0` są aktywne, `0` oznacza brak aktywnego limitu.
`policy.burn_rate_hourly_cap_credits`	Godzinowy limit szybkości spalania w Credits; tylko wartości `> 0` są aktywne, `0` oznacza brak aktywnego limitu.
`policy.kill_switch_enabled`	`true` zatrzymuje nowe wykonania agenta.
`ledger.hour_cost_credits`	Już naliczone Credits w bieżącym oknie godzinowym.
`ledger.today_cost_credits`	Już naliczone Credits w bieżącym oknie dziennym.
`ledger.month_cost_credits`	Już naliczone Credits w bieżącym oknie miesięcznym.

Kill-Switch

Kill-Switch zatrzymuje wykonania agenta, dopóki uprawniona osoba nie przywróci dostępu. Traktuj capability_disabled jako twardą blokadę i nie próbuj jej omijać.

Praktyczny przebieg

Odczytaj describe docelowej capability.
Jeśli describe.dry_run ma wartość required, najpierw wykonaj pomyślny dry_run z tymi samymi parametrami.
Dla płatnych działań wykonaj preflight kosztowy i wyślij dry_run.estimated_cost.amount_max jako liczbę JSON do wallet.agent_budget.guard.check.
Tylko przy status: "succeeded" i result.allowed: true wykonaj docelową capability.
W przypadku błędu budżetu: nie wykonuj, lecz wykorzystaj Handover lub feedback.

Dalej

dry_run i Kosten-Preflight