feat: Intelligent Interruption Handling for Voice Agents

[anishh15]

Summary

Implements context-aware interruption handling that distinguishes between passive acknowledgements (yeah, mhmm, okay) and actual interruptions (stop, wait, no) based on agent speaking state.

Key Features

• Configurable word lists - Custom backchannel and interrupt words
• State-based filtering - Only filters when agent is speaking
• Mixed input handling - "yeah but wait" correctly triggers interruption
• No VAD modification - Implemented as logic layer above existing pipeline
• Seamless audio - Agent continues without pause or stutter

Files Added

File	Description
interruption_filter.py	Core filter logic with regex-based word matching
interrupt_demo.py	Demo agent for testing the feature
test_interruption_filter.py	Unit tests (21 passing)
proof/	Screen recording and transcript

Files Modified

File	Changes
agent_activity.py	State tracking and filter integration
audio_recognition.py	Skip EOU detection for filtered utterances
agent_session.py	Configuration options
__init__.py	Public API exports

Usage

session = AgentSession(
    interruption_filter_enabled=True,
    backchannel_words={"yeah", "ok", "mhm"},  # optional
    interrupt_words={"stop", "wait", "no"},   # optional
)

Documentation

See CHANGES.md for detailed architecture and configuration guide.

[Copilot]

Pull request overview

This PR implements intelligent interruption handling for voice agents that distinguishes between passive acknowledgements (backchanneling) and actual interruptions. The feature filters backchannel words like "yeah", "mhmm", and "okay" when the agent is speaking, allowing conversations to flow naturally without unnecessary interruptions.

Changes:

• Added InterruptionFilter class with configurable word lists and state-aware filtering logic
• Integrated filter into AgentActivity with state capture timing to handle VAD/STT race conditions
• Modified AudioRecognition to skip EOU (End-of-Utterance) detection for filtered backchannel utterances
• Added configuration options to AgentSession for enabling/customizing the filter
• Included comprehensive test suite (21 tests), demo agent, and documentation

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
livekit-agents/livekit/agents/voice/interruption_filter.py	New core filter implementation with regex-based word matching and state-aware logic
livekit-agents/tests/test_interruption_filter.py	Comprehensive unit tests covering filter behavior in various scenarios
examples/voice_agents/interrupt_demo.py	Demo agent showcasing the interruption handling feature
proof/transcript.txt	Annotated transcript demonstrating filter behavior
CHANGES.md	Documentation explaining architecture, configuration, and design decisions
livekit-agents/livekit/agents/voice/agent_activity.py	Integration point: state capture, filter application, and flag management
livekit-agents/livekit/agents/voice/audio_recognition.py	Modified to skip EOU detection for filtered utterances using new hook
livekit-agents/livekit/agents/voice/agent_session.py	Added configuration options for filter enable/disable and custom word lists
livekit-agents/livekit/agents/voice/__init__.py	Exported filter classes and constants to public API
livekit-agents/livekit/agents/telemetry/traces.py	Added compatibility for newer opentelemetry-sdk versions (unrelated to main feature)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.