How must agents negotiate cooperative rate-limit budgets without individual overconsumption?

**Date of Record:** 2026 October 27 **Scope:** Applies when multiple autonomous agents share a rate-limited resource (API quota, tenant limit, or infrastructure capacity) and must cooperatively allocate the shared budget without individually over-consuming, causing collective exhaustion. Does not apply to strictly single-agent sessions or resources with effectively unlimited capacity.

Core Distinction

The separation between **individual rate-limit compliance** (each agent stays under its per-agent budget) and **collective rate-limit compliance** (the sum of all agents' usage stays under the shared budget). Relying on individual compliance creates the **Tragedy of the Shared Quota**: each agent maximizes its own usage (rational individual behavior), the aggregate exceeds the shared budget, and the resource is throttled or banned for all agents.

What Was Observed

In multi-agent shared-resource architectures, failing to enforce cooperative budgets produces three primary failure modes:

  1. **Quota Exhaustion Race:** Ten agents each plan to use 15% of the shared quota, but all burst simultaneously, exhausting 100% in minutes, and all are throttled.
  2. **Burst Amplification:** Each agent ramps up usage during what it perceives as off-peak, but all agents perceive the same off-peak, causing a burst that exceeds the limit.
  3. **Fairness Collapse:** One dominant agent consumes the majority of the shared budget, starving the others and forcing them into extreme backoff.

Recorded Elements

  1. **`cooperative_budget_claim_receipt`:** A cryptographic claim on a share of the shared budget, reserved before the agent uses it, preventing simultaneous over-claiming.
  2. **`collective_usage_attestation_signature`:** A cryptographic proof of the current collective usage across all agents, allowing individual agents to see the remaining headroom.
  3. **`fairness_allocation_receipt`:** The exact fairness rule (e.g., "each agent gets equal share," "proportional to priority") and the current allocation, allowing agents to know their fair share.
  4. **`burst_coordination_receipt`:** A cryptographic proof that the agent's planned burst is within its fair share and within the collective remaining budget.

Condition of Validity

* **Applies when:** Multiple agents share a rate-limited resource, individual maximization can exhaust the shared budget, and cooperative allocation is enforceable. * **Does not apply when:** Single agent, unlimited resource, or agents that operate in strict isolation with separate quotas.

Decision Boundary

  1. **Is the resource shared across multiple agents?** If no, standard rate limiting applies. If yes, proceed.
  2. **Is the `cooperative_budget_claim_receipt` in place before the agent uses budget?** If no, the agent may over-consume. It must claim first.
  3. **Does the agent's planned usage fit within its `fairness_allocation_receipt`?** If yes, proceed. If no, the agent must wait, reduce, or request reallocation.
  4. **Conversely, when can an agent use shared budget without cooperative claims?** Only when the resource is strictly underutilized (collective usage well below the shared limit), or the agent's priority is explicitly high enough to justify discretionary use.

Operational Effect

  1. **Quota Preservation:** Cooperative claims prevent simultaneous exhaustion.
  2. **Burst Coordination:** Agents check collective headroom before bursting.
  3. **Fairness Enforcement:** Explicit fairness rules prevent one agent from starving others.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class CooperativeVerdict(Enum):
    SINGLE_AGENT = auto()
    CLAIM_VERIFIED = auto()
    CLAIM_EXCEEDS_FAIR_SHARE = auto()
    COLLECTIVE_HEADROOM_INSUFFICIENT = auto()

@dataclass(frozen=True)
class BudgetClaim:
    agent_id: str
    claimed_amount: float
    fairness_allocation: float
    collective_usage_current: float
    collective_usage_limit: float

@dataclass(frozen=True)
class CooperativePolicy:
    require_claims: bool
    max_burst_ratio: float

@dataclass(frozen=True)
class CooperativeManifest:
    verdict: CooperativeVerdict
    directive: str
    manifest_digest: str

class CooperativeRateLimitGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_claim(
        cls, claim: BudgetClaim, policy: CooperativePolicy
    ) -> CooperativeManifest:
        
        # Gate 1: Claims not required
        if not policy.require_claims:
            digest = cls._hash(json.dumps({
                "agent": claim.agent_id,
                "claims": "NOT_REQUIRED"
            }, sort_keys=True))
            return CooperativeManifest(
                verdict=CooperativeVerdict.SINGLE_AGENT,
                directive=f"PROCEED: Cooperative claims not required.",
                manifest_digest=digest
            )

        # Gate 2: Fair share check
        if claim.claimed_amount > claim.fairness_allocation:
            return CooperativeManifest(
                verdict=CooperativeVerdict.CLAIM_EXCEEDS_FAIR_SHARE,
                directive=f"HALT: Agent {claim.agent_id} claims {claim.claimed_amount:.2f} > fair share {claim.fairness_allocation:.2f}.",
                manifest_digest=cls._hash(f"OVER_FAIR:{claim.agent_id}")
            )

        # Gate 3: Collective headroom
        remaining = claim.collective_usage_limit - claim.collective_usage_current
        if claim.claimed_amount > remaining:
            return CooperativeManifest(
                verdict=CooperativeVerdict.COLLECTIVE_HEADROOM_INSUFFICIENT,
                directive=f"HALT: Claim {claim.claimed_amount:.2f} > remaining headroom {remaining:.2f}.",
                manifest_digest=cls._hash(f"NO_HEADROOM:{remaining:.2f}")
            )

        # Gate 4: Verified
        digest = cls._hash(json.dumps({
            "agent": claim.agent_id,
            "claimed": f"{claim.claimed_amount:.2f}",
            "fair_share": f"{claim.fairness_allocation:.2f}",
            "headroom": f"{remaining:.2f}"
        }, sort_keys=True))
        
        return CooperativeManifest(
            verdict=CooperativeVerdict.CLAIM_VERIFIED,
            directive=f"PROCEED: Claim {claim.claimed_amount:.2f} within fair share and headroom.",
            manifest_digest=digest
        )