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.