Python: [Bug]: Declarative InvokeAzureAgent splatters _raw_function_invocation_kwargs into Agent.run()

[likebean]

Description

When running a declarative workflow through AG-UI, InvokeAzureAgent fails with:

TypeError: Agent.run() got an unexpected keyword argument '_raw_function_invocation_kwargs'

What happened

1. agent-framework-ag-ui calls workflow.run(function_invocation_kwargs={"forwarded_props": ...}).
2. agent-framework-core stores both the resolved kwargs and the original payload under the internal state key _raw_function_invocation_kwargs (intended for nested WorkflowExecutor remapping).
3. agent-framework-declarative InvokeAzureAgent reads the entire WORKFLOW_RUN_KWARGS bag and does await agent.run(..., **run_kwargs), which forwards _raw_function_invocation_kwargs as a real keyword argument.
4. Agent.run() only accepts the public name function_invocation_kwargs (no **kwargs), so it raises TypeError.

What we expected

_raw_function_invocation_kwargs / _raw_client_kwargs should stay internal to the workflow state (for nested workflow routing). Declarative agent invocation should only pass public Agent.run parameters (e.g. function_invocation_kwargs, client_kwargs, session, tools, …), typically via the already-populated options["additional_function_arguments"] path.

Steps to reproduce

1. Install current PyPI latest: agent-framework-core==1.18.0, agent-framework-declarative==1.0.4, agent-framework-ag-ui==1.3.0.
2. Build a declarative workflow with an InvokeAzureAgent action (no tools required on the agent).
3. Run it through the AG-UI workflow host (so function_invocation_kwargs={"forwarded_props": ...} is passed).
4. Observe the TypeError on the first agent step.

Code Sample

Relevant declarative path (installed 1.0.4):

# agent_framework_declarative/.../_executors_agents.py
run_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY, {})
if run_kwargs:
    options = dict(run_kwargs.get("options") or {})
    options["additional_function_arguments"] = run_kwargs
    run_kwargs = {k: v for k, v in run_kwargs.items() if k != "options"}

result = await agent.run(messages_for_agent, options=options, **run_kwargs)
#                                                                  ^^^^^^^^^^
# includes "_raw_function_invocation_kwargs" when AG-UI forwarded nested props

Core stores the raw key when values are mappings (AG-UI always does):

# agent_framework/_workflows/_workflow.py (1.18.0)
if function_invocation_kwargs is not None:
    combined_kwargs["function_invocation_kwargs"] = self._resolve_invocation_kwargs(...)
    if isinstance(function_invocation_kwargs, WorkflowInvocationKwargs) or any(
        isinstance(value, Mapping) for value in function_invocation_kwargs.values()
    ):
        combined_kwargs[RAW_FUNCTION_INVOCATION_KWARGS_KEY] = function_invocation_kwargs

AG-UI trigger:

# agent_framework_ag_ui/_workflow_run.py (1.3.0)
fwd_kwargs["function_invocation_kwargs"] = {"forwarded_props": forwarded_props}

Suggested fix (declarative): before calling Agent.run, remap/drop internal keys:

if "_raw_function_invocation_kwargs" in run_kwargs:
    run_kwargs.setdefault(
        "function_invocation_kwargs",
        run_kwargs.pop("_raw_function_invocation_kwargs"),
    )
    run_kwargs.pop("_raw_function_invocation_kwargs", None)
# similarly for _raw_client_kwargs → client_kwargs
allowed = {
    "session", "middleware", "tools", "options", "compaction_strategy",
    "tokenizer", "function_invocation_kwargs", "client_kwargs", "stream",
}
run_kwargs = {k: v for k, v in run_kwargs.items() if k in allowed}

Error Messages / Stack Traces

TypeError: Agent.run() got an unexpected keyword argument '_raw_function_invocation_kwargs'

File ".../agent_framework_declarative/_workflows/_executors_agents.py", in _invoke_agent_and_store_results
    result: Any = await agent.run(messages_for_agent, options=options, **run_kwargs)
File ".../agent_framework_declarative/_workflows/_executors_agents.py", in handle_action
    raise AgentInvalidResponseException(
        f"Agent '{agent_name}' invocation failed: {e}"
    )

Package Versions

agent-framework-core: 1.18.0, agent-framework-declarative: 1.0.4, agent-framework-ag-ui: 1.3.0 (PyPI latest as of 2026-09-16)

Python Version

Python 3.12

Additional Context

• This is reproducible with a minimal declarative graph: Foreach → InvokeMcpTool → InvokeAzureAgent (agent has no tools). Failure happens at InvokeAzureAgent even when MCP succeeds.
• Orchestration / direct Agent.run paths that inject kwargs via middleware are unaffected; the failure is specific to declarative reading WORKFLOW_RUN_KWARGS and splatting internal _raw_* keys.
• Confirmed packages are already at PyPI latest; this is a cross-package contract bug, not an outdated dependency.

[github-actions]

👋 Hi likebean — thanks for the report!

Your reported _raw_function_invocation_kwargs error matches the declarative behavior before commit 81ee134c6. Current source sanitizes that key, and the exact forwarded_props payload now succeeds with a strict Agent.run() signature. Since your released 1.0.4 package predates this source change despite the unchanged version metadata, use a release containing that commit when available.

• You reported using: 1.0.4
• Latest version: 1.0.4
• Likely fix: 81ee134c607c

If upgrading to the latest release doesn't fix it, please reopen and we'll take another look. 🙏

[likebean]

not fix

[he-yufeng]

Confirmed on current main (c97528b): the "not fix" is right, and the triage pointer to 81ee134 was off. That commit scoped the __global__ executor-ID kwargs collision; it never touched the declarative invocation path.

The live chain today:

1. _workflow.py stores the resolved kwargs plus the internal _raw_function_invocation_kwargs / _raw_client_kwargs copies into the WORKFLOW_RUN_KWARGS_KEY state bag (they exist for nested workflow remapping).
2. agent-framework-declarative's agent action (_executors_agents.py:793-805) reads the whole bag, excludes only options, and splats the rest into agent.run(messages, options=options, **run_kwargs). The underscore keys land as real keyword arguments.
3. Agent.run() has no **kwargs, so _raw_function_invocation_kwargs raises TypeError on the first declarative agent step under AG-UI, exactly as reported.

The core AgentExecutor already avoids this by extracting only the public names via _prepare_agent_run_args; the declarative path never got the same treatment.

I'll pick this up. Fix shape: filter internal (underscore-prefixed) keys out of the splat while keeping the full bag on options["additional_function_arguments"], so nested-workflow remapping keeps working and Agent.run only sees public parameters. Regression test drives the declarative agent action with a state bag that includes _raw_function_invocation_kwargs and asserts the run goes through, plus a check that the raw key still reaches additional_function_arguments. PR will link here.

[he-yufeng]

Small correction to my line citations above (I was reading a stale local checkout): on current main the bag write is _workflow.py:605 and :613, and the declarative splat is _executors_agents.py:794-815 (agent.run(messages_for_agent, options=options, **run_kwargs) at :815). The mechanism is unchanged and verified against c97528b directly this time.