Skip to content

.NET: add token and time budgets to LoopAgent - #9165

Open
Mark Licata (marklicata) wants to merge 5 commits into
microsoft:mainfrom
marklicata:agent-budget-dotnet
Open

.NET: add token and time budgets to LoopAgent#9165
Mark Licata (marklicata) wants to merge 5 commits into
microsoft:mainfrom
marklicata:agent-budget-dotnet

Conversation

@marklicata

@marklicata Mark Licata (marklicata) commented Oct 7, 2026 •
edited
Loading

Copy link
Copy Markdown

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 token and wall-clock budgets to LoopAgent.

This is the .NET half of the work previously proposed in #8994, split per language at the reviewers' request. The Python counterpart is #9164 and uses the same exit-reason strings.

Description & Review Guide

What are the major changes?

  • LoopAgentOptions.MaxTokens (long?) and MaxDuration (TimeSpan?)
  • LoopAgent (non-streaming) stamps LoopExitReason.TokenBudgetExceeded / TimeBudgetExceeded on budget stops and LoopExitReason.IterationCapReached when MaxIterations fires
  • LoopExitReason: [Experimental] static class with AdditionalPropertiesKey, IterationCapReached, TokenBudgetExceeded, TimeBudgetExceeded
  • PublicAPI.Unshipped.txt updated for all 5 target frameworks

What is the impact of these changes?

Opt-in; LoopAgent without budgets behaves as today. LoopExitReason is also introduced by the .NET signal-protocol PR; whichever lands second unions the constants during its merge from main.

What do you want reviewers to focus on?

  • Budget check ordering relative to the evaluator
  • Streaming limitation: the budget stops the loop but can't stamp AdditionalProperties

Sub-agent usage

MaxTokens also counts sub-agent tokens. An internal AsyncLocal scope on ChatClientAgent rolls the usage of sub-agents called via AsAIFunction and BackgroundAgentsProvider into the parent's AgentResponse.Usage. This applies to both RunAsync and RunStreamingAsync; a streaming run ends with a usage-only update. Each layer of A→B→C is counted once. The invoke_agent telemetry spans still report each agent's own usage, and there is no public API change.

Known gaps, documented on MaxTokens:

  • Failed or cancelled sub-agents return no response, so their tokens aren't counted.
  • Agents that custom tools call directly through RunAsync aren't counted.
  • Each background task is charged once, to the parent run that first sees it finish. Tasks that finish after the last parent run, or are only finalized at release, aren't counted.

Related Issue

Part of #8862, together with #9164 for Python. 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

@marklicata @claude
.NET: add token and time budgets to LoopAgent
3d8a4b8 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings October 7, 2026 15:34
@agent-framework-automation agent-framework-automation Bot added the .NET Usage: [Issues, PRs], Target: .Net label Oct 7, 2026
@marklicata Mark Licata (marklicata) mentioned this pull request Oct 7, 2026
Open
5 tasks done
@marklicata Mark Licata (marklicata) mentioned this pull request Oct 7, 2026
Closed
5 tasks done
Copilot AI reviewed Oct 7, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Duration limits cannot interrupt blocked calls or streams, leaving wall-clock enforcement incomplete.

2 open findings
What changed in this PR

Adds opt-in resource budgets to .NET LoopAgent, complementing the Python work in #9164.

Changes:

  • Adds token and duration limits with checks before evaluators.
  • Introduces exit-reason constants for budget and iteration-cap stops.
  • Adds non-streaming tests and updates all five public API baselines.
File Description
dotnet/​tests/​Microsoft.Agents.AI.UnitTests/​Harness/​Loop/​LoopAgentBudgetTests.cs Tests non-streaming budget stops and evaluator ordering.
dotnet/​src/​Microsoft.Agents.AI/​PublicAPI/​netstandard2.0/​PublicAPI.Unshipped.txt Records new budget APIs.
dotnet/​src/​Microsoft.Agents.AI/​PublicAPI/​net9.0/​PublicAPI.Unshipped.txt Records new budget APIs.
dotnet/​src/​Microsoft.Agents.AI/​PublicAPI/​net8.0/​PublicAPI.Unshipped.txt Records new budget APIs.
dotnet/​src/​Microsoft.Agents.AI/​PublicAPI/​net472/​PublicAPI.Unshipped.txt Records new budget APIs.
dotnet/​src/​Microsoft.Agents.AI/​PublicAPI/​net10.0/​PublicAPI.Unshipped.txt Records new budget APIs.
dotnet/​src/​Microsoft.Agents.AI/​Harness/​Loop/​LoopExitReason.cs Defines experimental exit-reason constants.
dotnet/​src/​Microsoft.Agents.AI/​Harness/​Loop/​LoopAgentOptions.cs Adds validated budget options.
dotnet/​src/​Microsoft.Agents.AI/​Harness/​Loop/​LoopAgent.cs Tracks budgets and stops subsequent iterations.

🧠 Review effort: Balanced

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

Comment thread dotnet/src/Microsoft.Agents.AI/Harness/Loop/LoopAgent.cs
Comment thread dotnet/src/Microsoft.Agents.AI/Harness/Loop/LoopAgent.cs Outdated
@marklicata
Mark Licata (marklicata) marked this pull request as ready for review October 7, 2026 15:57
@marklicata @claude
Address review feedback: document MaxDuration semantics, add streamin…
f41c72e 
…g budget tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@westey-m westey (westey-m) self-assigned this Oct 9, 2026
westey-m
westey (westey-m) reviewed Oct 9, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI/Harness/Loop/LoopAgentOptions.cs Outdated
westey-m
westey (westey-m) reviewed Oct 9, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI/Harness/Loop/LoopAgent.cs Outdated
@marklicata @claude
Address review feedback: Throw helper, warn when token usage is missing
ce755bf 
- Use Throw.IfLessThanOrEqual for MaxTokens validation.
- Log a warning (once per run) when MaxTokens is set but the inner
  agent's response reports no token usage, in both RunAsync and
  RunStreamingAsync.
- Document what MaxTokens counts: inner agent input+output tokens
  (TotalTokenCount, falling back to Input+Output); evaluator and judge
  usage is not counted.
- Add tests for the warning, option validation, and judge usage
  exclusion.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@marklicata @claude
.NET: roll up sub-agent token usage into the calling agent's response
13fad81 
ChatClientAgent now adds the usage of the sub-agents it invokes to its own
AgentResponse.Usage, in both RunAsync and RunStreamingAsync, so that
LoopAgentOptions.MaxTokens also counts sub-agent tokens.

- An internal AsyncLocal SubAgentUsageScope (modelled on ServedModelScope)
  holds a lock-based usage accumulator per ChatClientAgent run. It is set up
  before context providers run and re-established after each streaming yield.
- AsAIFunction adds the sub-agent's reported usage to the caller's scope and
  clears the scope for the sub-agent's own run, so A -> B -> C counts each
  layer once. Concurrent tool invocations are summed safely.
- FunctionInvokingChatClient overwrites response usage with its own model
  call totals, so the merge happens after it returns. Streaming runs end with
  a usage-only update carrying the sub-agent total.
- BackgroundAgentsProvider charges each successful background run once, to
  the parent run that first observes its completion (context provision or
  the wait/result tools). Runs that finish after the last parent run, or are
  only finalized at release, are not counted.
- OpenTelemetryAgent keeps reporting each agent's own usage on its
  invoke_agent span; the rolled-up sub-agent usage is excluded.
- Failed or cancelled sub-agents and agents invoked directly from custom
  tools are not counted. No public API changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@marklicata @claude
Merge remote-tracking branch 'origin/main' into agent-budget-dotnet
363c4fc 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

2 active deployments
integration — 363c4fca Deployed Oct 13, 2026 by marklicata via dotnet-test (net472, windows-latest, Release, true, integration) #30134
github-app-auth — 363c4fca Deployed Oct 13, 2026 by marklicata via add_label #25203
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@westey-m westey (westey-m) westey-m requested changes
@eavanvalkenburg Eduard van Valkenburg (eavanvalkenburg) Awaiting requested review from eavanvalkenburg eavanvalkenburg is a code owner
@SergeyMenshykh SergeyMenshykh Awaiting requested review from SergeyMenshykh SergeyMenshykh is a code owner
@rogerbarreto Roger Barreto (rogerbarreto) Awaiting requested review from rogerbarreto rogerbarreto is a code owner
@moonbox3 Evan Mattson (moonbox3) Awaiting requested review from moonbox3 moonbox3 is a code owner
@baywet Vincent Biret (baywet) Awaiting requested review from baywet baywet is a code owner
@peibekwe Peter Ibekwe (peibekwe) Awaiting requested review from peibekwe peibekwe is a code owner

Requested changes must be addressed to merge this pull request.

Assignees

@westey-m westey (westey-m)

Labels

.NET Usage: [Issues, PRs], Target: .Net

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@marklicata @westey-m