Budgets et Kill-Switch

Le travail d’un agent peut être gratuit, facturé à l’usage ou soumis à des coûts externes répercutés. Vérifiez donc le Wallet et les règles budgétaires avant les actions payantes.

Tous les champs de consommation et de budget de la passerelle sont exprimés en Credits. Les champs de paiement ou de facture peuvent indiquer une devise comme EUR. Il s’agit alors de la devise de la pièce ou du prestataire, et non de l’unité de consommation de la passerelle.

Consulter le Wallet

Après la validation du code Owner-OTP et l’activation par webRichtung, wallet.balance.get lit le solde actuel du Wallet du propriétaire de l’organisation. Cette capacité est en lecture seule et utilise le scope billing.wallet:read.

Vérifier le budget

La capacité wallet.agent_budget.guard.check vérifie qu’une opération prévue respecte le budget, les plafonds et le Kill-Switch. Utilisez-la avant une capacité payante. Répétez la vérification si l’intention, les paramètres ou l’estimation des coûts changent.

Transmettez au contrôle budgétaire l’estimation issue du dry_run de la capacité cible. Dans dry_run, estimated_cost.amount_max est une chaîne décimale. Dans estimated_cost_credits, transmettez la même valeur sous forme de nombre JSON :

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

Champ	Règle
capability_id	Obligatoire. Capacité que vous souhaitez exécuter ensuite.
estimated_cost_credits	Obligatoire. Nombre en Credits. Utilisez dry_run.estimated_cost.amount_max ; dry_run.estimated_cost.currency doit valoir credits.
window	Facultatif. task, daily ou monthly ; en cas de doute, commencez par task.

Le contrôle s’exécute via /mcp/invoke. La réponse réussie utilise l’enveloppe habituelle d’Invoke. La décision du contrôle se trouve sous 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
    }
  }
}

Tous les champs de plafond et de consommation se terminent par _credits. Si status ne vaut pas succeeded ou si result.allowed ne vaut pas true, n’exécutez pas la capacité cible.

Un champ de plafond ne limite la consommation que si sa valeur numérique est supérieure à 0. La valeur 0 signifie qu’aucun plafond n’est actif pour cette période. Elle n’indique ni une valeur par défaut, ni un blocage, ni un état inconnu. Une réponse avec result.allowed: true et certains plafonds à 0 est donc correcte si le Wallet, les autres plafonds actifs et kill_switch_enabled ne bloquent pas l’opération.

Contenu utile sous result :

Champ	Signification
allowed	true si le Wallet, les plafonds et le Kill-Switch ne bloquent pas l’opération prévue.
organization_id	Organisation du propriétaire dont le Wallet et la politique ont été vérifiés.
wallet_balance_credits	Solde actuel du Wallet du propriétaire, sous forme de chaîne décimale en Credits.
estimated_cost_credits	Estimation vérifiée, sous forme de nombre en Credits.
policy.policy_profile_id	Profil de politique actif ou null.
policy.task_cap_credits	Plafond de cette opération en Credits ; seules les valeurs > 0 sont actives, 0 signifie aucun plafond actif.
policy.daily_cap_credits	Plafond journalier en Credits ; seules les valeurs > 0 sont actives, 0 signifie aucun plafond actif.
policy.monthly_cap_credits	Plafond mensuel en Credits ; seules les valeurs > 0 sont actives, 0 signifie aucun plafond actif.
policy.burn_rate_hourly_cap_credits	Plafond de consommation horaire en Credits ; seules les valeurs > 0 sont actives, 0 signifie aucun plafond actif.
policy.kill_switch_enabled	true arrête les nouvelles exécutions d’agents.
ledger.hour_cost_credits	Credits déjà comptabilisés dans la fenêtre horaire actuelle.
ledger.today_cost_credits	Credits déjà comptabilisés dans la journée actuelle.
ledger.month_cost_credits	Credits déjà comptabilisés dans le mois actuel.

Kill-Switch

Un Kill-Switch arrête les exécutions d’agents jusqu’à ce qu’une personne autorisée les réactive. Traitez capability_disabled comme un blocage strict et n’essayez pas de le contourner.

Déroulement pratique

1. Consultez describe pour la capacité cible.
2. Si describe.dry_run vaut required, effectuez d’abord un dry_run réussi avec les mêmes paramètres.
3. Pour les actions payantes, effectuez une estimation préalable et transmettez dry_run.estimated_cost.amount_max comme nombre JSON à wallet.agent_budget.guard.check.
4. Exécutez la capacité cible uniquement avec status: "succeeded" et result.allowed: true.
5. En cas d’erreur budgétaire, n’exécutez pas l’action. Utilisez le Passage de relais ou le canal de retour d’expérience.

Pour continuer

dry_run et estimation des coûts