[FEATURE] Graph - Cancel Node - Do Not Raise Exception

[pgrayy]

Problem Statement

Currently, users can cancel a node execution by setting event.cancel_node = <STR_MSG|True> within a BeforeNodeCallEvent hook. Unlike for swarm (docs, test), this leads to an exception that stops the entire graph execution. I would like to explore if this is necessary. To help figure this out, we should look at the resulting behavior of returning False from the should_continue call.

If it is appropriate to raise an exception, we should raise an explicit node cancel exception instead of a RuntimeError.

Proposed Solution

No response

Use Case

Cleaning exit from graph without having to worry about catching a RuntimeError when I intentionally cancel a node execution.

Alternatives Solutions

No response

Additional Context

No response

---

Implementation Requirements

Based on clarification discussion and repository analysis:

Summary

Align Graph cancel_node behavior with Swarm - don't raise an exception, set status to FAILED and return gracefully. This follows the same pattern as should_continue returning False.

Technical Approach

Current Behavior Comparison

Swarm (swarm.py lines 750-759) - Graceful exit:

if before_event.cancel_node:
    yield MultiAgentNodeCancelEvent(current_node.node_id, cancel_message)
    self.state.completion_status = Status.FAILED
    break  # No exception

Graph (graph.py lines 864-871) - Raises exception:

if before_event.cancel_node:
    yield MultiAgentNodeCancelEvent(node.node_id, cancel_message)
    raise RuntimeError(cancel_message)  # This needs to change

Reference: should_continue Graceful Exit Pattern (lines 648-651)

When should_continue returns False:

1. Sets self.state.status = Status.FAILED
2. Returns gracefully (no exception)
3. Downstream nodes don't execute
4. GraphResult is still built and yielded normally via MultiAgentResultEvent

Implementation Details

1. Modify _execute_node in graph.py (lines 864-871)

Replace the raise RuntimeError with graceful handling:

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(node.node_id, cancel_message)
    
    # Create NodeResult for cancelled node (similar to failure handling)
    node_result = NodeResult(
        result=cancel_message,
        execution_time=0,
        status=Status.FAILED,
        accumulated_usage=Usage(inputTokens=0, outputTokens=0, totalTokens=0),
        accumulated_metrics=Metrics(latencyMs=0),
        execution_count=1,
    )
    
    node.execution_status = Status.FAILED
    node.result = node_result
    self.state.failed_nodes.add(node)
    self.state.results[node.node_id] = node_result
    
    yield MultiAgentNodeStopEvent(node_id=node.node_id, node_result=node_result)
    return  # Graceful exit, no exception

2. Add failed_nodes check in _execute_graph (after line 658)

The comment on line 669-670 notes: "a failure would throw exception and code would not make it here". Since we're removing the exception, add a check:

async for event in self._execute_nodes_parallel(current_batch, invocation_state):
    yield event

# Check if any nodes failed (including cancelled) - stop execution gracefully
if self.state.failed_nodes:
    self.state.status = Status.FAILED
    return

if self.state.status == Status.INTERRUPTED:
    # ... existing interrupt handling

Files to Modify

File	Changes
src/strands/multiagent/graph.py	Modify _execute_node to not raise, add failed_nodes check in _execute_graph
tests/strands/multiagent/test_graph.py	Update test_graph_cancel_node - remove pytest.raises(RuntimeError), verify result is yielded
tests_integ/hooks/multiagent/test_cancel.py	Update test_graph_cancel_node - remove pytest.raises(RuntimeError), verify result accessible

Acceptance Criteria

• Setting cancel_node in a BeforeNodeCallEvent hook does NOT raise a RuntimeError
• Graph execution stops gracefully when a node is cancelled
• GraphResult is yielded normally with status=Status.FAILED
• MultiAgentNodeCancelEvent is still emitted
• MultiAgentNodeStopEvent is emitted for the cancelled node
• Downstream nodes do not execute (same as should_continue returning False)
• Behavior is consistent with Swarm cancel_node handling
• Unit tests pass without expecting RuntimeError
• Integration tests pass without expecting RuntimeError

Breaking Change Notice

This is a breaking change for any code that catches RuntimeError during graph node cancellation. The current behavior is considered a bug since it's inconsistent with Swarm behavior and the existing should_continue graceful exit pattern.

Related Links

• Original PR introducing cancel_node: hooks - before node call - cancel node #1203
• Swarm interrupt docs: https://github.com/strands-agents/docs/blob/main/docs/user-guide/concepts/interrupts.md#swarm

[pgrayy]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Analysis

I've analyzed the repository and identified the key differences between Graph and Swarm cancel_node handling:

Current Behavior

Swarm (swarm.py lines 750-759):

if before_event.cancel_node:
    # ... cancel_message setup ...
    yield MultiAgentNodeCancelEvent(current_node.node_id, cancel_message)
    self.state.completion_status = Status.FAILED
    break  # <-- Graceful exit, no exception

Graph (graph.py lines 864-871):

if before_event.cancel_node:
    # ... cancel_message setup ...
    yield MultiAgentNodeCancelEvent(node.node_id, cancel_message)
    raise RuntimeError(cancel_message)  # <-- Raises exception

Key Observation

The Graph's should_continue method (line 644) already demonstrates a pattern for graceful failure without exceptions - when execution limits are reached, it sets status = Status.FAILED and returns, rather than raising an exception.

Files That Would Need Modification

• src/strands/multiagent/graph.py - Change cancel_node handling
• src/strands/types/exceptions.py - Add NodeCancelException (if explicit exception is desired)
• tests/strands/multiagent/test_graph.py - Update unit tests (currently expects RuntimeError)
• tests_integ/hooks/multiagent/test_cancel.py - Update integration tests (currently expects RuntimeError)

---

Clarifying Questions

1. Preferred Behavior

Which approach do you prefer?

• Option A: Align Graph with Swarm - Don't raise an exception, set status to FAILED and return a result gracefully (most consistent with Swarm behavior)
• Option B: Create explicit exception - Create a NodeCancelException (or GraphNodeCancelException) instead of RuntimeError
• Option C: Make it configurable - Add a parameter like raise_on_cancel: bool = True to allow users to choose

2. Downstream Node Handling

When a node is cancelled in a Graph, what should happen to downstream dependent nodes?

• A: They should not execute (current behavior with the exception)
• B: They should also be marked as cancelled/skipped
• C: Something else?

3. Result Availability

If we remove the exception (Option A), should the GraphResult still be available via graph.state even though the streaming was cancelled? Currently with the exception, users must access graph.state directly. With Option A, the result would be yielded normally.

4. Breaking Change Acceptance

This change may affect existing code that catches RuntimeError during graph cancellation. Is this an acceptable breaking change, or should we maintain backward compatibility somehow?

5. should_continue Return Value

You mentioned investigating should_continue returning False. Currently when should_continue returns False, the graph gracefully sets status to FAILED and returns without exception. Would you like the same behavior for cancel_node?

---

Please respond when you have a chance. Based on the analysis, this seems like a well-scoped task that can be implemented in a single PR.

[pgrayy]

/strands

1. Let's go with Option A and make it consistent with Swarm if possible. For additional context on the existing behavior, you can view the PR here.
2. What happens if should_continue returns False? What does it do with the downstream nodes?
3. What happens if should_continue returns False? Do we still add GraphResult to graph.state? If so, I think we should follow that behavior.
4. If we can return gracefully then I would call the current behavior a bug and so the breaking change is acceptable.
5. If should_continue can lead to a graceful exit then yes I think cancel_node should to.

[pgrayy]

/strands

1. Let's go with Option A and make it consistent with Swarm if possible. For additional context on the existing behavior, you can view the PR here.
2. What happens if should_continue returns False? What does it do with the downstream nodes?
3. What happens if should_continue returns False? Do we still add GraphResult to graph.state? If so, I think we should follow that behavior.
4. If we can return gracefully then I would call the current behavior a bug and so the breaking change is acceptable.
5. If should_continue can lead to a graceful exit then yes I think cancel_node should to.

[github-actions]

Task Refinement Complete

Summary

Based on the clarification discussion, I've updated the issue description with comprehensive implementation requirements.

Key Decisions Made

1. Approach: Option A - Align Graph with Swarm behavior (no exception on cancel)
2. Downstream nodes: Follow should_continue pattern - they don't execute but aren't explicitly marked as skipped
3. Result availability: GraphResult will be yielded normally via MultiAgentResultEvent
4. Breaking change: Accepted - current behavior is considered a bug

Implementation Strategy

The fix involves two main changes:

1. In _execute_node: Replace raise RuntimeError(cancel_message) with graceful handling that:

   • Creates a NodeResult for the cancelled node
   • Sets node.execution_status = Status.FAILED
   • Adds node to self.state.failed_nodes
   • Yields MultiAgentNodeStopEvent
   • Returns (no exception)

2. In _execute_graph: Add a check after _execute_nodes_parallel to detect failed nodes and exit gracefully (similar to should_continue pattern)

Files to Modify

• src/strands/multiagent/graph.py
• tests/strands/multiagent/test_graph.py
• tests_integ/hooks/multiagent/test_cancel.py

Status

✅ Ready for implementation - This is a well-scoped task that can be completed in a single PR.

[pgrayy]

/strands to clarify, when should_continue returns false, does this result in a NodeResult being generated still with a failed status?