Presupuestos y Kill-Switch

El trabajo del Agent puede ser gratuito, basado en consumo o redirigido externamente. Por eso verificas la Wallet y las reglas de presupuesto antes de acciones que impliquen costes.

Todos los campos de consumo y presupuesto del Gateway están expresados en Credits. Los campos de pago o facturación pueden llevar una moneda como EUR; en ese caso es la moneda del comprobante o del proveedor, no la unidad de consumo del Agent-Gateway.

Leer la Wallet

Tras el Owner-OTP-Claim y la activación de webRichtung, wallet.balance.get lee el saldo actual de la Wallet del Owner de la organización. Es de solo lectura y utiliza el scope billing.wallet:read.

Verificar el presupuesto

La Capability wallet.agent_budget.guard.check verifica si una operación planificada está dentro del presupuesto, Cap y Kill-Switch. Úsala antes de una Capability de destino de pago; repite la verificación si cambia la intención, los parámetros o la estimación de coste.

Envía al Guard la estimación de coste del dry_run de destino. estimated_cost.amount_max es un string decimal en el dry_run; para estimated_cost_credits pasas el mismo valor como número JSON:

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

Campo	Regla
`capability_id`	Obligatorio. Capability que quieres ejecutar después.
`estimated_cost_credits`	Obligatorio. Número en Credits. Usa `dry_run.estimated_cost.amount_max`; `dry_run.estimated_cost.currency` debe ser `credits`.
`window`	Opcional. `task`, `daily` o `monthly`; si no estás seguro, comienza con `task`.

El Guard se ejecuta a través de /mcp/invoke. La respuesta exitosa utiliza la envoltura normal de Invoke; la decisión del Guard está bajo 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
    }
  }
}

Todos los campos de Cap y Ledger terminan en _credits. Si status no es succeeded o result.allowed no es true, no ejecutas la Capability de destino.

Semántica del Cap: Un campo Cap solo limita si su valor numérico es mayor que 0. 0 significa que no hay Cap activo en esa ventana. No es un valor predeterminado, ni un bloqueo ni un estado desconocido. Una respuesta con result.allowed: true y valores individuales de Cap en 0 es por tanto correcta si la Wallet, otros Caps activos y kill_switch_enabled no bloquean.

Contenido útil bajo result:

Campo	Significado
`allowed`	`true` si la Wallet, los Caps y el Kill-Switch no bloquean la operación planificada.
`organization_id`	Organización Owner cuya Wallet y Policy fueron verificadas.
`wallet_balance_credits`	Saldo actual de la Wallet del Owner como string decimal en Credits.
`estimated_cost_credits`	Estimación verificada como número en Credits.
`policy.policy_profile_id`	Perfil de Policy activo o `null`.
`policy.task_cap_credits`	Cap para esta operación en Credits; solo valores `> 0` están activos, `0` significa que no hay Cap activo.
`policy.daily_cap_credits`	Cap diario en Credits; solo valores `> 0` están activos, `0` significa que no hay Cap activo.
`policy.monthly_cap_credits`	Cap mensual en Credits; solo valores `> 0` están activos, `0` significa que no hay Cap activo.
`policy.burn_rate_hourly_cap_credits`	Cap de tasa de consumo por hora en Credits; solo valores `> 0` están activos, `0` significa que no hay Cap activo.
`policy.kill_switch_enabled`	`true` detiene nuevas ejecuciones del Agent.
`ledger.hour_cost_credits`	Credits ya contabilizados en la ventana horaria actual.
`ledger.today_cost_credits`	Credits ya contabilizados en la ventana diaria actual.
`ledger.month_cost_credits`	Credits ya contabilizados en la ventana mensual actual.

Kill-Switch

Un Kill-Switch detiene las ejecuciones del Agent hasta que una persona autorizada lo libere nuevamente. Trata capability_disabled como un bloqueo absoluto y no intentes evitarlo.

Flujo práctico

Leer describe de la Capability de destino.
Si describe.dry_run tiene el valor required, ejecutar primero un dry_run exitoso con los mismos parámetros.
Para acciones de pago ejecutar un preflight de coste y enviar dry_run.estimated_cost.amount_max como número JSON a wallet.agent_budget.guard.check.
Solo con status: "succeeded" y result.allowed: true ejecutar la Capability de destino.
En caso de error de presupuesto: no ejecutar, sino usar Handover o feedback.

Continuar

dry_run y preflight de coste