[Suhas Aggarwal (suhasagg)]

Motivation & Context

Issue #9239 discusses per-tool rate limiting and admission control for Python Agent Framework tool execution.

The maintainer recommended demonstrating this capability through the existing FunctionMiddleware extension point rather than introducing a new framework-level rate-limiting API.

This PR follows that direction by providing a focused, opt-in sample showing how applications can enforce in-process, per-tool quotas before invoking tools.

The example is useful for agents interacting with external APIs, rate-limited services, or tools where excessive concurrent requests should be controlled.

Description & Review Guide

What are the major changes?

• Add per_tool_rate_limiting.py, demonstrating token-bucket admission control through FunctionMiddleware.
• Support independently configured quotas by tool name.
• Use time.monotonic() for refill accounting and threading.Lock for concurrency-safe token updates.
• Reject over-quota calls before invoking call_next(), preventing downstream tool execution.
• Preserve cancellation and exception propagation.
• Support middleware-instance reuse across event loops without binding synchronization to a particular event loop.
• Add test_per_tool_rate_limiting.py with 17 tests covering policy validation, quota accounting, refill, concurrent admission, cancellation, event-loop reuse, and framework middleware integration.
• Update the middleware samples README with execution instructions, quota scope, and limitations.

What is the impact of these changes?

This is a sample-only contribution. It does not modify core framework behavior, public APIs, or existing middleware contracts.

The sample demonstrates application-local admission control and intentionally does not claim distributed enforcement, automatic retries, or exactly-once execution.

Rate-limit rejection is represented as a tool-visible result rather than using MiddlewareTermination to stop the entire tool loop.

What do you want reviewers to focus on?

1. Whether the sample follows the existing FunctionMiddleware conventions.
2. Whether quota accounting and concurrent admission are sufficiently safe and clear.
3. Whether rejection-before-execution semantics are appropriate.
4. Whether cancellation behavior, tests, and documented limitations adequately demonstrate the intended approach.

Related Issue

Fixes #9239.

This PR implements the sample-only direction discussed in the issue. It does not attempt to introduce the broader core API originally proposed.

This also replaces the approach in the previously closed PR #9293 by keeping all rate-limiting logic inside the samples directory, without adding public framework exports.

Local Validation

Executed locally using Python 3.10:

• python -m pytest test_per_tool_rate_limiting.py -v — 17 passed
• ruff check per_tool_rate_limiting.py test_per_tool_rate_limiting.py — passed
• ruff format --check per_tool_rate_limiting.py test_per_tool_rate_limiting.py — passed
• python per_tool_rate_limiting.py — passed, demonstrating two admitted calls followed by one rejected call

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details:

AI assistance was used for implementation, test development. I reviewed the generated changes and validated the implementation locally using pytest, Ruff, and sample execution.

Contribution Checklist

• The submitted sample passes the local checks listed above.
• All 17 sample tests pass.
• The PR follows the Contribution Guidelines (confirm after reviewing them).
• This PR links to an agreed issue with no competing open PR (confirm current issue status and competing PRs).
• This is not a breaking change.

[Copilot]

🟡 Changes recommended

Sampling time before acquiring the lock can admit calls beyond the configured burst, and normal CI commands do not collect the 17 new regression tests.

2 open issues

• CI test discovery omits 17 new regression cases · New
• Clock sampled before lock causes stale token admission · New

What changed in this PR

Adds a sample-only approach to per-tool rate limiting through Python’s existing FunctionMiddleware extension point, following the direction of #9239 without changing core APIs.

Changes:

• Introduces per-tool token buckets with lock-protected accounting and rejection before tool execution.
• Adds 17 regression cases covering quotas, concurrency, cancellation, event-loop reuse, and middleware integration.
• Documents execution instructions, quota ownership, and in-process limitations.

File	Description
python/​samples/​02-agents/​middleware/​test_per_tool_rate_limiting.py	Adds offline admission-control and integration tests.
python/​samples/​02-agents/​middleware/​README.md	Documents sample usage, rejection behavior, and limitations.
python/​samples/​02-agents/​middleware/​per_tool_rate_limiting.py	Implements token-bucket middleware and a standalone demonstration.

_{Review effort: Balanced}