feat(multiagent): Add stream_async #961

mkmeral · 2025-10-02T11:13:12Z

Description

This PR adds streaming support to the Swarm and Graph multi-agent systems, enabling real-time event emission during multi-agent execution. This brings multi-agent systems to feature parity with the single Agent class streaming capabilities.

Key Changes

New Event Types (src/strands/types/_events.py):

MultiAgentNodeStartEvent: Emitted when a node begins execution
MultiAgentNodeCompleteEvent: Emitted when a node completes execution
MultiAgentNodeStreamEvent: Forwards agent events with node context
MultiAgentHandoffEvent: Emitted during agent handoffs in Swarm (includes from_node, to_node, and message)

Swarm Streaming (src/strands/multiagent/swarm.py):

Added stream_async() method that yields events during execution
Refactored invoke_async() to use stream_async() internally (maintains backward compatibility)
Events include node start/complete, forwarded agent events, handoff notifications, and final result
Proper event emission even during failures

Graph Streaming (src/strands/multiagent/graph.py):

Added stream_async() method for real-time event streaming
Refactored invoke_async() to consume stream_async() events
Supports streaming from parallel node execution
Events maintain node context throughout execution

Testing:

Comprehensive test coverage for streaming functionality in both Swarm and Graph
Tests for parallel execution, handoffs, failures, and timeouts
Backward compatibility tests to ensure existing code continues to work

Benefits

Real-time visibility into multi-agent execution progress
Consistent streaming API across single and multi-agent systems
Better debugging and monitoring capabilities
Foundation for UI progress indicators and live updates

Related Issues

Documentation PR

Type of Change

New feature

Testing

How have you tested the change?

Added comprehensive unit tests for streaming in both Swarm and Graph (tests/strands/multiagent/test_swarm.py, tests/strands/multiagent/test_graph.py)
Tests cover: basic streaming, parallel execution, handoffs, failures, timeouts, and backward compatibility
All existing tests pass, confirming backward compatibility

Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

I ran hatch run prepare

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

zastrowm · 2025-10-06T17:39:25Z

src/strands/multiagent/swarm.py

+
+                # Yield final result (consistent with Agent's AgentResultEvent format)
+                result = self._build_result()
+                yield {"result": result}


Yield final result (consistent with Agent's AgentResultEvent format)

Is this an AgentResult as it is for single-agent streaming? If not, can we rename so that it doesn't conflict with different types

zastrowm · 2025-10-06T17:40:41Z

src/strands/multiagent/graph.py

+
+        Yields:
+            Dictionary events containing graph execution information including:
+            - MultiAgentNodeStartEvent: When a node begins execution


These types aren't exposed to customers, so we should either remove these docs or document the shape of the dictionaries being emited

Can you also list out the the new events to the PR description (similar to #788) along with the signatures of the new apis being added. This well help the PR be more akin to the spec of what's being proposed

so we should either remove these docs AND document the shape of the dictionaries being emitted*

zastrowm · 2025-10-06T17:43:40Z

src/strands/multiagent/graph.py

+            try:
+                event = await asyncio.wait_for(async_generator.__anext__(), timeout=timeout)
+                yield event
+            except StopAsyncIteration:


Is this always thrown at the end and thus part of normal execution?

nit: seems like theres might be a more pythonic way to do this without the while

async with asyncio.timeout(timeout): async for event in async_generator:

zastrowm · 2025-10-06T17:46:39Z

src/strands/multiagent/graph.py

-            # because a failure would throw exception and code would not make it here
            ready_nodes.extend(self._find_newly_ready_nodes(current_batch))

+    async def _execute_nodes_parallel(


Does this follow the pattern of how tools are executed in parallel - I know we worked out some wrinkles/bugs with that, so it'd be ideal to not have to redo those

Also, does this have to be in this PR? Can we do the streaming then add parallel execution as a different commit to simplify the review?

zastrowm · 2025-10-06T17:47:52Z

src/strands/multiagent/graph.py

+        start_event = MultiAgentNodeStartEvent(
+            node_id=node.node_id, node_type="agent" if isinstance(node.executor, Agent) else "multiagent"
+        )
+        yield start_event.as_dict()


Could we do this at a higher level instead of in here? That way we can ensure this method is always returning TypedEvents

Same for below

zastrowm · 2025-10-06T17:48:43Z

src/strands/multiagent/graph.py

+                            wrapped_event = MultiAgentNodeStreamEvent(node.node_id, event)
+                            yield wrapped_event.as_dict()
+                            # Capture the final result event
+                            if "result" in event:


Can we just do an isinstance check here?

zastrowm · 2025-10-06T17:50:53Z

src/strands/multiagent/graph.py

                if isinstance(node.executor, MultiAgentBase):
+                    # For nested multi-agent systems, stream their events and collect result
+                    multi_agent_result = None
                    if self.node_timeout is not None:


Rather than having two code paths, can _stream_with_timeout special_case no timeout to infinite?

If not, perhaps a conditional like so:

events = self._stream_with_timeout(...) if timeout else self.stream_async()

So that the if blocks are unified

zastrowm · 2025-10-06T17:51:50Z

src/strands/multiagent/graph.py

                elif isinstance(node.executor, Agent):
+                    # For agents, stream their events and collect result
+                    agent_response = None
                    if self.node_timeout is not None:


Same comments as above - these if blocks have the same content, so let's find a way to unify them

zastrowm · 2025-10-06T17:54:00Z

src/strands/multiagent/swarm.py

+                            to_node=self.state.current_node.node_id,
+                            message=self.state.handoff_message or "Agent handoff occurred",
+                        )
+                        yield handoff_event.as_dict()


As noded for graphs, can we do the as_dict() stuff higher up? I'd like to be strongly typed at the lower-levels and only do dict conversion at the api layer

zastrowm · 2025-10-06T17:54:30Z

src/strands/multiagent/swarm.py

-
-                except Exception:
-                    logger.exception("node=<%s> | node execution failed", current_node.node_id)
+                except Exception as e:


Why can't we use an exception type for this? This seems hacky

dbschmigelski · 2025-10-06T18:17:00Z

src/strands/multiagent/graph.py

            status=Status.EXECUTING,
            task=task,
            total_nodes=len(self.nodes),
            edges=[(edge.from_node, edge.to_node) for edge in self.edges],


note related to this PR, but why doesn't GraphState take Iterable[GraphEdge] instead of edges: list[Tuple["GraphNode", "GraphNode"]] = field(default_factory=list)

Did GraphEdge come later?

dbschmigelski · 2025-10-06T18:28:40Z

src/strands/multiagent/graph.py

+            try:
+                event = await asyncio.wait_for(async_generator.__anext__(), timeout=timeout)
+                yield event
+            except StopAsyncIteration:


nit: seems like theres might be a more pythonic way to do this without the while

async with asyncio.timeout(timeout): async for event in async_generator:

dbschmigelski · 2025-10-06T18:29:51Z

src/strands/multiagent/graph.py

-            # because a failure would throw exception and code would not make it here
            ready_nodes.extend(self._find_newly_ready_nodes(current_batch))

+    async def _execute_nodes_parallel(


Also, does this have to be in this PR? Can we do the streaming then add parallel execution as a different commit to simplify the review?

dbschmigelski · 2025-10-06T18:30:40Z

src/strands/multiagent/swarm.py

+        self, async_generator: AsyncIterator[dict[str, Any]], timeout: float, timeout_message: str
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Wrap an async generator with timeout functionality."""
+        while True:


same nit as in graph

dbschmigelski · 2025-10-06T18:35:51Z

src/strands/multiagent/swarm.py

-                    logger.exception("node=<%s> | node execution failed", current_node.node_id)
+                except Exception as e:
+                    # Check if this is a timeout exception
+                    if "timed out after" in str(e):


nit: can we create a variable for this so we don't accidentally change the message in exception

Murat Kaan Meral added 3 commits October 2, 2025 12:45

feat(multiagent): Add stream async

6c00bbe

Merge branch 'main' into multiagent-streaming

b09b539

fix(graph): improve parallel node calling

08141a0

mkmeral had a problem deploying to auto-approve October 2, 2025 11:13 — with GitHub Actions Failure

fix: Fix double execution

d4f5571

mkmeral had a problem deploying to auto-approve October 2, 2025 13:00 — with GitHub Actions Failure

mkmeral marked this pull request as draft October 2, 2025 13:07

fix: improve graph timeout

fc0a272

mkmeral had a problem deploying to auto-approve October 3, 2025 09:59 — with GitHub Actions Failure

Murat Kaan Meral added 2 commits October 3, 2025 12:20

Merge branch 'main' into multiagent-streaming

ca59221

fix: Add integ tests

60f16b9

mkmeral had a problem deploying to auto-approve October 3, 2025 10:28 — with GitHub Actions Failure

mkmeral marked this pull request as ready for review October 3, 2025 10:32

zastrowm requested changes Oct 6, 2025

View reviewed changes

dbschmigelski reviewed Oct 6, 2025

View reviewed changes

feat(multiagent): Add stream_async #961

Are you sure you want to change the base?

feat(multiagent): Add stream_async #961

Uh oh!

Conversation

mkmeral commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key Changes

Benefits

Related Issues

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mkmeral commented Oct 2, 2025 •

edited

Loading