fix(graph): introduce Status.SKIPPED for cancel_node; graph continues downstream

strands-py/src/strands/hooks/events.py

@@ -4,6 +4,7 @@
 """
 
 import uuid
+import warnings
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
@@ -330,18 +331,33 @@ class BeforeNodeCallEvent(BaseHookEvent, _Interruptible):
         source: The multi-agent orchestrator instance
         node_id: ID of the node about to execute
         invocation_state: Configuration that user passes in
-        cancel_node: A user defined message that when set, will cancel the node execution with status FAILED.
-            The message will be emitted under a MultiAgentNodeCancel event. If set to `True`, Strands will cancel the
-            node using a default cancel message.
+        skip_node: A user defined message that when set, will skip the node execution and emit a
+            :class:`~strands.types._events.MultiAgentNodeSkipEvent`. If set to ``True``, a default
+            skip message is used. Any falsy value (``False``, ``""`` etc.) means "do not skip".
+            Takes precedence over ``cancel_node`` when both are truthy.
+        cancel_node: Deprecated. Use ``skip_node`` instead. When set to a truthy value, behaves
+            identically to ``skip_node`` but also emits a ``DeprecationWarning`` at the assignment
+            site.
     """
 
     source: "MultiAgentBase"
     node_id: str
     invocation_state: dict[str, Any] | None = None
+    skip_node: bool | str = False
     cancel_node: bool | str = False
 
     def _can_write(self, name: str) -> bool:
-        return name in ["cancel_node"]
+        return name in ["skip_node", "cancel_node"]
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Set attribute, emitting a DeprecationWarning when cancel_node is assigned a truthy value."""
+        if name == "cancel_node" and value:
+            warnings.warn(
+                "BeforeNodeCallEvent.cancel_node is deprecated; use skip_node instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        super().__setattr__(name, value)
 
     @override
     def _interrupt_id(self, name: str) -> str:

strands-py/src/strands/multiagent/base.py

@@ -29,13 +29,15 @@ class Status(Enum):
         PENDING: Task has not started execution yet.
         EXECUTING: Task is currently running.
         COMPLETED: Task finished successfully.
+        SKIPPED: Task was intentionally bypassed via cancel_node; downstream nodes still execute.
         FAILED: Task encountered an error and could not complete.
         INTERRUPTED: Task was interrupted by user.
     """
 
     PENDING = "pending"
     EXECUTING = "executing"
     COMPLETED = "completed"
+    SKIPPED = "skipped"
     FAILED = "failed"
     INTERRUPTED = "interrupted"
 
@@ -44,8 +46,8 @@ class Status(Enum):
 class NodeResult:
     """Unified result from node execution - handles both Agent and nested MultiAgentBase results."""
 
-    # Core result data - single AgentResult, nested MultiAgentResult, or Exception
-    result: Union[AgentResult, "MultiAgentResult", Exception]
+    # Core result data - single AgentResult, nested MultiAgentResult, Exception, or None (skipped)
+    result: Union[AgentResult, "MultiAgentResult", Exception, None]
 
     # Execution metadata
     execution_time: int = 0
@@ -59,8 +61,8 @@ class NodeResult:
 
     def get_agent_results(self) -> list[AgentResult]:
         """Get all AgentResult objects from this node, flattened if nested."""
-        if isinstance(self.result, Exception):
-            return []  # No agent results for exceptions
+        if self.result is None or isinstance(self.result, Exception):
+            return []
         elif isinstance(self.result, AgentResult):
             return [self.result]
         else:
@@ -72,8 +74,10 @@ def get_agent_results(self) -> list[AgentResult]:
 
     def to_dict(self) -> dict[str, Any]:
         """Convert NodeResult to JSON-serializable dict, ignoring state field."""
-        if isinstance(self.result, Exception):
-            result_data: dict[str, Any] = {"type": "exception", "message": str(self.result)}
+        if self.result is None:
+            result_data: dict[str, Any] = {"type": "skipped"}
+        elif isinstance(self.result, Exception):
+            result_data = {"type": "exception", "message": str(self.result)}
         elif isinstance(self.result, AgentResult):
             result_data = self.result.to_dict()
         else:
@@ -97,8 +101,10 @@ def from_dict(cls, data: dict[str, Any]) -> "NodeResult":
             raise TypeError("NodeResult.from_dict: missing 'result'")
         raw = data["result"]
 
-        result: AgentResult | MultiAgentResult | Exception
-        if isinstance(raw, dict) and raw.get("type") == "agent_result":
+        result: AgentResult | MultiAgentResult | Exception | None
+        if isinstance(raw, dict) and raw.get("type") == "skipped":
+            result = None
+        elif isinstance(raw, dict) and raw.get("type") == "agent_result":
             result = AgentResult.from_dict(raw)
         elif isinstance(raw, dict) and raw.get("type") == "exception":
             result = Exception(str(raw.get("message", "node failed")))

strands-py/src/strands/multiagent/graph.py

@@ -43,8 +43,8 @@
 from ..telemetry import get_tracer
 from ..types._events import (
     MultiAgentHandoffEvent,
-    MultiAgentNodeCancelEvent,
     MultiAgentNodeInterruptEvent,
+    MultiAgentNodeSkipEvent,
     MultiAgentNodeStartEvent,
     MultiAgentNodeStopEvent,
     MultiAgentNodeStreamEvent,
@@ -68,7 +68,8 @@ class GraphState:
 
     Attributes:
         status: Current execution status of the graph.
-        completed_nodes: Set of nodes that have completed execution.
+        completed_nodes: Set of nodes whose execution is settled — either completed normally or skipped via skip_node.
+            Both statuses satisfy downstream readiness checks; inspect node.execution_status to distinguish them.
         failed_nodes: Set of nodes that failed during execution.
         interrupted_nodes: Set of nodes that user interrupted during execution.
         execution_order: List of nodes in the order they were executed.
@@ -134,6 +135,9 @@ class GraphResult(MultiAgentResult):
 
     total_nodes: int = 0
     completed_nodes: int = 0
+    """Number of nodes that successfully ran to completion (excludes skipped nodes)."""
+    skipped_nodes: int = 0
+    """Number of nodes bypassed via skip_node or cancel_node; downstream nodes continued executing."""
     failed_nodes: int = 0
     interrupted_nodes: int = 0
     execution_order: list["GraphNode"] = field(default_factory=list)
@@ -929,13 +933,29 @@ async def _execute_node(self, node: GraphNode, invocation_state: dict[str, Any])
                 yield self._activate_interrupt(node, interrupts, from_hook=True)
                 return
 
-            if before_event.cancel_node:
-                cancel_message = (
-                    before_event.cancel_node if isinstance(before_event.cancel_node, str) else "node cancelled by user"
+            skip_value = before_event.skip_node or before_event.cancel_node
+
+            if skip_value:
+                skip_message = skip_value if isinstance(skip_value, str) else "node skipped by user"
+                logger.debug("reason=<%s> | node skipped, graph continues", skip_message)
+                yield MultiAgentNodeSkipEvent(node.node_id, skip_message)
+                node_result = NodeResult(
+                    result=None,
+                    execution_time=0,
+                    status=Status.SKIPPED,
+                    accumulated_usage=Usage(inputTokens=0, outputTokens=0, totalTokens=0),
+                    accumulated_metrics=Metrics(latencyMs=0),
+                    execution_count=0,
                 )
-                logger.debug("reason=<%s> | cancelling execution", cancel_message)
-                yield MultiAgentNodeCancelEvent(node.node_id, cancel_message)
-                raise RuntimeError(cancel_message)
+                node.result = node_result
+                node.execution_time = 0
+                node.execution_status = Status.SKIPPED
+                self.state.completed_nodes.add(node)
+                self.state.results[node.node_id] = node_result
+                self.state.execution_order.append(node)
+                self._accumulate_metrics(node_result)
+                yield MultiAgentNodeStopEvent(node_id=node.node_id, node_result=node_result)
+                return
 
             # Build node input from satisfied dependencies
             node_input = self._build_node_input(node)
@@ -1120,7 +1140,7 @@ def _build_node_input(self, node: GraphNode) -> list[ContentBlock]:
 
                     return node_responses
 
-        # Get satisfied dependencies
+        # Get satisfied dependencies, excluding skipped nodes (they produced no output)
         dependency_results = {}
         for edge in self.edges:
             if (
@@ -1129,7 +1149,9 @@ def _build_node_input(self, node: GraphNode) -> list[ContentBlock]:
                 and edge.from_node.node_id in self.state.results
             ):
                 if edge.should_traverse(self.state):
-                    dependency_results[edge.from_node.node_id] = self.state.results[edge.from_node.node_id]
+                    nr = self.state.results[edge.from_node.node_id]
+                    if nr.status != Status.SKIPPED:
+                        dependency_results[edge.from_node.node_id] = nr
 
         if not dependency_results:
             # No dependencies - return task as ContentBlocks
@@ -1180,7 +1202,8 @@ def _build_result(self, interrupts: list[Interrupt]) -> GraphResult:
             execution_count=self.state.execution_count,
             execution_time=self.state.execution_time,
             total_nodes=self.state.total_nodes,
-            completed_nodes=len(self.state.completed_nodes),
+            completed_nodes=sum(1 for n in self.state.completed_nodes if n.execution_status == Status.COMPLETED),
+            skipped_nodes=sum(1 for n in self.state.completed_nodes if n.execution_status == Status.SKIPPED),
             failed_nodes=len(self.state.failed_nodes),
             interrupted_nodes=len(self.state.interrupted_nodes),
             execution_order=self.state.execution_order,
@@ -1285,7 +1308,8 @@ def _from_dict(self, payload: dict[str, Any]) -> None:
             self.nodes[node_id] for node_id in (payload.get("completed_nodes") or []) if node_id in self.nodes
         )
         for node in self.state.completed_nodes:
-            node.execution_status = Status.COMPLETED
+            nr = results.get(node.node_id)
+            node.execution_status = Status.SKIPPED if (nr and nr.status == Status.SKIPPED) else Status.COMPLETED
 
         # Execution order (only nodes that still exist)
         order_node_ids = payload.get("execution_order") or []

strands-py/src/strands/multiagent/swarm.py

@@ -44,8 +44,8 @@
 from ..tools.decorator import tool
 from ..types._events import (
     MultiAgentHandoffEvent,
-    MultiAgentNodeCancelEvent,
     MultiAgentNodeInterruptEvent,
+    MultiAgentNodeSkipEvent,
     MultiAgentNodeStartEvent,
     MultiAgentNodeStopEvent,
     MultiAgentNodeStreamEvent,
@@ -774,14 +774,13 @@ async def _execute_swarm(self, invocation_state: dict[str, Any]) -> AsyncIterato
                         yield self._activate_interrupt(current_node, interrupts)
                         break
 
-                    if before_event.cancel_node:
-                        cancel_message = (
-                            before_event.cancel_node
-                            if isinstance(before_event.cancel_node, str)
-                            else "node cancelled by user"
-                        )
-                        logger.debug("reason=<%s> | cancelling execution", cancel_message)
-                        yield MultiAgentNodeCancelEvent(current_node.node_id, cancel_message)
+                    skip_value = before_event.skip_node or before_event.cancel_node
+
+                    if skip_value:
+                        skip_message = skip_value if isinstance(skip_value, str) else "node skipped by user"
+                        logger.debug("reason=<%s> | node skipped, stopping swarm sequence", skip_message)
+                        yield MultiAgentNodeSkipEvent(current_node.node_id, skip_message)
+                        # Linear swarm: nodes depend on prior output; skip sets FAILED (unlike graph, which continues).
                         self.state.completion_status = Status.FAILED
                         break
 

strands-py/src/strands/types/_events.py

@@ -564,7 +564,11 @@ def __init__(self, node_id: str, agent_event: dict[str, Any]) -> None:
 
 
 class MultiAgentNodeCancelEvent(TypedEvent):
-    """Event emitted when a user cancels node execution from their BeforeNodeCallEvent hook."""
+    """Planned event for when a node stops graph execution entirely (see issue #2401).
+
+    Not currently emitted by the library. To handle bypassed nodes, subscribe to
+    :class:`MultiAgentNodeSkipEvent` (type ``multiagent_node_skip``) instead.
+    """
 
     def __init__(self, node_id: str, message: str) -> None:
         """Initialize with cancel message.
@@ -582,6 +586,30 @@ def __init__(self, node_id: str, message: str) -> None:
         )
 
 
+class MultiAgentNodeSkipEvent(TypedEvent):
+    """Event emitted when a node is bypassed via :attr:`BeforeNodeCallEvent.skip_node`.
+
+    Also triggered by the deprecated :attr:`BeforeNodeCallEvent.cancel_node` alias. The
+    orchestrator's behavior after skip depends on its type: a graph continues executing
+    downstream nodes, while a swarm stops the current run.
+    """
+
+    def __init__(self, node_id: str, message: str) -> None:
+        """Initialize with skip message.
+
+        Args:
+            node_id: Unique identifier for the node.
+            message: The node skip message.
+        """
+        super().__init__(
+            {
+                "type": "multiagent_node_skip",
+                "node_id": node_id,
+                "message": message,
+            }
+        )
+
+
 class MultiAgentNodeInterruptEvent(TypedEvent):
     """Event emitted when a node is interrupted."""