[Suhas Aggarwal (suhasagg)]

Motivation & Context

Developers using Microsoft Agent Framework may need different execution deadlines for different tools, particularly when an agent invokes multiple tools concurrently.

A single global timeout does not adequately represent tool-specific latency requirements or the different failure semantics of read-only and side-effecting operations.

This PR addresses #9235 by providing a focused Python sample demonstrating per-tool asynchronous execution deadlines using the existing FunctionMiddleware extension point and standard asyncio APIs.

The implementation follows the maintainer's guidance to avoid introducing a new core timeout API.

Description & Review Guide

What are the major changes?

1. New sample: per_tool_execution_deadlines.py

   • Demonstrates configurable, independent deadlines for individual tools.
   • Uses the existing FunctionMiddleware extension point.
   • Uses Python 3.10-compatible asyncio APIs.
   • Allows tools without configured deadlines to execute normally.
   • Distinguishes enforced deadline expiry from a TimeoutError raised by the tool itself.
   • Preserves caller-initiated cancellation.

2. Explicit timeout failure semantics

   • Read-only tools: An enforced deadline can produce a recoverable timeout result.
   • Side-effecting tools: An enforced deadline raises MiddlewareFailure, since the operation's outcome may be uncertain and side effects may already have occurred.
   • Preserves existing concurrent-batch failure semantics, including cancellation of in-flight sibling tools when a fatal middleware failure occurs.
   • Does not introduce automatic retries.

3. Cancellation and cleanup guidance

   • Explains that asynchronous cancellation is cooperative.
   • Notes that cleanup may extend beyond the configured deadline.
   • Clarifies that synchronous worker threads and remote operations may continue after cancellation.
   • Explicitly states that deadline expiry does not guarantee rollback, exactly-once execution, or absence of side effects.

4. Focused offline tests and documentation

   • Adds test_per_tool_execution_deadlines.py with 20 tests.
   • Extends the middleware README with usage instructions, expected behavior, and operational limitations.

What is the impact of these changes?

• Provides a practical, reusable example for implementing tool-specific deadlines.
• Clarifies safe timeout handling for read-only versus side-effecting tools.
• Demonstrates cancellation behavior in concurrent tool execution.
• Introduces no new public framework API, no automatic retries, and no breaking changes.
• Keeps the implementation limited to Python samples, tests, and documentation.

What do you want reviewers to focus on?

• Correct distinction between middleware-enforced deadlines and tool-raised TimeoutError.
• Preservation of caller cancellation and cooperative cleanup semantics.
• Appropriate use of MiddlewareFailure for uncertain side-effecting outcomes.
• Compatibility with existing concurrent-batch failure behavior.
• Clarity and maintainability of the sample implementation.

Validation

Local validation completed successfully:

• 20/20 sample tests passed, including real Agent-level concurrent-batch cancellation coverage.
• Existing framework regression test for concurrent sibling cancellation passed.
• Ruff lint and formatting checks passed.
• git diff --check passed.

All tests are offline and do not require external model API credentials.

Related Issue

Fixes #9235

Implementation follows the maintainer's October 27 guidance to use existing middleware and asyncio APIs rather than changing the core framework.

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 guidance, test development. The changes were reviewed and validated locally, including the focused test suite, existing framework regression coverage, and lint checks.

Contribution Checklist

• The changed Python files pass Ruff lint and formatting checks.
• All 20 added sample tests pass, including integration coverage.
• The PR is scoped to the existing Python middleware sample architecture.
• This PR links to an issue with explicit maintainer agreement on the implementation direction.
• This is not a breaking change.

[Copilot]

🟡 Changes recommended

Deadline cleanup can swallow caller cancellation and suppress downstream MiddlewareFailure, converting a fatal error into a recoverable timeout for read-only tools instead of aborting the concurrent batch.

2 open issues

• Preserve MiddlewareFailure during cancellation cleanup · New
• Propagate caller cancellation during deadline cleanup · New

What changed in this PR

Adds a Python sample for #9235 demonstrating per-tool asynchronous deadlines through existing FunctionMiddleware, without introducing a new core API.

Changes:

• Adds configurable deadlines with recoverable read-only timeouts and fatal side-effecting timeouts.
• Adds offline tests covering execution, cancellation, cleanup, and concurrent-batch behavior.
• Documents usage and limitations, including cooperative cancellation and uncertain remote outcomes.

File	Description
python/​samples/​02-agents/​middleware/​test_per_tool_execution_deadlines.py	Adds focused middleware tests and Agent-level batch cancellation coverage.
python/​samples/​02-agents/​middleware/​README.md	Documents commands, timeout behavior, and operational limitations.
python/​samples/​02-agents/​middleware/​per_tool_execution_deadlines.py	Implements deadline policies, middleware, and an offline demonstration.

_{Review effort: Balanced}