Disjuntores Econômicos para Enxames de IA: Prevenindo Contas Fora de Controle com agent-budget-governor

Por que tetos mensais de API por organização falham em enxames multiagente autônomos—e como o Benni-OS/agent-budget-governor impõe árvores hierárquicas de orçamento, disjuntores de taxa de queima (velocity burn-rate), soft downgrade automático de modelos e um ledger SHA-256 à prova de adulteração em menos de 0,05 ms antes que qualquer requisição de inferência saia do seu processo.

Disjuntores Econômicos para Enxames de IA: Prevenindo Contas Fora de Controle com agent-budget-governor

1. O Pesadelo das 3h da Manhã: Por Que Tetos Mensais de Provedor Falham

Todo time que coloca agentes de IA autônomos em produção cedo ou tarde enfrenta o mesmo incidente às 3h da manhã: um worker em background recebe um schema de ferramenta malformado, dispara um loop exponencial de retentativas dentro de um enxame multiagente e queima milhares de dólares em tokens de modelos de fronteira antes que qualquer alerta humano dispare.

Grande parte das equipes presume que configurar um limite mensal de gastos no painel da OpenAI, Anthropic ou Google Cloud resolve o risco. Em arquiteturas distribuídas de agentes, tetos no nível do provedor falham em três frentes estruturais:

Tese Central: Redes elétricas não esperam a usina derreter para conter um curto-circuito em uma tomada—elas posicionam disjuntores locais rápidos em cada quadro de distribuição. Enxames autônomos exigem disjuntores econômicos determinísticos em pré-voo rodando localmente em < 0,05 ms antes que um único socket se abra para o provedor de LLM.

2. Anatomia do Desperdício Financeiro em Enxames Multiagente

Diferente de microsserviços REST determinísticos, agentes autônomos exibem amplificação de custo não linear. Três dinâmicas combinadas transformam prompts unitariamente baratos em faturas explosivas:

A. Acúmulo de Contexto e Custo Quadrático por Turno

Em loops ReAct ou de tool-calling convencionais, cada turno concatena todo o histórico de raciocínio e o stdout bruto das ferramentas de volta ao prompt. Se um agente itera 25 vezes tentando corrigir um teste instável anexando 3.000 tokens de stack trace por passo, o consumo total de entrada cresce de forma quadrática—queimando facilmente mais de 1 milhão de tokens para um único ticket travado.

B. Amplificação por Fan-Out Hierárquico

Quando um orquestrador delega uma missão a quatro agentes especialistas e cada especialista invoca três subagentes críticos de verificação, a vazão de tokens escala como O(fator_ramificacao ^ profundidade). Sem particionamento rígido entre pai e filho, um worker subordinado enxerga toda a cota financeira da organização.

C. Picos de Velocidade de Queima (Velocity Burn-Rate)

Olhar apenas o orçamento acumulado da execução esconde anomalias de alta frequência. Suponha uma cota diária por tenant de US$ 50,00, que parece conservadora. Se um loop defeituoso queima US$ 12,00 em 8 segundos a uma velocidade de US$ 90,00/min, esperar o teto de US$ 50,00 garante desperdício financeiro evitável antes da intervenção.


3. Arquitetura: Orçamentos Hierárquicos, Disjuntores de Velocidade e Soft Downgrade

O Benni-OS/agent-budget-governor atua na fronteira de despacho em pré-voo de cada cliente LLM, gateway MCP e orquestrador de enxame. Antes de qualquer chamada de inferência ser enviada, o governador avalia quatro camadas determinísticas em < 0,05 ms na CPU local:

flowchart LR A["Requisição de Passo do Enxame\n(tenant / run / worker)"] -->|"Reserva em Pré-Voo"| B["1. Árvore Hierárquica de Orçamento\n(Org → Tenant → Run → Worker)"] B -->|"Verifica Teto e Fatia"| C["2. Velocidade em Janela Deslizante\n(< 0,05ms Burn-Rate Check)"] C -->|"Gasto < 80% & Taxa Normal"| D["CLOSED: ALLOW\n(Modelo Tier Fronteira)"] C -->|"80% <= Gasto < 100% ou Alerta Taxa"| E["HALF-OPEN: SOFT_DOWNGRADE\n(Modelo Compacto / Local)"] C -->|"Gasto >= 100% ou Pico Crítico"| F["OPEN: TRIP_CIRCUIT\n(Trava & Salva Checkpoint)"] D -->|"Consolida Uso Real"| G["4. Ledger SHA-256 de Gastos\n(Cadeia de Auditoria Imutável)"] E -->|"Consolida Uso Real"| G F -->|"Emite Recibo de Abertura"| G

Camada 1: Árvores Hierárquicas de Orçamento com Reserva Atômica

Os orçamentos formam uma árvore estrita: Organização → Tenant → Execução do Enxame → Agente Worker. Quando um orquestrador pai instancia um subagente, ele recorta uma fatia isolada via allocate_child(). Antes de a chamada HTTP sair do processo, pre_flight_reserve() bloqueia uma reserva pelo pior caso estimado (tokens de entrada + teto de saída). Após a resposta do provedor, commit_usage() reconcilia os tokens reais consumidos e devolve a sobra reservada ao nó.

Camada 2: Disjuntor de Velocidade de Queima em Janela Deslizante

Em vez de inspecionar apenas o total acumulado, cada nó mantém um buffer circular monotônico de deltas de custo com timestamp em uma janela deslizante configurável (por exemplo, 10 s ou 60 s). Se a velocidade instantânea de queima ultrapassar max_usd_per_min, o disjuntor abre imediatamente—estancando tempestades de retentativa em milissegundos mesmo quando o orçamento total acumulado ainda está longe de 100%.

Camada 3: Soft Downgrade Automático (Degradação Graciosa)

Matar um agente abruptamente aos 85% do orçamento desperdiça todo o raciocínio já produzido. Quando o consumo cruza um limiar suave (como 80% do teto do nó) ou entra em faixa amarela de velocidade, o agent-budget-governor retorna uma decisão tipada SOFT_DOWNGRADE com substituição explícita de modelo (por exemplo, migrando de um modelo de fronteira para um tier compacto ou runtime local quantizado, com teto reduzido de max_output_tokens). O agente sintetiza o resultado, grava o checkpoint e encerra de forma limpa.

Camada 4: Ledger SHA-256 à Prova de Adulteração

Cada reserva, soft downgrade, abertura de disjuntor e liquidação de uso real grava um registro imutável encadeado ao digest SHA-256 anterior: entry_hash = sha256(prev_hash || canonical_payload). Qualquer linha alterada ou removida invalida a cadeia criptográfica—oferecendo atribuição auditável por trace_id e tenant_id para FinOps, faturamento e compliance.


4. Implementação de Referência: Disjuntor Hierárquico e Ledger SHA-256 em Python

Abaixo está o núcleo Python sem dependências externas por trás do Benni-OS/agent-budget-governor. Ele implementa reserva hierárquica pai-filho, detecção de velocidade em janela deslizante, soft downgrade automático de modelo e ledger SHA-256 verificável:

import hashlib
import json
import threading
import time
from collections import deque
from dataclasses import dataclass, field
from enum import Enum
from typing import Deque, Dict, List, Optional, Tuple


class CircuitState(str, Enum):
    CLOSED = "CLOSED"                  # Execução normal no modelo solicitado
    SOFT_DOWNGRADE = "SOFT_DOWNGRADE"  # Roteamento automático para tier compacto/local
    OPEN = "OPEN"                      # Disjuntor aberto: bloqueia inferência imediatamente


class BudgetCircuitOpenError(RuntimeError):
    """Exceção disparada quando o disjuntor econômico bloqueia uma inferência."""


@dataclass(frozen=True)
class PreFlightDecision:
    allowed: bool
    state: CircuitState
    node_id: str
    reservation_id: str
    recommended_model: str
    max_output_tokens: int
    reason: str
    remaining_usd: float
    burn_rate_usd_per_min: float


@dataclass(frozen=True)
class LedgerEntry:
    seq: int
    timestamp: float
    trace_id: str
    node_id: str
    event_type: str
    model: str
    amount_usd: float
    decision: str
    prev_hash: str
    entry_hash: str


class SpendLedger:
    """Ledger append-only encadeado via SHA-256 para atribuição FinOps imutável."""

    def __init__(self) -> None:
        self._entries: List[LedgerEntry] = []
        self._head_hash: str = "0" * 64
        self._lock = threading.Lock()

    def append(
        self,
        trace_id: str,
        node_id: str,
        event_type: str,
        model: str,
        amount_usd: float,
        decision: str,
    ) -> LedgerEntry:
        with self._lock:
            seq = len(self._entries)
            ts = time.time()
            payload = json.dumps(
                {
                    "seq": seq,
                    "timestamp": round(ts, 6),
                    "trace_id": trace_id,
                    "node_id": node_id,
                    "event_type": event_type,
                    "model": model,
                    "amount_usd": round(amount_usd, 8),
                    "decision": decision,
                    "prev_hash": self._head_hash,
                },
                sort_keys=True,
                separators=(",", ":"),
            )
            entry_hash = hashlib.sha256(payload.encode("utf-8")).hexdigest()
            entry = LedgerEntry(
                seq=seq,
                timestamp=ts,
                trace_id=trace_id,
                node_id=node_id,
                event_type=event_type,
                model=model,
                amount_usd=amount_usd,
                decision=decision,
                prev_hash=self._head_hash,
                entry_hash=entry_hash,
            )
            self._entries.append(entry)
            self._head_hash = entry_hash
            return entry

    def verify_chain(self) -> bool:
        expected_prev = "0" * 64
        for entry in self._entries:
            if entry.prev_hash != expected_prev:
                return False
            payload = json.dumps(
                {
                    "seq": entry.seq,
                    "timestamp": round(entry.timestamp, 6),
                    "trace_id": entry.trace_id,
                    "node_id": entry.node_id,
                    "event_type": entry.event_type,
                    "model": entry.model,
                    "amount_usd": round(entry.amount_usd, 8),
                    "decision": entry.decision,
                    "prev_hash": entry.prev_hash,
                },
                sort_keys=True,
                separators=(",", ":"),
            )
            recomputed = hashlib.sha256(payload.encode("utf-8")).hexdigest()
            if recomputed != entry.entry_hash:
                return False
            expected_prev = entry.entry_hash
        return True


@dataclass
class BudgetNode:
    node_id: str
    hard_cap_usd: float
    soft_ratio: float = 0.80
    max_usd_per_min: float = 2.00
    velocity_window_sec: float = 60.0
    fallback_model: str = "gpt-4o-mini"
    fallback_max_tokens: int = 1024
    parent: Optional["BudgetNode"] = None
    spent_usd: float = 0.0
    reserved_usd: float = 0.0
    _events: Deque[Tuple[float, float]] = field(default_factory=deque)

    def available_usd(self) -> float:
        return max(0.0, self.hard_cap_usd - (self.spent_usd + self.reserved_usd))

    def current_burn_rate_per_min(self, now: float) -> float:
        cutoff = now - self.velocity_window_sec
        while self._events and self._events[0][0] < cutoff:
            self._events.popleft()
        window_spend = sum(amt for _, amt in self._events)
        return (window_spend / self.velocity_window_sec) * 60.0


class BudgetGovernor:
    """Disjuntor econômico determinístico sub-milissegundo para enxames de IA."""

    def __init__(self, ledger: Optional[SpendLedger] = None) -> None:
        self.nodes: Dict[str, BudgetNode] = {}
        self.reservations: Dict[str, Tuple[str, float, str]] = {}
        self.ledger = ledger or SpendLedger()
        self._lock = threading.Lock()
        self._seq = 0

    def register_root(self, node_id: str, hard_cap_usd: float, **kwargs) -> BudgetNode:
        with self._lock:
            node = BudgetNode(node_id=node_id, hard_cap_usd=hard_cap_usd, **kwargs)
            self.nodes[node_id] = node
            return node

    def allocate_child(
        self, parent_id: str, child_id: str, child_cap_usd: float, **kwargs
    ) -> BudgetNode:
        with self._lock:
            parent = self.nodes[parent_id]
            if child_cap_usd > parent.available_usd():
                raise BudgetCircuitOpenError(
                    f"Impossível alocar ${child_cap_usd:.4f} para {child_id}; "
                    f"nó pai {parent_id} possui apenas ${parent.available_usd():.4f} disponíveis."
                )
            # Isola a fatia na reserva do pai imediatamente para impedir oversubscription entre irmãos
            parent.reserved_usd += child_cap_usd
            child = BudgetNode(
                node_id=child_id,
                hard_cap_usd=child_cap_usd,
                parent=parent,
                **kwargs,
            )
            self.nodes[child_id] = child
            return child

    def pre_flight_reserve(
        self,
        node_id: str,
        trace_id: str,
        requested_model: str,
        estimated_cost_usd: float,
        requested_max_tokens: int = 4096,
    ) -> PreFlightDecision:
        with self._lock:
            node = self.nodes[node_id]
            now = time.monotonic()
            burn_rate = node.current_burn_rate_per_min(now)
            projected_total = node.spent_usd + node.reserved_usd + estimated_cost_usd

            # 1. Pico de Velocidade ou Estouro de Teto -> Disjuntor OPEN
            if burn_rate >= node.max_usd_per_min:
                self.ledger.append(
                    trace_id, node_id, "CIRCUIT_TRIP_VELOCITY", requested_model, 0.0, "OPEN"
                )
                return PreFlightDecision(
                    allowed=False,
                    state=CircuitState.OPEN,
                    node_id=node_id,
                    reservation_id="",
                    recommended_model=requested_model,
                    max_output_tokens=0,
                    reason=f"velocity_spike:{burn_rate:.2f}_usd_per_min",
                    remaining_usd=node.available_usd(),
                    burn_rate_usd_per_min=burn_rate,
                )

            if projected_total > node.hard_cap_usd:
                self.ledger.append(
                    trace_id, node_id, "CIRCUIT_TRIP_CAP", requested_model, 0.0, "OPEN"
                )
                return PreFlightDecision(
                    allowed=False,
                    state=CircuitState.OPEN,
                    node_id=node_id,
                    reservation_id="",
                    recommended_model=requested_model,
                    max_output_tokens=0,
                    reason="hard_budget_cap_exceeded",
                    remaining_usd=node.available_usd(),
                    burn_rate_usd_per_min=burn_rate,
                )

            # 2. Reserva atômica do teto de pior caso
            self._seq += 1
            res_id = f"res_{node_id}_{self._seq}"
            node.reserved_usd += estimated_cost_usd
            self.reservations[res_id] = (node_id, estimated_cost_usd, trace_id)

            # 3. Avalia limiar suave ou pressão antecipada de velocidade -> SOFT_DOWNGRADE
            utilization = projected_total / node.hard_cap_usd
            if utilization >= node.soft_ratio or burn_rate >= (node.max_usd_per_min * 0.75):
                self.ledger.append(
                    trace_id,
                    node_id,
                    "RESERVE_SOFT_DOWNGRADE",
                    node.fallback_model,
                    estimated_cost_usd,
                    "SOFT_DOWNGRADE",
                )
                return PreFlightDecision(
                    allowed=True,
                    state=CircuitState.SOFT_DOWNGRADE,
                    node_id=node_id,
                    reservation_id=res_id,
                    recommended_model=node.fallback_model,
                    max_output_tokens=min(requested_max_tokens, node.fallback_max_tokens),
                    reason=f"soft_threshold_reached:{utilization:.1%}",
                    remaining_usd=node.available_usd(),
                    burn_rate_usd_per_min=burn_rate,
                )

            self.ledger.append(
                trace_id, node_id, "RESERVE_ALLOW", requested_model, estimated_cost_usd, "CLOSED"
            )
            return PreFlightDecision(
                allowed=True,
                state=CircuitState.CLOSED,
                node_id=node_id,
                reservation_id=res_id,
                recommended_model=requested_model,
                max_output_tokens=requested_max_tokens,
                reason="within_budget",
                remaining_usd=node.available_usd(),
                burn_rate_usd_per_min=burn_rate,
            )

    def commit_usage(
        self, reservation_id: str, model_used: str, actual_cost_usd: float
    ) -> LedgerEntry:
        with self._lock:
            node_id, est_cost, trace_id = self.reservations.pop(reservation_id)
            node = self.nodes[node_id]
            node.reserved_usd = max(0.0, node.reserved_usd - est_cost)
            node.spent_usd += actual_cost_usd
            node._events.append((time.monotonic(), actual_cost_usd))

            # Propaga o gasto real para a cadeia ancestral na árvore hierárquica
            curr = node.parent
            while curr is not None:
                curr.spent_usd += actual_cost_usd
                curr.reserved_usd = max(0.0, curr.reserved_usd - actual_cost_usd)
                curr._events.append((time.monotonic(), actual_cost_usd))
                curr = curr.parent

            return self.ledger.append(
                trace_id, node_id, "COMMIT_USAGE", model_used, actual_cost_usd, "SETTLED"
            )

Padrão de Integração em Despacho de Enxames

Proteger um passo de worker autônomo exige cinco linhas de Python determinístico. Mesmo se um agente entrar em loop de validação JSON, o governador força degradação graciosa aos 80% do teto e interrompe a execução antes de exceder o sub-orçamento alocado:

governor = BudgetGovernor()
governor.register_root("org_prod", hard_cap_usd=100.00, max_usd_per_min=15.0)
governor.allocate_child("org_prod", "swarm_run_42", child_cap_usd=5.00, max_usd_per_min=1.20)
governor.allocate_child(
    "swarm_run_42", "research_worker_1", child_cap_usd=1.00,
    soft_ratio=0.80, fallback_model="gpt-4o-mini"
)

decision = governor.pre_flight_reserve(
    node_id="research_worker_1",
    trace_id="trace_98f1a",
    requested_model="claude-sonnet-4",
    estimated_cost_usd=0.045,
)
if not decision.allowed:
    raise BudgetCircuitOpenError(f"Passo interrompido com segurança: {decision.reason}")

# Roteia usando decision.recommended_model e decision.max_output_tokens, depois liquida:
governor.commit_usage(decision.reservation_id, decision.recommended_model, actual_cost_usd=0.031)
assert governor.ledger.verify_chain()

5. Comparação Empírica: APIs Cruas vs. Limites de Provedor vs. agent-budget-governor

Dimensão de Governança e FinOps SDK Cru (Sem Guardrails) Teto Mensal do Provedor Benni-OS/agent-budget-governor
Raio de Explosão em Loop Fatura em nuvem ilimitada Queda global de toda a produção Isolado à execução ou worker específico
Detecção de Velocidade de Queima Nenhuma Atraso de minutos a horas no billing Janela deslizante em tempo real (< 0,05 ms)
Comportamento Perto do Teto Explosão contínua de gastos Crash abrupto HTTP 429 / 402 Soft Downgrade automático + checkpoint
Particionamento entre Subagentes Chave única compartilhada Rotação manual de chaves por time Árvore hierárquica Pai → Filho atômica
Auditoria e Atribuição de Custo Fatura fechada no fim do mês Totais agregados da organização Ledger SHA-256 encadeado e verificável
Latência em Pré-Voo 0 ms Apenas checagem remota na API < 0,05 ms em CPU Local (Zero Custo de LLM)

6. Defesa em Profundidade na Suíte Soberana Benni OS

A governança econômica atinge confiabilidade máxima quando combinada às salvaguardas estruturais do restante da stack Benni OS. Em pipelines produtivos, o agent-intent-compiler elimina loops estocásticos de planejamento antes da execução, o agent-context-firewall coloca dados não confiáveis em quarentena para impedir que injeções indiretas disparem fan-outs indevidos de ferramentas e o agent-budget-governor impõe a fronteira financeira determinística em cada chamada de inferência e ferramenta MCP.

Cada abertura de disjuntor ou reserva liquidada registra na mesma linhagem de rastreamento usada pelo agent-run-ledger e pelo agent-trace-replay—dando às equipes de plataforma controle previsível de custos, unit economics estável e recibos criptográficos verificáveis para cada token consumido.

Instale Freios Financeiros Determinísticos nos Seus Enxames

Clone o Benni-OS/agent-budget-governor, imponha orçamentos hierárquicos e disjuntores de velocidade em menos de 0,05 ms e opere agentes autônomos sem risco de faturas fora de controle.

Explorar Benni-OS/agent-budget-governor no GitHub →

Perguntas Frequentes

Por que os limites mensais de gasto da OpenAI ou Anthropic não bastam para enxames de agentes?
Limites mensais no provedor são grosseiros e reativos. Eles sincronizam com atraso de billing e revogam a chave da organização inteira de uma vez—derrubando toda a produção quando um único worker entra em loop de retentativas. O agent-budget-governor impõe orçamentos isolados em pré-voo por tenant, execução de enxame e subagente em menos de 0,05 ms localmente.
Como o Soft Downgrade Automático evita falhas abruptas no meio de uma tarefa?
Quando uma execução cruza um limiar suave configurável (como 80% do orçamento alocado ou um pico moderado de velocidade de queima), o agent-budget-governor muda o estado do disjuntor para SOFT_DOWNGRADE em vez de abortar imediatamente. Os passos seguintes são roteados automaticamente para um modelo compacto de menor custo ou modelo local com teto reduzido de tokens de saída, permitindo sintetizar e salvar o checkpoint com segurança.
Como o disjuntor de velocidade de queima (velocity burn-rate) em janela deslizante trava loops infinitos?
Um loop fechado pode queimar centenas de dólares em segundos muito antes de um teto mensal ou diário ser percebido. O disjuntor de velocidade monitora o gasto em USD ao longo de uma janela deslizante curta (por exemplo, 10 a 60 segundos). Se a taxa instantânea de queima ultrapassar max_usd_per_min do nó, o disjuntor abre imediatamente independentemente do saldo total restante.
Como o ledger SHA-256 encadeado garante atribuição de custos à prova de adulteração?
Cada reserva de orçamento, soft downgrade, abertura de disjuntor e recibo reconciliado de tokens é serializado com trace_id, node_id, timestamp e o digest da entrada anterior, recebendo um hash SHA-256. Qualquer edição retroativa ou omissão quebra a verificação da cadeia, entregando não-repúdio criptográfico para FinOps corporativo e rateio multi-tenant.