Python: support mixed workflow invocation kwargs

[Dineshsuriya D (droideronline)]

Motivation & Context

Workflow runs currently support either flat global function_invocation_kwargs or executor-specific mappings. Workflows that need shared tool context, such as tenant or request metadata, plus agent-specific tool settings cannot express both through the public API. This extends the kwargs propagation completed in #2895 / #2894.

Description & Review Guide

• What are the major changes?
  • Support an explicit "__global__" mapping alongside executor-specific mappings in function_invocation_kwargs and client_kwargs.
  • Merge global kwargs with executor-specific kwargs in AgentExecutor, with specific values taking precedence.
  • Preserve mixed kwargs when a workflow invokes a nested workflow.
  • Add regression coverage for mixed function invocation kwargs and update resolution expectations.
• What is the impact of these changes?
  • Existing flat-global and per-executor forms remain compatible.
  • Users can now write {"__global__": common_kwargs, "executor_id": specific_kwargs}.
• What do you want reviewers to focus on?
  • Whether "__global__" is the preferred public spelling and whether merge precedence is intuitive.
  • Whether the same merge behavior should apply to client_kwargs as implemented here.

Related Issue

Fixes #7962

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) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Luis Rodriguez (luisangelrod)]

The merge precedence in AgentExecutor looks consistent, and I verified the two affected workflow test modules plus Ruff check and format locally.

Could you add regression coverage for the other two behaviors described by this PR?

1. Mixed client_kwargs, including an executor-specific value overriding the same global key.
2. Mixed kwargs crossing a WorkflowExecutor, with a global value reaching the inner agents and an inner executor-specific override still winning.

The current new test covers only direct function_invocation_kwargs, so the client and nested propagation paths can regress independently. The Workflow.run docstring also explains "global" for function_invocation_kwargs but not client_kwargs, even though both accept it.

Since #7962 is still labeled triage, maintainer confirmation of "global" as the public spelling also seems important before merge.

[Dineshsuriya D (droideronline)]

Addressed in cda37e4. Added mixed client_kwargs coverage, mixed nested WorkflowExecutor coverage, and documented the collision-free WorkflowInvocationKwargs wrapper for both function_invocation_kwargs and client_kwargs. The wrapper uses global_kwargs plus executor_kwargs with executor-specific values taking precedence.

[Luis Rodriguez (luisangelrod)]

The follow-up addresses the compatibility, nested-routing, client-kwargs, and documentation concerns. The two targeted workflow test modules pass, and strict core Pyright passes locally.

Two repository requirements remain:

1. uv run poe syntax -P core -C reports and auto-fixes the __all__ ordering in agent_framework/__init__.pyi; WorkflowInvocationKwargs should sort before WorkflowMessage.
2. Because this adds a root-level public API, please update python/packages/core/AGENTS.md as required by the package instructions. Since agent-framework-core is released, it would also be useful for a maintainer to confirm whether this wrapper is intended to be released immediately or explicitly staged.

After those are resolved, the implementation looks ready for another pass.