site iconKoei's Digital Garden

Archive

TurnHandlingOptions リファレンス

4 min read

TurnHandlingOptions リファレンス

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ

What（何についてか）

AgentSession の turn_handling に渡す設定オブジェクトを扱う。対象は turn_detection、endpointing、interruption の3領域であり、ユーザー発話の終端判定、応答開始タイミング、割り込み処理の一連の挙動を制御する。

Why（なぜ必要か）

LiveKit Agents の会話品質は、モデル選択だけでなくターン制御の設定に強く依存する。判定が早すぎると発話の被りが起き、遅すぎると会話が停滞する。さらに、誤割り込み時の復帰が不適切だと対話が分断される。TurnHandlingOptions はこれらの挙動を一箇所で定義できるため、会話体験の再現性とチューニング可能性を担保する。

How（どう動くか）

turn_detection はターン終了判定の戦略を定義する。realtime_llm、vad、stt、manual を選べ、未指定時は優先順に自動選択される。

endpointing はターン確定までの待機時間を決める。mode は fixed または dynamic（Pythonのみ）を取り、min_delay と max_delay により待機時間の下限と上限を与える。

interruption は割り込み判定と復帰動作を制御する。mode、min_duration、min_words、false_interruption_timeout、resume_false_interruption の組み合わせで、ノイズ耐性と応答継続性を調整する。

graph TD
    A[User Speech] --> B[Turn Detection]
    B --> C[Endpointing Delay]
    C --> D[Agent Turn Complete]
    D --> E[Agent Response Playback]
    E --> F{User Barge-in?}
    F -->|No| G[Continue Playback]
    F -->|Yes| H[Interruption Handling]
    H --> I{False Interruption?}
    I -->|Yes| J[Resume Playback]
    I -->|No| K[Switch to User Turn]

Usage（Python）

from livekit.agents import AgentSession, TurnHandlingOptions
 
session = AgentSession(
    turn_handling=TurnHandlingOptions(
        turn_detection="vad",
        endpointing={
            "mode": "fixed",
            "min_delay": 0.5,
            "max_delay": 3.0,
        },
        interruption={
            "mode": "adaptive",
            "min_duration": 0.5,
            "resume_false_interruption": True,
        },
    ),
)

Endpointing（Python）

turn_handling = {
    "endpointing": {
        "mode": "dynamic",
        "min_delay": 0.5,
        "max_delay": 3.0,
    },
}

Interruption（Python）

turn_handling = {
    "interruption": {
        "mode": "adaptive",
        "min_duration": 0.5,
        "min_words": 0,
        "discard_audio_if_uninterruptible": True,
        "false_interruption_timeout": 2.0,
        "resume_false_interruption": True,
    },
}
turn_handling = {
    "interruption": {"enabled": False},
}

False interruption の時系列

sequenceDiagram
    participant U as User
    participant A as Agent
    participant I as Interruption Detector
    participant S as STT

    A->>U: Agent speech output
    U->>I: Candidate barge-in audio
    I->>I: Check min_duration
    alt Too short
        I-->>A: Ignore as noise
        A->>U: Continue speech
    else Duration accepted
        I-->>A: Interrupt playback
        A->>A: Pause output
        alt Transcript detected
            S-->>A: User transcript
            A->>A: Continue as real interruption
        else No transcript
            I->>I: Wait false_interruption_timeout
            I-->>A: Emit false interruption
            alt resume_false_interruption = True
                A->>U: Resume paused speech
            else resume_false_interruption = False
                A->>A: Keep paused state
            end
        end
    end

Key Concepts

用語説明
turn_detectionユーザー発話終了の判定方式。未指定時は優先順フォールバックが適用される。
endpointingターン確定前の待機挙動。min_delay/max_delay でテンポを制御する。
interruption割り込み判定と復帰ロジック。誤検知時の再開可否まで含めて制御する。
false interruption割り込み判定後に実際の発話が確認されないケース。タイムアウト後の復帰設定が重要。

実装上の注意

  • Pythonでは min_delay、max_delay、min_duration、false_interruption_timeout は秒単位で扱う。
  • turn_detection 未指定時の自動選択とフォールバック前提で、利用モデルの有無によって挙動が変化する。
  • interruption.enabled を False にすると割り込み処理が無効化される。旧来のbool shorthandはサポートされない。

一言まとめ

TurnHandlingOptions は、ターン終端判定・待機時間・割り込み復帰を統合して会話テンポを制御する中核設定である。

Graph View

Backlinks