Interruption Handling
Interruption handling allows agents to gracefully stop generating responses when the user starts speaking, creating natural conversational flow.
Pattern Overview
This pattern enables:
- Natural Conversation: User can interrupt agent at any time
- Graceful Cancellation: Agent stops generating without errors
- Resource Cleanup: Proper cleanup of ongoing operations
- Seamless Recovery: Agent can resume processing new user input
Key Components
Events
UserStartedSpeaking
: Triggers interruption of ongoing generationUserStoppedSpeaking
: Resumes normal processing flowAgentGenerationComplete
: Signals when generation finishes
Routes
interrupt_on()
: Defines which events should cancel the current operation- Interrupt Handlers: Custom functions to handle cancellation cleanup
- Task Cancellation: Automatic cancellation of async tasks
Nodes
- Interrupt Awareness: Nodes handle
asyncio.CancelledError
gracefully - Cleanup Logic: Implement interrupt handlers for resource cleanup
- State Recovery: Maintain consistent state after interruptions
Basic Example
Node-Level Interruption Handling
Advanced Patterns
Conditional Interruption
Multiple Interrupt Events
State Management During Interruptions
Best Practices
- Always Handle CancelledError: Nodes should gracefully handle task cancellation
- Cleanup Resources: Use interrupt handlers to cleanup API calls, files, connections
- Maintain State Consistency: Ensure node state remains valid after interruptions
- Log Interruptions: Track interruption patterns for debugging and optimization
- Fast Interruption Response: Keep interrupt handlers lightweight and fast
- Recovery Planning: Consider how to handle partial responses and state recovery
Common Use Cases
- Voice Conversations: Natural turn-taking in voice interactions
- Long Responses: Allow interruption of lengthy agent responses
- Emergency Stops: Immediate cancellation for safety or escalation
- Context Switches: Interrupt current task when user changes topic
- Multi-Agent Handoffs: Cancel current agent when transferring to another
Troubleshooting
Generation Doesn’t Stop
- Ensure
interrupt_on()
is properly configured on the route - Check that the node properly handles
asyncio.CancelledError
- Verify interrupt events are being properly emitted
Resource Leaks
- Implement interrupt handlers to cleanup streaming connections
- Use
async with
contexts for resource management - Cancel pending API calls in interrupt handlers
State Corruption
- Save critical state before generation starts
- Validate state consistency after interruptions
- Consider using database transactions for critical state changes
This pattern is essential for creating natural, responsive voice agents that feel conversational rather than robotic.