Python: Add sequential function invocation option

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Function calls returned in one assistant message are currently always executed concurrently. Stateful tools can therefore race when a model batches dependent operations such as writing a file and then reading it.

This change adds a batch-wide execution control so callers can opt into deterministic sequential invocation without introducing per-tool concurrency groups or changing the existing default.

Description & Review Guide

• What are the major changes?
  • Add allow_concurrent_invocation to FunctionInvocationConfiguration, defaulting to True.
  • Execute fully executable calls one at a time in model order when the option is False, while retaining per-call task and ContextVar isolation.
  • Preserve model order across stateful and stateless approval replay, including mixed local and Host-owned batches.
  • Keep session-backed approval batches atomic across resume calls: decisions may be accumulated, but tools do not execute and the model is not resumed until every approval in the original batch has a decision.
  • Apply middleware termination after the already accepted batch finishes, matching concurrent-batch behavior without synthetic skipped results.
  • Document the execution and approval-replay contracts and add focused regression coverage.
• What is the impact of these changes?
  Existing behavior remains unchanged by default. Agents with stateful tools can opt into sequential execution at the function-invocation layer, independently of provider-side allow_multiple_tool_calls. Approval replay cannot reorder sequential calls or partially execute a session-backed approval batch based on response arrival timing.
• What do you want reviewers to focus on?
  Please focus on the sequential scheduling path in _try_execute_function_call_groups, the atomic approval staging in _resolve_approval_responses, and preservation of model order across approval and Host-owned replay.

Related Issue

Fixes #7386

Supersedes #8204 with a narrower implementation. Thank you to pratik wayase (@PratikWayase) for the original investigation and implementation work that established the batch-wide allow_concurrent_invocation direction.

Selective per-tool concurrency controls remain deferred to #7914.

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. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after a language prefix) — a workflow keeps the label and the title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Approval replay can reverse model order under sequential execution, and the specification matrix is incomplete.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds opt-in sequential Python tool invocation to prevent races between dependent stateful tools.

Changes:

• Adds allow_concurrent_invocation, defaulting to True.
• Implements ordered execution, context isolation, and skipped termination results.
• Documents and tests the new behavior.

File summaries

File	Description
python/packages/core/agent_framework/_tools.py	Adds sequential scheduling.
python/packages/core/tests/core/test_tools.py	Adds focused regression tests.
docs/specs/004-python-function-calling-loop.md	Documents execution semantics.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Balanced

---

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

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): bd7f2e065ef0
Model: gpt-5.6-sol-fast

Overview

The PR adds an opt-in serial scheduler while preserving concurrent execution by default, isolating each invocation's context, and emitting terminal results for a suffix skipped after middleware termination. Focused tests cover direct ordering, context isolation, default behavior, and suffix skipping. One residual budget-accounting defect treats those unstarted suffix calls as executed, which can prevent a pending approved call from running on re-entry.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/_tools.py