Python: Add max_function_calls to FunctionInvocationConfiguration (#2329)

[eavanvalkenburg]

Summary

Addresses #2329 — adds a new per-request max_function_calls setting to FunctionInvocationConfiguration that limits the total number of individual function invocations across all iterations within a single get_response call.

Motivation

max_iterations limits LLM roundtrips, but each roundtrip can execute multiple tools in parallel. Setting max_iterations=3 could result in 30+ function executions. There was no way to cap the actual number of tool calls per request.

Changes

Core (_tools.py)

• New field: max_function_calls: int | None on FunctionInvocationConfiguration (default: None = unlimited)
• Tracking: Both _get_response and _stream loops now track cumulative function call count via function_call_count on FunctionRequestResult
• Enforcement: When max_function_calls is reached, forces tool_choice="none" to get a final text response
• Validation: normalize_function_invocation_configuration validates the new field (must be ≥1 or None)
• Improved docstrings: Clarified semantics of all three control mechanisms:
  • max_iterations — caps LLM roundtrips (each may invoke multiple tools in parallel)
  • max_function_calls (new) — caps total individual function invocations per request
  • max_invocations (on tool) — lifetime cap on a specific tool instance

Tests

• 4 new tests: parallel calls limit, single calls limit, None means unlimited, config validation

Sample

• New samples/02-agents/tools/control_total_tool_executions.py showcasing all three mechanisms with 4 scenarios

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_tools.py	876	94	89%	166–167, 322, 324, 342–344, 351, 369, 383, 390, 397, 413, 415, 422, 459, 484, 488, 505–507, 554–556, 578, 632, 654, 717–723, 759, 770–781, 803–805, 810, 814, 828–830, 869, 938, 948, 958, 1014, 1045, 1064, 1342, 1399, 1419, 1490–1494, 1616, 1620, 1644, 1670, 1672, 1688, 1690, 1775, 1805, 1825, 1827, 1880, 1943, 2134–2135, 2187, 2200, 2210–2211, 2249–2250, 2311, 2317, 2324
TOTAL	22169	3476	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4269	240 💤	0 ❌	0 🔥	1m 16s ⏱️

[Copilot]

Pull request overview

Adds a new per-request function invocation limiter (max_function_calls) to the Python tool-invocation loop to better control total tool execution cost within a single get_response call.

Changes:

• Introduces max_function_calls: int | None in FunctionInvocationConfiguration, including normalization/validation.
• Tracks cumulative tool executions via function_call_count from tool-processing steps and forces tool_choice="none" once the limit is reached.
• Adds unit tests and a new sample demonstrating max_iterations, max_function_calls, and per-tool max_invocations.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
python/packages/core/agent_framework/_tools.py	Adds max_function_calls, validation, tracking, and enforcement logic in non-streaming and streaming loops.
python/packages/core/tests/core/test_function_invocation_logic.py	Adds tests covering the new configuration and validation.
python/samples/02-agents/tools/control_total_tool_executions.py	New sample demonstrating all three limiting mechanisms with multiple scenarios.
python/samples/01-get-started/06_host_your_agent.py	Disables formatting/lint rule to preserve snippet tag layout.

Comments suppressed due to low confidence (1)

python/packages/core/agent_framework/_tools.py:2117

• total_function_calls is incremented for approval-executed tool calls, but the max_function_calls check isn’t applied until after the subsequent model response’s tools are processed. If approvals alone exhaust the budget, the next super_get_response(...) still runs with tool_choice unchanged, allowing the model to request (and the loop to execute) more tool calls beyond the limit. Add a check immediately after updating total_function_calls from approval_result (and similarly in _stream) to force tool_choice="none" before the next model roundtrip when the budget is reached.

                        response = ChatResponse(messages=prepped_messages)
                        break
                    errors_in_a_row = approval_result["errors_in_a_row"]
                    total_function_calls += approval_result.get("function_call_count", 0)

                    response = await super_get_response(
                        messages=prepped_messages,
                        stream=False,
                        options=mutable_options,
                        **filtered_kwargs,