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*

I have matched the implementation/documentation to agent. I will add additional docs as a followup CR on docs repo. I will also update the RP description to explain the events 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:

src/strands/multiagent/graph.py

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?

Not easily, because agent also translates it to a dict before returning the responses. https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/agent.py#L591

Is there a reason we decided to go this way instead of returning typed events?

Two reasons why whe didn't ship typed events publically:

We didn't want to split the world between the old way (dict checking) and new way (classes)

We weren't sure that classes was the right path forward

(1) is not a good enough reason IMHO and so (2) was stronger. For TypeScript we're thinking it's going to be type: "SomeName" and I think we'd do the same in python.

I think it's worth revisiting now, however

src/strands/multiagent/graph.py

src/strands/multiagent/swarm.py

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:

src/strands/multiagent/graph.py

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

- Update docstrings to match Agent's minimal style (use dict keys instead of class names) - Add isinstance checks for result event detection for type safety - Improve _stream_with_timeout to handle None timeout case - Add MultiAgentResultEvent for consistency with Agent pattern - Yield TypedEvent objects internally, convert to dict at API boundary - All 154 tests passing

- Remove unnecessary asyncio.gather() after event loop completion - Same issue as tool executor PR strands-agents#954 - By the time loop exits, all tasks have already completed - Gather was waiting for already-finished tasks (no-op) - All 154 tests passing

codecov · 2025-10-10T11:29:12Z

Codecov Report

❌ Patch coverage is 90.32258% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/multiagent/graph.py	91.95%	2 Missing and 5 partials ⚠️
src/strands/multiagent/swarm.py	87.75%	4 Missing and 2 partials ⚠️
src/strands/multiagent/base.py	50.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

zastrowm · 2025-10-10T20:52:12Z

src/strands/multiagent/swarm.py

+                wrapped_event = MultiAgentNodeStreamEvent(node_name, event)
+                yield wrapped_event
+                # Capture the final result event
+                if isinstance(event, dict) and "result" in event:


Is there ever a case where this is not an dict?

zastrowm · 2025-10-10T20:54:17Z

src/strands/types/_events.py

+        Args:
+            result: The final result from multi-agent execution (SwarmResult, GraphResult, etc.)
+        """
+        super().__init__({"result": result})


How does the caller differentiate between an AgentResult (using the key result) and a MultiAgent result?

zastrowm · 2025-10-10T20:54:56Z

src/strands/types/_events.py

+class MultiAgentResultEvent(TypedEvent):
+    """Event emitted when multi-agent execution completes with final result."""
+
+    def __init__(self, result: Any) -> None:


Why is this Any? - why is this not typed as GraphResult?

zastrowm · 2025-10-10T21:09:09Z

tests/strands/multiagent/test_graph.py

+    try:
+        async for event in graph.stream_async("Test streaming with failure"):
+            events.append(event)
+        raise AssertionError("Expected an exception")


Why aren't we using pytest-raises?

https://docs.pytest.org/en/stable/reference/reference.html#pytest-raises

zastrowm · 2025-10-10T21:11:05Z

tests/strands/multiagent/test_graph.py

+    events = []
+    start_time = time.time()
+    async for event in graph.stream_async("Test parallel streaming"):
+        events.append(event)
+    total_time = time.time() - start_time


We have ahelper for event aggregations - can we use that throughout?

Suggested change

events = []

start_time = time.time()

async for event in graph.stream_async("Test parallel streaming"):

events.append(event)

total_time = time.time() - start_time

start_time = time.time()

events = await alist(graph.stream_async("Test parallel streaming"))

total_time = time.time() - start_time

zastrowm · 2025-10-10T21:12:16Z

tests/strands/multiagent/test_swarm.py

+    coordinator.tool_registry.registry = {"handoff_to_specialist": handoff_to_specialist}
+
+    # Collect all streaming events
+    events = []


Same here for using alist

zastrowm · 2025-10-10T21:14:23Z

tests_integ/test_multiagent_graph.py

+    # Count event categories
+    node_start_events = [e for e in events if e.get("multi_agent_node_start")]
+    node_stream_events = [e for e in events if e.get("multi_agent_node_stream")]
+    custom_events = [e for e in events if e.get("custom_event")]


Everywhere else where we allow custom events, we wrap them rather than allowing passthrough - specifically so that we don't conflict going forward. My gut says that we should be doing that here. Thoughts?

zastrowm · 2025-10-10T21:16:44Z

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:


Two reasons why whe didn't ship typed events publically:

We didn't want to split the world between the old way (dict checking) and new way (classes)

We weren't sure that classes was the right path forward

(1) is not a good enough reason IMHO and so (2) was stronger. For TypeScript we're thinking it's going to be type: "SomeName" and I think we'd do the same in python.

I think it's worth revisiting now, however

zastrowm

The typed events shape & fields are a blocker for me

zastrowm · 2025-10-10T21:19:39Z

src/strands/types/_events.py

+            {
+                "multi_agent_node_stream": True,
+                "node_id": node_id,
+                **agent_event,  # Forward all original agent event data


Let's nest this instead of combining. Specifically ToolStreamEvent has all data here as a sub-field and I think that's what we should do whenever we wrap things

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

Murat Kaan Meral added 2 commits October 10, 2025 13:07

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

zastrowm requested changes Oct 10, 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!

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!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Oct 10, 2025

Codecov Report

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!

zastrowm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

mkmeral commented Oct 2, 2025 •

edited

Loading