[FEATURE] Expose user defined state in MultiAgent Graph and Swarm

[dbschmigelski]

Problem Statement

In Agent, the user has access to AgentState where they can store and access information in tools. This is useful where we may want to store a reference to a large file, but not actually provide the content to the the LLM in the AgentResult ContentBlock(s).

In Graph, there exists GraphState, but it does not expose a similar "user defined state" property.

Proposed Solution

Swarm, another MultiAgent platform, has SharedContext. HOWEVER, SharedContext is used by the LLM and is NOT the same conceptually AgentState. Its should not be used to accomplish the stated goal.

Proposed solutions are explored in depth below #665 (comment)

Use Case

This would be useful if I want to store information across nodes.

Alternatives Solutions

No response

Additional Context

No response

[dbschmigelski]

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

[dbschmigelski]

Hey, reopening this ticket. The PR #816, is more of a half solution to unblock customers.

But the "correct" solution I believe would still be to expose this on the primitives themselves, so Option 3 - MultiAgentState through subclass