hooks - before node call - cancel node

[pgrayy]

Description

Allow users to cancel multiagent node execution from their BeforeNodeCallEvent hooks. This change mirrors tool cancellation introduced in #964. Cancellation is particularly useful for HIL approval/rejection workflows operated through interrupts.

Usage

class CancelHook(HookProvider):
    def register_hooks(self, registry) -> None:
        registry.add_callback(BeforeNodeCallEvent, self.cancel)

    def cancel(self, event: BeforeToolCallEvent) -> None:
        if event.node_id == "delete":
            response = event.interrupt("my_interrupt", reason="need approval")
            if response != "APPROVE":
                event.cancel_node = "node rejected"

system_agent = Agent(name="system")
delete_agent = Agent(name="delete")
swarm = Swarm([system_agent, delete_agent], hooks=[CancelHook()])

result = swarm("Delete my file")
...

If rejected, the delete node will not be executed and the swarm will end with a FAILED status. Similar behavior occurs with node cancellation in Graph.

Related Issues

#204

Documentation PR

Will add documentation to https://strandsagents.com/latest/documentation/docs/user-guide/concepts/interrupts/ once multi-agent interrupt work is complete. In the meanwhile, customers will have the API reference docs, which will automatically update on next release.

Type of Change

New feature

Testing

How have you tested the change? 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: Wrote new unit tests.
• I ran hatch test tests_integ/hooks/multiagent/test_cancel.py: Wrote new integ tests.

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.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!