Claude Managed Agents Session Budget Checklist

Claude Managed Agents session budgets: prove the hard stop before unattended runs Quick answer On August 7, 2026, Anthropic added hard per-session budgets to Claude Managed Agents. A budget is a US-dollar ceiling, written as whole cents, that the platform enforces against the session's public-list-price cost. When the cap is reached, the session pauses with the session-level stop reason budget_reached ; it does not terminate. Raising or removing the budget resumes the paused work automatically. This is an API-level Claude Managed Agents feature. It is not a Claude Code subscription meter, and it is different from the Messages API's advisory, token-denominated task budgets. Do not treat the number as an exact final invoice or a mid-request kill switch. Enforcement happens between model requests. An in-flight request finishes, so one request per active thread can take the recorded list cost past the cap. Use the rollout below to prove event ordering, overshoot, blocked new work, and resume authority before trusting the cap on unattended agents. Who this is for This guide is for developers running Claude Managed Agents through the REST API or Anthropic SDKs, especially scheduled deployments, long research sessions, tool-heavy agents, and multiagent coordinators. It is useful when a job must stop starting new model work before one failed loop consumes an open-ended budget. The feature is a financial guardrail, not a task-quality guarantee. Keep outcome checks, permission policies, tool timeouts, and human approval for irreversible actions. What the budget actually controls The platform continuously computes a session's list cost. The official documentation includes model tokens at each model's public list price, web search at $10 per 1,000 searches, and active session runtime at $0.08 per hour. Negotiated discounts do not change when the cap fires, so the budget is not necessarily the amount your organization will be billed. | Boundary | Official behavior | Operational consequence | |---|---|---| | Unit | Whole US cents as a string; "2500" means $25 | Reject decimal strings and floating-point conversion | | Attachment | Set only when the session is created | An unbudgeted existing session cannot receive a cap later | | Enforcement | Checked before each new model request | A request already running can finish past the cap | | Stop state | Session becomes idle with budget_reached | Preserve state; do not classify it as completion or failure | | Multiagent | One shared cap across all threads and advisors | Parallel in-flight requests increase the overshoot margin | | Deployment | Budget is copied to each future session | It is a per-run ceiling, not one cumulative deployment budget | | Resume | Raise the cap or remove it | An accepted update resumes work without another user message | Removing a session budget is one-way: the same session cannot receive a new budget later. Changing a deployment budget is different; it affects sessions started afterward, and a cleared deployment budget can be set again. A budget-sizing rule that survives concurrency Start from accepted work, not a guess about average tokens. Run representative tasks without a cap, record the p50 and p95 session usage.list_cost , then choose a canary cap that is high enough for one normal task but low enough to stop a loop. Use this planning record: Task class: Observed p50 list cost: Observed p95 list cost: Maximum concurrent threads: Largest plausible single request per thread: Web-search allowance: Runtime allowance: Canary cap: Expected overshoot margin: Who may raise the cap: Maximum approved cap: The important margin is not a fixed percentage. It is the sum of the largest plausible in-flight request on each active thread. A single-threaded session has one-request exposure; a coordinator with four active threads can have four requests complete after the cap decision. Six-canary rollout 1. Create a disposable budgeted session Use a non-production agent and harmless task. The request must include the Managed Agents beta header and a budget at creation: { "agent": "agent_test", "environment_id": "env_test", "budget": { "type": "limit", "max_list_cost": { "amount": "50", "currency": "USD" } } } Keep API keys in environment variables; never copy them into the request body or an audit record. Confirm the returned session echoes the intended budget. 2. Prove the stop signal and event order Run a bounded workload designed to cross the small canary cap. The session must become idle with session-level stop_reason: budget_reached . Immediately before the final session.status_idle event, expect a cumulative session.usage snapshot. A thread can report end_turn even when the session reports budget_reached . Use the session-level reason as the authority for the budget decision. 3. Measure overshoot instead of calling it a defect Record usage.list_cost , the cap, active thread count, and the last request on every thread. A 50-cent cap can legitimately pause at 53 cents because the crossing request was admitted while cost was still below the cap. Fail the canary if new model requests begin after the session is at the cap. Do not fail merely because a previously admitted request finishes above it. 4. Verify blocked and accepted events At the cap, a new user.message must receive HTTP 400. Events that settle already-started work remain accepted: tool confirmations, tool results, custom tool results, and interrupts. A settled result must not silently trigger another model request. This distinguishes “record the outcome of existing work” from “authorize more paid work.” 5. Test a controlled resume Read the session's reported usage.list_cost , then raise the cap to at least one cent above that value plus the intended next-work allowance. Reusing the old cap can fail because enforcement uses exact unrounded cost while the API displays rounded cents. Require an explicit operator record before the update: Session ID: Stop reason and last usage event: Original cap / observed list cost: Reason to continue: New maximum: Evidence the loop was fixed: Approver / timestamp: The accepted update resumes automatically. Do not send a duplicate user message “to restart” the task. 6. Test deployment and multiagent boundaries For a scheduled deployment, start two canary sessions and prove each receives the same independent cap. Changing the deployment budget must affect only sessions created afterward. For multiagent work, spawn the maximum approved concurrency, include an advisor if production uses one, and verify every thread shares the session cap. Advisor calls are charged to the same budget. If any selected model lacks a public list price, treat the budget path as unavailable rather than claiming a reliable cap. Decision tree at budget_reached - Was the task already complete? Record the output and close the session without increasing the cap. - Is work waiting only on a tool result? Settle it; do not authorize another model turn yet. - Was there a retry loop, oversized context, or unexpected fan-out? Fix the cause and start a fresh bounded canary. - Is the remaining work known and valuable? Raise the cap once within the pre-approved maximum and record authority. - Is the required spend or outcome still uncertain? Leave the session idle and escalate to a human. Pair this hard stop with AI Gateway spend attribution and the existing Managed Agents memory migration boundary. A session cap limits new spend; it does not explain which user, tool, or memory decision created the cost. Common mistakes Confusing list cost with the invoice. The enforcement meter uses public list rates even when contracted billing is lower. Assuming zero overshoot. The platform stops between requests, not in the middle of one. Size for every active thread. Removing a cap when you meant to raise it. Removal resumes work and prevents the same session from receiving another budget. Treating a per-deployment budget as cumulative. The value is copied onto each new session. Track fleet-wide spend separately. FAQ Can I add a budget to a running session that started without one? No. The API rejects that with HTTP 400. Create a new budgeted session instead. Is budget_reached a completed task? No. It means the platform paused new model work at the financial boundary. Evaluate the task outcome independently. Does a task budget provide the same protection? No. Managed Agents session budgets are hard, dollar-denominated platform caps. Messages API task budgets are advisory token budgets used by supported models to self-regulate, and they are not supported on Claude Code or Cowork surfaces. Top comments (0)