Python: fix(declarative): keep internal workflow-routing kwargs out of the Agent.run splat

[Yufeng He (he-yufeng)]

Motivation & Context

Running a declarative workflow through AG-UI fails on the first InvokeAzureAgent step with TypeError: Agent.run() got an unexpected keyword argument '_raw_function_invocation_kwargs'. The workflow state bag (WORKFLOW_RUN_KWARGS_KEY) carries internal routing copies (_raw_function_invocation_kwargs, _raw_client_kwargs) next to the public kwargs, and the declarative agent step splatted the whole bag into Agent.run, which accepts only public parameters. The core AgentExecutor already filters through _prepare_agent_run_args; this path never did.

Description & Review Guide

• What are the major changes? In _executors_agents.py, the splat into agent.run(..., **run_kwargs) now drops underscore-prefixed internal keys (in addition to the already-excluded options). The full bag still reaches options["additional_function_arguments"], so nested-workflow remapping that reads the raw copies keeps working unchanged.
• What is the impact of these changes? Declarative agent steps run through AG-UI-style invocations again on stacks where the resolved-kwargs state is absent (the reporter's 1.18.0 core / 1.0.4 declarative combination). When the resolved state exists, the prepare hook already strips these keys, so the new filter is a no-op on that path.
• What do you want reviewers to focus on? The legacy-checkpoint expectation in test_workflow_run_kwargs_survive_file_checkpoint_restore changed: it previously pinned the raw key being forwarded to agent.run, which is exactly the behavior that TypeErrors against the real Agent.run signature (the pinned mock accepted anything). It now asserts the raw key stays out of the call while remaining in additional_function_arguments.

The regression test drives the executor with a strict-signature stub agent (no **kwargs): on the old code it raises the reported TypeError, on the new code the run completes and the full bag still reaches tool forwarding. Verified: test_graph_executors.py 104 passed / 10 skipped (existing environment skips) on Python 3.13, ruff check and format per repo config.

Related Issue

Fixes #8413

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

[Copilot]

🟢 Approval recommended

No unresolved review issues remain, and regression coverage is included.

Pull request overview

Fixes declarative workflow failures by preventing internal routing kwargs from being passed to Agent.run.

Changes:

• Filters underscore-prefixed internal kwargs before agent invocation.
• Preserves the full kwargs bag for tool forwarding.
• Adds regression and checkpoint coverage.

File summaries

File	Description
python/packages/declarative/tests/test_graph_executors.py	Adds regression coverage and updates checkpoint expectations.
python/packages/declarative/agent_framework_declarative/_workflows/_executors_agents.py	Filters internal kwargs before invoking agents.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite (auto)

Note

Copilot is running an experiment and ran this review at Lite.

---

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