Python: Adds support for flowing kwargs to context and tool calls when using …

[nmccann]

…workflow as agent.

Motivation and Context

#2894 introduced support for flowing kwargs through the Workflow context so that they can be used by tool calls, however WorkflowAgent wasn't updated to provide similar functionality, this change allows WorkflowAgent to behave in a similar manner.

Description

Applied similar solution found in #2894 to WorkflowAgent.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[nmccann]

I'd like to add some unit tests to cover this scenario, but unsure if they should go in test_workflow_kwargs or test_workflow_agent or a new file.

Also, in the course of manually testing this, I noticed that if we have an executor that calls an agent by itself (as seen in some of the "Getting Started" samples), it's not straightforward to get the kwargs from the workflow's context and forward those to the agent so that it has access to the same kwargs. My current thought of how to do that would be to import the WORKFLOW_RUN_KWARGS_KEY to use to extract it from the context. But that doesn't seem like the intended approach.

Maybe we shouldn't be calling agents within an executor, or if we do we should consider it to be "isolated" from the broader state of the workflow.

[moonbox3]

Didn't know you were also working on this. As I was plumbing the kwargs through, I spotted another bug about not properly handling a list[ChatMessage] with a WorkflowAgent in #2946, as well as adding tests and a new sample.

[moonbox3]

any reason we couldn't use idiomatic Python **kwargs forwarding?

[moonbox3]

Feels like this adds some unnecessary complexity - could we simply propagate **kwargs as-is?

[Copilot]

Pull request overview

This PR adds support for flowing kwargs through WorkflowAgent to context and tool calls, extending the functionality introduced in PR #2894 for the Workflow class. This allows callers to pass custom context data (like API endpoints, user tokens, etc.) through WorkflowAgent.run() and WorkflowAgent.run_stream() which then becomes accessible to @ai_function tools via the **kwargs parameter.

Key Changes:

• Added run_kwargs parameter to _run_stream_impl() method to accept and forward kwargs
• Updated docstrings for run() and run_stream() methods to document the kwargs functionality
• Modified both run() and run_stream() to pass kwargs through to the internal implementation

[Copilot]

The code example is incorrectly placed within the "Keyword Args:" section. Following the pattern established in Workflow.run_stream() (lines 480-520 in _workflow.py), examples should be in a separate "Examples:" section after the "Returns:" section. The example text "With custom context for ai_functions:" should be a subsection heading within an "Examples:" section, not nested under "Keyword Args:". Please restructure the docstring to match the Workflow.run_stream() documentation style.

[Copilot]

The code example is incorrectly placed within the "Keyword Args:" section. Following the pattern established in Workflow.run_stream() (lines 480-520 in _workflow.py), examples should be in a separate "Examples:" section after the "Yields:" section. The example text "With custom context for ai_functions:" should be a subsection heading within an "Examples:" section, not nested under "Keyword Args:". Please restructure the docstring to match the Workflow.run_stream() documentation style.

Suggested change

	With custom context for ai_functions:
	.. code-block:: python
	async for event in workflow_agent.run_stream(
	"analyze data",
	custom_data={"endpoint": "https://api.example.com"},
	user_token={"user": "alice"},
	):
	process(event)
	Yields:
	AgentRunResponseUpdate objects representing the workflow execution progress.
	Yields:
	AgentRunResponseUpdate objects representing the workflow execution progress.
	Examples:
	With custom context for ai_functions:
	.. code-block:: python
	async for event in workflow_agent.run_stream(
	"analyze data",
	custom_data={"endpoint": "https://api.example.com"},
	user_token={"user": "alice"},
	):
	process(event)

[Copilot]

The new functionality of passing kwargs through WorkflowAgent lacks test coverage. While the test file test_workflow_kwargs.py has comprehensive tests for kwargs flowing through Workflow and SequentialBuilder to agents, there are no tests verifying that kwargs passed to WorkflowAgent.run() and WorkflowAgent.run_stream() properly flow through to the underlying workflow and become accessible to @ai_function tools. Consider adding tests similar to test_sequential_kwargs_flow_to_agent but for WorkflowAgent specifically.

[nmccann]

Didn't know you were also working on this. As I was plumbing the kwargs through, I spotted another bug about not properly handling a list[ChatMessage] with a WorkflowAgent in #2946, as well as adding tests and a new sample.

No worries, I'm good with closing this one in favour of #2946. Was mostly looking to get familiarity with the process of running it locally and creating a PR, which I now have. Will look through your PR to see how you did the tests etc.

I would also need to wait to get approval for the CLA, and that turns out to be difficult to do this time of year :)