Add token and wall-clock budget enforcement to AgentLoopMiddleware #8862

Summary

AgentLoopMiddleware has one budget dimension today: max_iterations (default 10). This issue proposes adding token budget and wall-clock time budget as first-class parameters, integrated into the loop's existing stop evaluation, in both the Python and .NET implementations.

We intend to take on implementation.

User need

When a user delegates a task to an autonomous agent, they are accepting a cost in tokens and time. Two failure modes need to be bounded:

1. Token runaway — an agent in a confused or stuck loop continues issuing LLM calls. Without a token cap, this continues until something external intervenes.
2. Time runaway — an agent waiting on a slow or hung external system doesn't burn tokens, but holds a session open indefinitely. Token budgets alone don't catch this.

Operators deploying autonomous agents need explicit, enforced limits — not defaults that permit unbounded runs.

Developer need

There is no standard token or wall-clock budget primitive in MAF. Every team building autonomous loops implements cost controls from scratch, with different semantics for what happens when limits are hit, and no shared warning-threshold mechanism. Wall-clock limits in particular are rarely implemented correctly.

Additional gaps:

• Hierarchical chargeback: when an agent spawns sub-agents via BackgroundAgentsProvider, sub-agent token spend is invisible to the parent's budget.
• Warning thresholds: teams find out a budget was exceeded after the fact, not at 80% when the agent could still wrap up cleanly.

What's already there

• Python: AgentLoopMiddleware (python/packages/core/agent_framework/_harness/_loop.py) — has max_iterations checked in _evaluate_stop before should_continue. This is the correct integration point for additional budget dimensions. ContextWindowCompactionStrategy handles context window tokens for compaction, not cost control.
• .NET: AgentLoopMiddleware equivalent in dotnet/src/Microsoft.Agents.AI/Harness/Loop/ and dotnet/src/Microsoft.Agents.AI.Harness/. BackgroundAgentsProvider exists in both languages.
• Neither implementation has max_tokens, max_duration_seconds, warning thresholds, or hierarchical chargeback.

Proposal

An AgentBudget type with three independently-configured dimensions, added as an optional parameter to AgentLoopMiddleware:

max_tokens and max_duration_seconds have no framework defaults intentionally — they are too workload-specific. For autonomous sessions, the framework should require these to be set explicitly.

Integration into stop evaluation: budget checks run before should_continue, consistent with how max_iterations is already handled. Each dimension that fires produces a typed exit reason (see related issue #8860 on typed exit reasons).

Wall-clock enforcement: a background async task started when the loop begins. On expiry it cancels the loop.

Warning events at 80%: when any budget dimension reaches 80% of its limit, emit a warning into the agent context or session state so the agent can wrap up before the hard cap fires.

Hierarchical chargeback: child agent token spend (via BackgroundAgentsProvider) reduces the parent's remaining max_tokens. Wall-clock budget does not propagate — each agent in a hierarchy has its own time limit.

Scope

• Both Python and .NET implementations are in scope. The Python harness (python/packages/core/agent_framework/_harness/) and .NET harness (dotnet/src/Microsoft.Agents.AI/Harness/ and dotnet/src/Microsoft.Agents.AI.Harness/) maintain feature parity; changes to one require equivalent changes in the other.
• AgentBudget type: new in core (Python and .NET), experimental-flagged
• Integration into AgentLoopMiddleware stop evaluation in both languages
• Background async task for wall-clock enforcement
• Chargeback hook into BackgroundAgentsProvider (may require design coordination)

Open questions

1. Where should warning events surface — agent context injection, session state, a new event type, or all three?
2. The chargeback integration with BackgroundAgentsProvider needs design review — specifically, whether chargeback should be opt-in or automatic when a budget is configured.

Related

• Add signal-based completion detection and typed exit reasons to AgentLoopMiddleware #8860 — typed exit reasons (budget firing produces a typed exit reason)
• Add AsyncRequestBroker utility and shell execution audit log #8861 — AsyncRequestBroker (independent, but part of the same autonomous agent primitive set)