Put a Hard Ceiling on Your Managed Agent Before It Overruns: Session Budgets

TL;DR: Pass budget={"type":"limit","max_list_cost":{"currency":"USD","amount":"2500"}} when you create a Managed Agents session and it pauses — files and tool state intact — the moment it crosses $25.00.

Without a spend cap, a Managed Agents session running multiple subagents can bill hundreds of dollars before a job finishes — or before you notice it got stuck. Session budgets set a hard ceiling at creation that pauses the session cleanly when it hits your limit.

Set it at creation:

import anthropic

client = anthropic.Anthropic()
BETAS = ["managed-agents-2026-04-01"]

session = client.beta.sessions.create(
    agent=my_agent.id,
    environment_id=env.id,
    title="Weekly competitive analysis",
    budget={
        "type": "limit",
        "max_list_cost": {
            "currency": "USD",
            "amount": "2500",   # $25.00 — amount is in whole US cents as a string
        },
    },
    betas=BETAS,
)

Detect and handle the pause:

with client.beta.sessions.events.stream(session.id, betas=BETAS) as stream:
    for ev in stream:
        if ev.type == "session.status_idle":
            if ev.stop_reason.type == "budget_reached":
                # Files and tool state are preserved — raise the cap to resume
                client.beta.sessions.update(
                    session.id,
                    budget={"type": "limit", "max_list_cost": {"currency": "USD", "amount": "5000"}},
                    betas=BETAS,
                )
            break

Track spend as it accumulates with session.usage events, which stream the cumulative list_cost against your cap.

The constraints that catch people:

• Budget can only be set at session creation — you cannot add one to a session already running
• Amount is in whole US cents as a string: "100" = $1.00, "2500" = $25.00
• You can raise the cap but not lower it below already-consumed cost
• Removing the budget (budget=None) is permanent — you cannot re-add it to the same session
• Enforcement happens between model requests, not mid-turn, so actual spend can slightly overshoot your cap
• Requires anthropic>=0.121.0

The same SDK version also shipped inference geo pinning (model.inference_geo: "us" or "global") and GitHub-hosted skills for Managed Agents. The advisor model pattern ships as a separate roster entry covered in a previous post.

Sources: Session budgets — Anthropic Managed Agents Docs · Cookbook: cap what a session can spend — platform.claude.com · AI Agent Cost Control: 2026's Shift to Session Caps — Nerd Level Tech