diff --git a/docs/user-guide/concepts/multi-agent/graph.md b/docs/user-guide/concepts/multi-agent/graph.md index e6dfde1e..ca204e12 100644 --- a/docs/user-guide/concepts/multi-agent/graph.md +++ b/docs/user-guide/concepts/multi-agent/graph.md @@ -291,6 +291,51 @@ async def run_graph(): result = asyncio.run(run_graph()) ``` +## Streaming Events + +Graphs support real-time streaming of events during execution using [`stream_async`](../../../api-reference/multiagent.md#strands.multiagent.graph.Graph.stream_async). This provides visibility into node execution, parallel processing, and nested multi-agent systems. + +```python +from strands import Agent +from strands.multiagent import GraphBuilder + +# Create specialized agents +researcher = Agent(name="researcher", system_prompt="You are a research specialist...") +analyst = Agent(name="analyst", system_prompt="You are an analysis specialist...") + +# Build the graph +builder = GraphBuilder() +builder.add_node(researcher, "research") +builder.add_node(analyst, "analysis") +builder.add_edge("research", "analysis") +builder.set_entry_point("research") +graph = builder.build() + +# Stream events during execution +async for event in graph.stream_async("Research and analyze market trends"): + # Track node execution + if event.get("type") == "multiagent_node_start": + print(f"šŸ”„ Node {event['node_id']} starting") + + # Monitor agent events within nodes + elif event.get("type") == "multiagent_node_stream": + inner_event = event["event"] + if "data" in inner_event: + print(inner_event["data"], end="") + + # Track node completion + elif event.get("type") == "multiagent_node_stop": + node_result = event["node_result"] + print(f"\nāœ… Node {event['node_id']} completed in {node_result.execution_time}ms") + + # Get final result + elif event.get("type") == "multiagent_result": + result = event["result"] + print(f"Graph completed: {result.status}") +``` + +See the [streaming overview](../streaming/overview.md#multi-agent-events) for details on all multi-agent event types. + ## Graph Results When a Graph completes execution, it returns a [`GraphResult`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphResult) object with detailed information: diff --git a/docs/user-guide/concepts/multi-agent/swarm.md b/docs/user-guide/concepts/multi-agent/swarm.md index b62c261b..3f333d59 100644 --- a/docs/user-guide/concepts/multi-agent/swarm.md +++ b/docs/user-guide/concepts/multi-agent/swarm.md @@ -186,6 +186,47 @@ async def run_swarm(): result = asyncio.run(run_swarm()) ``` +## Streaming Events + +Swarms support real-time streaming of events during execution using [`stream_async`](../../../api-reference/multiagent.md#strands.multiagent.swarm.Swarm.stream_async). This provides visibility into agent collaboration, handoffs, and autonomous coordination. + +```python +from strands import Agent +from strands.multiagent import Swarm + +# Create specialized agents +coordinator = Agent(name="coordinator", system_prompt="You coordinate tasks...") +specialist = Agent(name="specialist", system_prompt="You handle specialized work...") + +# Create swarm +swarm = Swarm([coordinator, specialist]) + +# Stream events during execution +async for event in swarm.stream_async("Design and implement a REST API"): + # Track node execution + if event.get("type") == "multiagent_node_start": + print(f"šŸ”„ Agent {event['node_id']} taking control") + + # Monitor agent events + elif event.get("type") == "multiagent_node_stream": + inner_event = event["event"] + if "data" in inner_event: + print(inner_event["data"], end="") + + # Track handoffs + elif event.get("type") == "multiagent_handoff": + from_nodes = ", ".join(event['from_node_ids']) + to_nodes = ", ".join(event['to_node_ids']) + print(f"\nšŸ”€ Handoff: {from_nodes} → {to_nodes}") + + # Get final result + elif event.get("type") == "multiagent_result": + result = event["result"] + print(f"\nSwarm completed: {result.status}") +``` + +See the [streaming overview](../streaming/overview.md#multi-agent-events) for details on all multi-agent event types. + ## Swarm Results When a Swarm completes execution, it returns a [`SwarmResult`](../../../api-reference/multiagent.md#strands.multiagent.swarm.SwarmResult) object with detailed information: diff --git a/docs/user-guide/concepts/streaming/overview.md b/docs/user-guide/concepts/streaming/overview.md index f0093b8f..24539bf3 100644 --- a/docs/user-guide/concepts/streaming/overview.md +++ b/docs/user-guide/concepts/streaming/overview.md @@ -41,6 +41,33 @@ All streaming methods yield the same set of events: - `reasoning_signature`: Signature from reasoning process - `redactedContent`: Reasoning content redacted by the model +### Multi-Agent Events + +Multi-agent systems ([Graph](../multi-agent/graph.md) and [Swarm](../multi-agent/swarm.md)) emit additional coordination events: + +- `multiagent_node_start`: When a node begins execution + - `type`: `"multiagent_node_start"` + - `node_id`: Unique identifier for the node + - `node_type`: Type of node (`"agent"`, `"swarm"`, `"graph"`) +- `multiagent_node_stream`: Forwarded events from agents/multi-agents with node context + - `type`: `"multiagent_node_stream"` + - `node_id`: Identifier of the node generating the event + - `event`: The original agent event (nested) +- `multiagent_node_stop`: When a node completes execution + - `type`: `"multiagent_node_stop"` + - `node_id`: Unique identifier for the node + - `node_result`: Complete NodeResult with execution details, metrics, and status +- `multiagent_handoff`: When control is handed off between agents (Swarm) or batch transitions (Graph) + - `type`: `"multiagent_handoff"` + - `from_node_ids`: List of node IDs completing execution + - `to_node_ids`: List of node IDs beginning execution + - `message`: Optional handoff message (typically used in Swarm) +- `multiagent_result`: Final multi-agent result + - `type`: `"multiagent_result"` + - `result`: The final GraphResult or SwarmResult + +See [Graph streaming](../multi-agent/graph.md#streaming-events) and [Swarm streaming](../multi-agent/swarm.md#streaming-events) for usage examples. + ## Quick Examples ### Async Iterator Pattern