Thanks — I’m responding to your request for a complete guide on using TurnHandlingOptions. Below is a concise, practical guide you can use to configure turn detection, endpointing, and interruption handling for LiveKit agents. Overview • TurnHandlingOptions controls how an agent detects when a user has finished speaking (turn detection), when the agent should end listening (endpointing), and how the agent treats user interruptions (barge-ins vs backchannel). • You pass it to AgentSession to control conversation flow and responsiveness. Quick example (Python)

from livekit.agents import TurnHandlingOptions
from livekit.plugins.turn_detector.multilingual import MultilingualModel

turn_handling = TurnHandlingOptions(
    turn_detection=MultilingualModel(),
    endpointing={"min_delay": 0.5, "max_delay": 3.0},
    interruption={"mode": "adaptive", "enabled": True}
)

session = AgentSession(
    turn_handling=turn_handling,
    stt="deepgram/nova-3:multi",
    llm="openai/gpt-4.1-mini",
    tts="cartesia/sonic-3:...",
    vad=silero.VAD.load(),
)

1) Turn detection modes — how to choose • MultilingualModel(): context-aware model trained for conversational turn-taking. Good default for natural behavior; requires STT and VAD. • "realtime_llm": uses realtime model’s built-in activity detection (e.g., OpenAI Realtime or Gemini Live). When used, disable automatic detection on the realtime model if you want LiveKit to manage turns. • "stt": rely on STT end-of-speech signals (AssemblyAI, Deepgram, etc.). Combine with VAD for faster reactions. • "vad": use only voice-activity (silence) detection. Simple and low-cost. • "manual": you manage turns explicitly via

commit_user_turn()

,

interrupt()

, and

clear_user_turn()

. When to ask a clarifying question: • If you have multiple agents or realtime models in play, tell me which model and environment (Cloud or self-hosted) so I can recommend exact settings. 2) Endpointing — tuning delays for natural flow • Purpose: define how long silence must last before the system considers the user’s turn ended. • Key parameters: ◦

min_delay

— minimum silence time (seconds) before ending the turn (e.g., 0.5). ◦

max_delay

— cap for silence wait (seconds) to force a turn end (e.g., 3.0). ◦

mode

(

fixed

or

dynamic

, Python only) —

dynamic

adapts delays using pause stats to be more natural. • Node.js note: min/max delays are specified in milliseconds (e.g., 500, 3000). • Best practice: start with min_delay ~0.5s and max_delay ~2.5–3s and adjust based on user speech patterns. 3) Interruption handling — barge-ins vs backchannel • Purpose: decide if and how a user can interrupt agent speech. • Main options: ◦ `enabled`: true/false — allow interruptions. ◦ `mode`:

adaptive

(recommended) or

vad

. ▪︎

adaptive

uses acoustic/context cues to ignore backchannels while allowing true barge-ins. ▪︎

vad

flags any detected speech as interruption (simpler). ◦

min_duration

/ `min_words`: require a minimum speech duration or word count to treat as interruption (helps filter noise). ◦ `resume_false_interruption`: resume agent speech after a false interruption (e.g., cough) when appropriate. ◦ `false_interruption_timeout`: how long to wait before marking interruption as false. ◦ `discard_audio_if_uninterruptible`: drop audio if agent cannot be interrupted. • Recommendation: use

adaptive

with aligned STT transcripts when available for best UX. 4) Combined patterns & edge cases • Realtime LLM + LiveKit detection: if you use realtime LLM automatic detection, disable automatic detection on that model if you want LiveKit’s turn detector to handle endpointing. • STT-based detection: if you rely on STT for endpointing, set

endpointing.min_delay = 0

to avoid stacking delays (prevents added latency). • Always provide a VAD plugin even when using STT endpointing — improves responsiveness for interruptions. 5) Language & model considerations • MultilingualModel supports many languages (EN, ES, FR, DE, IT, PT, NL, ZH, JA, KO, ID, TR, RU, HI). • Adaptive interruption works best with STT that provides aligned transcripts. 6) Events to monitor • Listen for session events to observe turn/interrupt state: ◦

user_state_changed

— user started/stopped speaking. ◦

agent_state_changed

— agent speaking/thinking. ◦

user_interruption_detected

— when an interruption is detected. ◦

agent_false_interruption

— false interruption occurred; agent may resume. • Use these events to log behavior or adjust heuristics in real time. 7) Best practices / Recommendations • Default: Use

MultilingualModel

+

adaptive

interruption + VAD for robust natural conversations. • Tune endpointing

min_delay

and

max_delay

to your user population and use

dynamic

mode (Python) if you need adaptive timing. • Use

min_words

or

min_duration

if you see many short noises triggering interruptions. • For self-hosted deployments, note adaptive interruption quotas may apply. 8) Manual control (when you want full control) • Set

turn_detection="manual"

and call: ◦

session.interrupt()

— stop agent speech immediately. ◦

session.commit_user_turn()

— tell the system the user finished speaking and should be processed. ◦

session.clear_user_turn()

— discard current user audio. If you want, I can: • Provide a tailored example for Node.js (with millisecond endpointing) or for your exact STT/LLM/TTS stack. • Recommend starting values for

min_delay

,

max_delay

,

min_duration

, and

min_words

based on your use case (e.g., short Q&A vs. long-form conversation). • Show sample event handlers for logging or metrics. Would you like a Node.js example or a configuration tuned for short customer-support calls vs. long conversational flows? Sources: Turns overview | LiveKit Documentation | Agent session | LiveKit Documentation | LiveKit turn detector plugin | LiveKit Documentation | Gemini Live API plugin | LiveKit Documentation | Adaptive interruption handling | LiveKit Documentation, with interactive elements