Cost Guardrails for Managed Agents

When an agent runs autonomously in the cloud on a metered API, every session that starts is a spend event. Every tool call is a spend event. Every token generated is a spend event. The agent does not know it is burning money. The only thing standing between a working pipeline and a five-figure bill is the guardrail layer you build before the agent goes live.

Cost guardrails for Managed Agents are a safety concern, not just an economics concern. A runaway loop that generates 10,000 tokens per minute for six hours is functionally equivalent to a runaway process that pins a CPU — except it bills you. The difference is that CPU runaway gets caught by the operating system. Token runaway only gets caught by the guardrails you wrote.

The Budget Envelope Hierarchy

A single daily budget per agent is not enough. Production fleets have cost structure at multiple levels simultaneously: a fleet-wide ceiling across all agents, task-type budgets for each category of work, per-agent daily budgets, and per-session soft limits. These are nested, not independent.

Fleet ceiling — the hard cap across all agents combined. When the fleet ceiling trips, no new sessions start regardless of which agent requests them. This is your last line of defense and should be sized to represent genuine budget authority: the number that, if exceeded, requires an explanation to someone.

Task-type envelope — budget carved out per category of work. Research tasks, synthesis tasks, and monitoring tasks have different cost profiles and different value-per-dollar ratios. Giving each category its own envelope prevents one expensive task class from consuming the budget that other task classes need.

Per-agent envelope — individual daily budget for each named agent. An agent that exceeds its daily envelope is blocked from starting new sessions for the rest of the day. The agent is not killed — it is paused. Sessions already in flight complete normally unless they trip a session limit.

Per-session soft limit — the fastest-firing layer. A single session that crosses its per-session limit gets cancelled mid-flight. This is the guardrail that catches runaway loops before daily totals accumulate to a damaging level.

The enforcement rule: a spend event propagates upward through all four layers. The first layer that triggers its threshold determines the action — alert, block, or cancel. Inner layers (session) fire first on sudden spikes; outer layers (fleet) fire on sustained overspend across many agents.

Spend Velocity Detection

The four-layer hierarchy catches budget exhaustion. It does not catch the agent that is about to exhaust its budget in the next twenty minutes.

Spend velocity detection is the rate-based complement to total-spend thresholds. Instead of asking "has this agent spent $X today?", it asks "at the current burn rate, how much will this agent spend by end of day?"

Computing velocity:

def compute_velocity(history: list[tuple[datetime, float]], window: int = 5) -> float:
    """
    Compute spend rate in $/minute from the last `window` events.
    Returns 0.0 if fewer than two events exist in the window.
    """
    if len(history) < 2:
        return 0.0
    recent = history[-window:]
    elapsed_minutes = max(
        (recent[-1][0] - recent[0][0]).total_seconds() / 60.0,
        1.0  # floor to prevent division by zero on fast bursts
    )
    total_spend = sum(cost for _, cost in recent)
    return total_spend / elapsed_minutes

Projecting forward:

MINUTES_IN_DAY = 1440.0

def projected_daily_spend(
    rate_per_minute: float,
    minutes_elapsed_today: float,
    spend_so_far: float,
) -> float:
    """
    Project remaining spend for the day based on current rate.
    """
    minutes_remaining = max(MINUTES_IN_DAY - minutes_elapsed_today, 0.0)
    return spend_so_far + (rate_per_minute * minutes_remaining)

The velocity check fires at 80% projected (alert operations) and 100% projected (block new sessions). An agent spending at $0.40/minute projects to $576/day against an $8 daily budget — the velocity block fires after a handful of events, well before the per-session limit of $1.50 is exhausted four times over.

Kill-Switch Wiring

The guardrail layer is useless without a wired response. Detection without action is just a log message.

The kill-switch contract for cost guardrails follows the same pattern as authority kill switches: a registered callback that receives the session ID and the violation reason, and takes the cancellation action.

from typing import Callable

KillSwitchCallback = Callable[[str, GuardrailViolation], None]

class GuardrailEngine:
    def __init__(self) -> None:
        self._callbacks: list[KillSwitchCallback] = []

    def on_kill(self, callback: KillSwitchCallback) -> None:
        """Register a kill-switch callback. Called whenever a session must be stopped."""
        self._callbacks.append(callback)

    def _fire_kill(self, session_id: str, violation: GuardrailViolation) -> None:
        for cb in self._callbacks:
            cb(session_id, violation)

The callback registered by the operator typically calls the sessions cancel endpoint:

def make_cancel_callback(client):
    def cancel_session(session_id: str, violation: GuardrailViolation) -> None:
        print(f"[GUARDRAIL] Cancelling {session_id}: {violation.reason}")
        try:
            client.beta.sessions.cancel(session_id)
        except Exception as e:
            # Session may have already completed — log and move on
            print(f"[GUARDRAIL] Cancel failed (session may be done): {e}")
    return cancel_session

The callback separation matters: the guardrail engine does not know what "cancel" means in your infrastructure. For a Managed Agents pipeline, cancel means the API call. For a mock test environment, cancel means setting a flag. The callback is the seam between enforcement logic and execution.

Hard Ceilings vs. Soft Alerts

Not every threshold should be a hard stop. The enforcement spectrum:

Soft alert (warning): Triggered at 80% of a budget. The agent continues. The alert fires to an operations channel, a log stream, or a monitoring webhook. The purpose is to give a human or an automated responder time to investigate before the hard stop fires.

Hard block (session-level): Triggered when a per-session limit is crossed. New tool calls are blocked; the current session is cancelled. The agent can start a new session against a fresh limit tomorrow (or immediately if the block is per-session, not per-day).

Hard block (agent-level): Triggered when the daily per-agent budget is exhausted. The agent cannot start new sessions for the remainder of the day. This is recoverable — the budget resets at the next day boundary.

Hard block (fleet-level): Triggered when the global ceiling is hit. All agents are blocked from starting new sessions. This requires manual intervention: someone with budget authority must raise the ceiling or wait for the day to reset.

The practical rule: implement soft alerts at 80% on the per-agent and fleet layers. Implement hard blocks at 100% on all four layers. The session layer hard blocks immediately — there is no useful alert window for a session that is already running away.

Cost Attribution

Knowing that $47 was spent on Tuesday is not cost attribution. Cost attribution answers: which agent, on which task type, in which session, for which downstream feature or customer, spent that $47.

from dataclasses import dataclass

@dataclass
class AttributedCostEvent:
    agent_id: str
    session_id: str
    task_type: str
    feature_id: str        # the product feature that initiated the work
    customer_id: str       # the customer whose request triggered the agent
    model: str
    input_tokens: int
    output_tokens: int
    cost_usd: float
    timestamp: str

The feature_id and customer_id fields require propagation discipline: the orchestrator that starts the session must carry these identifiers from the originating request and attach them to every cost event the session generates. This is the plumbing work that makes post-mortem cost analysis meaningful.

Without attribution, you know you are over budget. With attribution, you know which customer's requests caused the overrun and can make a rational decision: raise their rate limit, route their requests to a cheaper model tier, or implement a per-customer budget ceiling.

The Build-vs-Buy Decision for Cost Observability

You can build cost observability entirely within your application code — the approach this lesson focuses on. You can also adopt a cost observability platform that instruments the API layer directly.

The build-vs-buy decision for cost observability:

Build (your own instrumentation):

• Full control over attribution schema and granularity
• No additional vendor dependency
• Cost events are first-class objects in your domain model
• Requires maintenance as your fleet evolves

Buy (third-party observability platform):

• Lower implementation overhead for the basics (spend totals, model breakdowns)
• Dashboards without custom code
• Attribution depth is limited to what the platform tracks
• Adds a cost layer to track the cost layer

For most teams running under 20 agents, building the core instrumentation (four-layer enforcer + velocity monitor + attribution events) takes less time than evaluating and integrating a platform. The implementation surface is small: one data class, one enforcer class, one velocity monitor, and one callback registration. The logic fits in a single file.