Bütçeler & Kill-Switch

Agent çalışması ücretsiz, tüketim bazlı veya harici olarak iletilebilir. Bu nedenle maliyet ilgili aksiyonlardan önce Wallet ve bütçe kurallarını kontrol edersiniz.

Tüm Gateway tüketim ve bütçe alanları Credits olarak belirtilir. Ödeme veya fatura alanları EUR gibi bir para birimi taşıyabilir; bu durumda belge veya Provider para birimidir, Agent-Gateway’in tüketim birimi değildir.

Wallet okuma

Owner-OTP-Claim ve webRichtung aktivasyonundan sonra wallet.balance.get organizasyonun Owner-Wallet’ının güncel bakiye durumunu okur. Sadece okuma işlevi görür ve billing.wallet:read scope’unu kullanır.

Bütçe kontrolü

wallet.agent_budget.guard.check Capability’si, planlanan bir operasyonun Bütçe, Cap ve Kill-Switch dahilinde olup olmadığını kontrol eder. Bunu ücretli bir hedef Capability’den önce kullanın; niyet, parametre veya maliyet tahmini değişirse kontrolü tekrarlayın.

Guard’a hedef dry_run’dan maliyet tahminini gönderin. estimated_cost.amount_max, dry_run’da bir ondalık string’dir; estimated_cost_credits için aynı değeri JSON sayısı olarak iletirsiniz:

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

Alan	Kural
`capability_id`	Zorunlu. Ardından çalıştırmak istediğiniz Capability.
`estimated_cost_credits`	Zorunlu. Credits cinsinden sayı. `dry_run.estimated_cost.amount_max` kullanın; `dry_run.estimated_cost.currency` `credits` olmalıdır.
`window`	Opsiyonel. `task`, `daily` veya `monthly`; emin değilseniz `task` ile başlayın.

Guard, /mcp/invoke üzerinden çalıştırılır. Başarılı yanıt normal Invoke zarfını kullanır; Guard kararı result altındadır:

{
  "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
    }
  }
}

Tüm Cap ve Ledger alanları _credits ile biter. status succeeded değilse veya result.allowed true değilse, hedef Capability’yi çalıştırmazsınız.

Cap semantiği: Bir Cap alanı yalnızca sayısal değeri 0’dan büyükse sınırlar. 0, bu pencerede aktif bir Cap olmadığı anlamına gelir. Varsayılan değer, kilit veya bilinmeyen durum değildir. result.allowed: true ve bireysel Cap değerleri 0 olan bir yanıt, Wallet, diğer aktif Cap’ler ve kill_switch_enabled bloke etmiyorsa doğrudur.

result altındaki içerik:

Alan	Anlam
`allowed`	Wallet, Cap’ler ve Kill-Switch planlanan operasyonu bloke etmiyorsa `true`.
`organization_id`	Wallet ve Policy’si kontrol edilen Owner organizasyonu.
`wallet_balance_credits`	Owner-Wallet’ın Credits cinsinden ondalık string olarak güncel bakiyesi.
`estimated_cost_credits`	Kontrol edilen tahmin, Credits cinsinden sayı olarak.
`policy.policy_profile_id`	Aktif Policy profili veya `null`.
`policy.task_cap_credits`	Bu işlem için Credits cinsinden Cap; yalnızca `> 0` değerleri aktiftir, `0` aktif Cap olmadığı anlamına gelir.
`policy.daily_cap_credits`	Credits cinsinden günlük Cap; yalnızca `> 0` değerleri aktiftir, `0` aktif Cap olmadığı anlamına gelir.
`policy.monthly_cap_credits`	Credits cinsinden aylık Cap; yalnızca `> 0` değerleri aktiftir, `0` aktif Cap olmadığı anlamına gelir.
`policy.burn_rate_hourly_cap_credits`	Credits cinsinden saatlik Burn-Rate Cap; yalnızca `> 0` değerleri aktiftir, `0` aktif Cap olmadığı anlamına gelir.
`policy.kill_switch_enabled`	`true` yeni Agent çalıştırmalarını durdurur.
`ledger.hour_cost_credits`	Mevcut saat penceresinde halihazırda sayılan Credits.
`ledger.today_cost_credits`	Mevcut gün penceresinde halihazırda sayılan Credits.
`ledger.month_cost_credits`	Mevcut ay penceresinde halihazırda sayılan Credits.

Kill-Switch

Bir Kill-Switch, yetkili bir insan tarafından tekrar serbest bırakılana kadar Agent çalıştırmalarını durdurur. capability_disabled’ı kesin bir kilit olarak değerlendirin ve atlamaya çalışmayın.

Pratik akış

Hedef Capability’nin describe bilgisini okuyun.
describe.dry_run değeri required ise, önce aynı parametrelerle başarılı bir dry_run çalıştırın.
Ücretli aksiyonlar için bir maliyet Preflight yapın ve dry_run.estimated_cost.amount_max’i JSON sayısı olarak wallet.agent_budget.guard.check’e gönderin.
Yalnızca status: "succeeded" ve result.allowed: true durumunda hedef Capability’yi çalıştırın.
Bütçe hatası durumunda: çalıştırmayın, bunun yerine Handover veya Feedback kullanın.

Devamı

dry_run & Maliyet Preflight