feat: add CancellationToken for graceful agent execution cancellation

[jgoyani1]

Description

Implement CancellationToken to enable graceful cancellation of agent execution from external contexts (e.g., web requests, background threads).

Key features:

• Thread-safe CancellationToken class with cancel() and is_cancelled() methods
• Agent accepts optional cancellation_token parameter at creation time
• Four cancellation checkpoints in event loop:
  1. Start of event loop cycle
  2. Before model execution
  3. During model response streaming
  4. Before tool execution
• New 'cancelled' stop reason in StopReason type
• Token automatically added to invocation_state for event loop access

Implementation details:

• CancellationToken uses threading.Lock for thread safety
• Zero usage/metrics returned when cancelled (no model execution occurred)
• Cancellation detected at checkpoints returns proper empty message structure

Tests included:

• Unit tests for CancellationToken thread safety and behavior
• Unit tests for agent cancellation at different checkpoints
• Integration tests with real model providers (require credentials)

Related Issues

#81

Documentation PR

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

Tests included:

• Unit tests for CancellationToken thread safety and behavior

• Unit tests for agent cancellation at different checkpoints

• Integration tests with real model providers (require credentials)

• 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.

[pgrayy]

During design review, I would recommend bringing up the naming of this. Throughout the SDK we now use stop, interrupt, and cancel. In my mind, they have the following meanings:

• stop: Stop the agent loop and exit out.
• interrupt: Interrupt the agent loop to get a user response. Once received, resume from where agent loop was interrupted.
• cancel: We use this specifically on components. For example, we can cancel a tool call that is about to happen. So it isn't so much stopping as it is about preventing something from getting started.

I am thinking cancel is the right word here because we are checking it at certain points in the loop to essentially say, don't go forward with this action. stop as a verb is probably something we should avoid using going forward. So we could still have a "stop event" or "stop reason", but the underlying reason is because of things like "interrupted", "cancelled", etc.

So with all that said, I would probably recommend calling this CancelSignal. It also fits in line with python's asyncio task.cancel() terminology.