[Mark Licata (marklicata)]

Motivation & Context

Autonomous loops need explicit resource limits. Without them, a confused or looping agent can burn tokens indefinitely or hold a session open on a slow external tool, and neither is safe for production. This adds AgentBudget so operators can bound AgentLoopMiddleware by token spend and wall-clock time.

This is the Python half of the work previously proposed in #8994, split per language at the reviewers' request. The .NET counterpart is #9165.

Description & Review Guide

What are the major changes?

• AgentBudget dataclass: max_tokens: int | None and max_duration: float | None, both optional with no defaults
• AgentLoopMiddleware: new budget: AgentBudget | None argument. Budget checks run before should_continue, so an expensive judge isn't called once a budget is exhausted.
• Token tracking: cumulative total_token_count per iteration from UsageDetails, falling back to input + output
• Time tracking: time.monotonic() at loop start, checked per iteration
• Exit reason stamped in additional_properties["loop_exit_reason"]: "token_budget_exceeded" / "time_budget_exceeded" on budget stops (non-streaming only), "iteration_cap_reached" when max_iterations fires

What is the impact of these changes?

Opt-in; loops without a budget behave as today.

Sub-agent usage

Sub-agent tokens count toward max_tokens. This is not configurable.

• Agent.as_tool rolls the sub-agent's usage_details into the parent's response usage_details, in both streaming and non-streaming runs. This also holds when the sub-agent stops on an approval or user-input request. Nested A→B→C counts each layer once.
• BackgroundAgentsProvider charges each finished task's usage once, to the parent run that first observes the completion.
• invoke_agent telemetry spans still report each agent's own usage only.
• Known gaps: failed or cancelled sub-agent runs produce no response, so their tokens aren't counted. Background tasks that are never observed, or are abandoned at release_session, aren't counted. Custom tools that call agent.run directly aren't counted.

What do you want reviewers to focus on?

• Check ordering: after the pending-approval escape hatch, before should_continue
• The total_token_count fallback when providers omit it
• Streaming limitation: the budget stops the loop but can't stamp additional_properties

Related Issue

Part of #8862, together with #9165 for .NET. The issue is closed manually once both PRs have merged.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Wall-clock limits do not interrupt in-flight work, and token fallback and streaming enforcement lack tests.

2 open findings

• Enforce max_duration during in-flight calls and streaming · New
• Test token budget fallback using split input and output counts · New

What changed in this PR

Adds opt-in token and wall-clock budgets for Python autonomous agent loops.

Changes:

• Introduces and exports AgentBudget.
• Enforces budgets and records loop exit reasons.
• Adds non-streaming budget tests.

File	Description
python/​packages/​core/​agent_framework/​_harness/​_loop.py	Implements budget validation and enforcement.
python/​packages/​core/​agent_framework/​__init__.py	Exports AgentBudget at runtime.
python/​packages/​core/​agent_framework/​__init__.pyi	Exports the typed public API.
python/​packages/​core/​tests/​core/​test_harness_loop.py	Adds budget behavior and validation tests.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Jose Alvarez (jpalvarezl)]

When the budget fires, setdefault preserves any stale loop_exit_reason supplied by an inner provider or nested loop, so callers can see the wrong reason even though this middleware stopped for the budget. Please assign the framework-owned reason unconditionally, and do the same for the cap paths, matching #9162's stale-reason behavior. Add a regression starting with a pre-existing reason.