feat(multiagent): allow callers of swarm and graph to pass kwargs to executors

[dbschmigelski]

This is the same PR as #703. The reason it is being reraised is that the initial author made additional commits on the branch.

This PR adds kwargs support to the multiagent primitives in the same manner as the Agent class. It does not necessarily solve general case as called out in #665 (comment), this unblocks customers.

Discussion Notes

(I am using emojis but I promise this is not AI generated)

❌ Option 2, MultiAgentState piped by Strands through kwargs, is a non-starter as it extends usage of invocation_state/kwargs by Strands. The team takes the position that these arguments are intended only to be used by the application developer, NOT the the SDK itself. There are a few instances where invocation_state/kwargs are leveraged internally, but we do not want make what is bad worse.

❌ Option 4, MultiAgentState through new field in Agent class, is interesting but is a poor option because it leaks Multi-Agent into the the base Agent class. What happens if there is another pattern? Do we simply throw everything into the Agent class? The Agent class SHOULD NOT be ware that it is participating in a multi agent pattern, if it did it would be a leaky abstraction.

🔜 This brings us to Option 3 MultiAgentState through sub class, this is the preferred option and will be explored in #573. Introducing a specialized MutliAgent Agent class would allow us to add multi agent specific logic and properties without leaking that information into the base Agent.

✅ However, Option 1, MultiAgentState allowed through kwargs, will unblock customers in the short term. Similar to how in the Agent we allow the user to pass arbitrary information via invocation_state/kwargs, we should allow callers of Graph and Swarm to do the same thing; then we pass that to the base Agent class through the existing mechanism of kwargs. This is an appropriate usage of in place mechanism of Agent. What would NOT be appropriate, would be if we were to place this MultiAgentState somehow inside of AgentState. Although the names are similar this again is a leaky.

To summarize, passing kwargs will unblock customers and be generally useful. However, we still intend to support this MultiAgentState in a first class way it will just not be in the immediate term. We will leave this issue open to track interest, but this will now depend on

Multi-Agent State (doc summary)

Goal: Share information across Agents collaborating in a MultiAgent pattern, without having that information exposed to the LLM. This is similar to the AgentState class’ relationship to the Agent.

Currently Agent has an AgentState object for single agent state. Need to expose multi-agent state while preserving isolation. There are a few options to achieve this.

Option 1 - MultiAgentState via kwargs

Least opinionated approach - pass multi-agent state through kwargs to Graph and Swarm. These kwargs propagate to all Agent and MultiAgentBase invocations.

result = await node.executor.invoke_async(
node_input,
**kwargs,
)

Option 2 - MultiAgentState piped through kwargs

Pass multi-agent state explicitly in kwargs on each agent invocation:

result = await node.executor.invoke_async(
node_input,
multi_agent_state=multi_agent_state
)
Note: While this maintains backwards compatibility since Graph/Swarm don't allow kwargs, it breaks internal principle of not adding content kwargs.

Option 3 - MultiAgentState through subclass

Create MultiAgentAgent subclass for multi-agent patterns, similar to MultiAgentBase. This would expose multi_agent_state. More complex and introduces a hierarchy.

Option 4 - MultiAgentState as Agent field

Add multi_agent_state directly to Agent constructor. Simplifies hierarchy vs Option 3 but pollutes Agent constructor.

Recommendation: Option 1 provides most flexibility is a useful feature even outside of the state conversation