開発ツール

LiveKit Voice AI 電話エージェント：SIP、割り込み、有人転送、通話ログ

LiveKit AgentSession、SIP トランク、着信ディスパッチ、割り込み、DTMF、有人転送、通話ログ、テスト、コンプライアンスを解説します。

LiveKit エージェントは、音声認識、LLM、音声合成、およびツールの呼び出しをリアルタイム セッションに組み込んで、SIP 経由で通常の電話ネットワークに接続できます。 Google トレンドの voice ai agents は米国で 350% 増加しました。ただし、電話ロボットがオンラインにならないのは通常、モデルが十分に賢くないためではなく、SIP ルーティング、中断、手動転送、およびログ リンクが一緒に検証されていないことが原因です。 この記事では、顧客サービスへの着信を例として使用します。まず、室内のエージェントがルーティングされ、次に電話番号に応答し、最後に本番通話に必要な障害パスが処理されます。

電話はどのようなコンポーネントを経由しますか?

発信者は電話番号をダイヤルします。 電話会社または LiveKit 電話番号は、通話を SIP トランクにルーティングします。 受信トランクは、どの番号とソースが受信できるかを決定します。 ディスパッチ ルールにより、SIP 参加者は LiveKit ルームに入れられます。 エージェント ワーカーはジョブを受け入れ、AgentSession を作成します。 STT は音声をテキストに変換し、LLM が応答を決定するかツールを呼び出し、TTS が応答を電話に送り返します。 人間に転送する場合、システムは新しい SIP 参加者を作成するか、通話を外部番号に渡します。 各層には独立したログと障害ステータスがあります。

まずブラウザ ルームでエージェント

を確認します 電話ネットワークでは、キャリア、番号、および SIP 構成変数が追加されます。 まず、LiveKit Playground またはローカルのオーディオ ルームを使用して音声エージェントを確認します。

  • を完了できるはずです。 ユーザーの声を聞いてください。
  • 妥当な遅れ以内に応答してください。
  • ユーザーが中断すると、現在の TTS を停止します。
  • 副作用のないツールを呼び出してください。
  • リソースはセッションが終了すると解放されます。

この手順が失敗した場合は、最初に電話番号を確認しないでください。

プロジェクトとローカル環境の作成

公式ドキュメントに従って LiveKit Cloud プロジェクト、またはセルフホスト LiveKit Server を準備します。 ローカル Python 環境:

1
2
3

python3 -m venv .venv-livekit
source .venv-livekit/bin/activate
python -m pip install --upgrade pip

Windows PowerShell:

1
2
3

python -m venv .venv-livekit
.\.venv-livekit\Scripts\Activate.ps1
python -m pip install --upgrade pip

古いブログから古いバージョンを固定せずに、現在のクイックスタートに従ってエージェントと必要なプラグインをインストールします。

環境変数はサーバー側にのみ配置されます 

1
2
3

LIVEKIT_URL=wss://example.livekit.cloud
LIVEKIT_API_KEY=replace-me
LIVEKIT_API_SECRET=replace-me

STT、LLM、および TTS プロバイダーも独自のキーを持っています。 .env.local を無視リストに追加します:

1

git check-ignore .env.local

API シークレットはブラウザーやモバイル デバイスに入力できません。 クライアントは、サーバーによって発行された短期ルーム トークンのみを取得します。

AgentSession は音声パイプライン

のコーディネーターです。 AgentSession は、ユーザー入力、モデル、ツール、出力、およびイベントを担当します。 特定のプラグイン名とパラメーターはバージョンによって異なります。固定サプライヤーにコミットする代わりに、その構造を以下に示します:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from livekit.agents import Agent, AgentSession

class SupportAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions=(
                "You are a concise phone support agent. "
                "Confirm identity before reading private account data. "
                "Offer a human handoff when the caller asks."
            )
        )

async def entrypoint(ctx):
    session = AgentSession(
        stt=build_stt(),
        llm=build_llm(),
        tts=build_tts(),
    )
    await session.start(
        room=ctx.room,
        agent=SupportAgent(),
    )

build_stt() などの関数は、正式にサポートされているプラグイン インスタンスに置き換える必要があります。

電話プロンプトの言葉は画面のないシナリオに適応させる必要がある

リンク、テーブル、コードはユーザーには表示されません。 回答は短くし、一度に 1 つの質問のみをしてください。 番号、日付、電子メールは確認のために繰り返す必要があります。 10 個のメニュー項目を一度に読み上げないでください。 手動への移行、繰り返し、前のステップに戻って通話を終了するための明確な指示が必要です。 認証は、発信者番号に基づいた自動信頼ではなく、アカウント操作が関与する前に実行されます。

ツールへの読み取りおよび書き込み権限の割り当て

営業時間の確認は読み取り専用ツールです。 お問い合わせの際には個人情報を読み取る場合があります。 注文のキャンセル、返金、アドレス変更は書き込み操作です。 書き込みツールは 2 回目の確認を必要とし、最終パラメータをユーザーに繰り返し入力します。

1
2
3
4

async def cancel_order(order_id: str, confirmed: bool) -> str:
    if not confirmed:
        return "confirmation_required"
    return await order_service.cancel(order_id)

LLM が自然言語に基づいて confirmed=True を独自に作成させないでください。 確認ステータスはセッション ロジックで管理する必要があります。

割り込み機能が電話エクスペリエンスを決定します

ユーザーが話し始めると、エージェントは現在の TTS を停止またはフェードアウトする必要があります。 過敏症の人は、咳、背景のテレビ、エコーを中断として解釈します。 過度に遅くなると、ユーザーはエラーを修正できなくなります。 デバッグ中の記録:

  • ユーザーボイスの開始時刻。
  • VAD 検出時間。
  • TTSの停止時間。
  • STT最終結果タイム。
  • 新しい回答の最初の音声時間。

遅延がどこから来たのかを知ることができるのは、エンドツーエンドのタイムラインだけです。

方向転換検出と電話ノイズ

電話の音声帯域幅、圧縮、ノイズはウェブマイクとは異なります。 短い沈黙は、必ずしもユーザーが話し終えたことを意味するわけではありません。 住所、注文番号、名前の間に自然な空白が生じる場合があります。 LiveKit によって現在提供されている方向転換検出と VAD 構成を使用して、実際の電話の録音からテストします。 静かなオフィスでパラメータを調整するためにブラウザのマイクだけを使用しないでください。

電話番号

を購入またはアクセスします LiveKit 電話番号を使用することも、サポートされているサードパーティの SIP プロバイダーを設定することもできます。 番号を選択する際は、国、地域、テキスト メッセージング機能、緊急通話の制限、ID 要件を確認してください。 番号の購入が成功しても、受信ルーティングが完了したことを意味するものではありません。 通話をルームに送信するには、トランク ルールとディスパッチ ルールも必要です。 オペレーター コンソールと LiveKit コンソールはそれぞれ検証可能な ID を保持します。

受信トランクは許可される数を制限します

受信トランクは、どの電話番号と SIP ソースを受信するかを定義します。 実稼働とテストには異なる番号またはトランクを使用します。 すべての SIP ソースを受け入れず、エージェントの拒否に依存しないでください。 オペレーターが IP 認証または資格情報認証をサポートしている場合は、公式の推奨に従ってそれを有効にします。 トランクを変更した後、テスト コールを実行して、古いルール キャッシュではなく新しい設定がヒットすることを確認します。

ディスパッチ ルールによりルームの名前とエージェント

が決定されます 通話ごとに固有のルームを生成して、2 つの未知の通話が同じ会話に入ることを防ぎます。 ルーム名には内部コール ID を含めることができますが、完全な電話番号を含めることはできません。 ルーティングに必要なフィールドのみがメタデータに配置されます。 エージェントの従業員は、ジョブのメタデータに基づいてカスタマー サービス、販売、または予約エージェントを選択します。 一致するエージェントがない場合は、可聴の障害プロンプトまたは転送パスが存在する必要があり、沈黙し続けることはできません。

着信通話の最小受け入れ数

会社の Wi-Fi に接続されていない実際の電話からダイヤルします。 レコード:

1
2
3
4
5

carrier_call_id
sip_participant_id
room_name
agent_job_id
session_id

着信を確認してから 3 ～ 5 秒以内に、少なくとも挨拶または待機のプロンプトが表示される必要があります。 通話は接続されているが音声が聞こえない場合は、SIP 参加者のトラック、エージェントが参加しているかどうか、および TTS が解放されているかどうかを確認してください。

403 および 404 エージェント ログを見るだけではありません

SIP 層 403 は、認証、送信元制限、番号が検証されていない、または通信事業者のポリシーに起因する可能性があります。 404 ルーティング番号またはトランク番号が一致していない可能性があります。 LiveKit ルームは作成されましたが、エージェントがありません。派遣と労働者の空き状況に焦点を当てます。 エージェントは開始されましたが、発信者の参加者がいません。 SIP アクセスに重点を置きます。 オペレーター側と LiveKit 側の両方でコール ID を保存します。

音声認識の代替入力としての DTMF

電話のキーパッドは、メニュー、数値オプション、デリケートな操作の確認に適しています。 たとえば、1 を押して手動に切り替え、2 を押して繰り返し、9 を押して終了します。 DTMF および音声コマンドで同じアクションを 2 回トリガーしないでください。 各入力にイベント ID を割り当て、ステート マシンを使用して重複を排除します。 銀行カードやパスワードなどの機密データは、完全なキーストローク シーケンスで通常のログに記録されるべきではありません。

手動転送は、エージェントに「転送済み」と言うように要求することを意味するものではありません

真のハンドオフには、少なくとも宛先キュー、コンテキスト ダイジェスト、およびコール ルーティングが含まれます。 LiveKit エージェントのハンドオフは、異なる AI エージェント間で役割を切り替えるのに適しています。 ライブカスタマーサービスに切り替えるには、通常、新しい SIP アウトバウンド参加者または外部コールセンターの統合が必要です。 キュー中にプロンプトを再生し、ユーザーがキャンセルできるようにします。 転送が失敗した場合は、直接電話を切るのではなく、元のエージェントに戻るか、コールバックを提供してください。

人間に渡されるコンテキストは最小限に抑える必要があります

含まれるもの:

  • 顧客IDを確認しました。
  • ユーザーの現在の目標。
  • 読み取り専用クエリが実行されました。
  • 未完了の操作。
  • ユーザーが録音に同意するかどうか。

モデルの思考プロセス全体、無関係な履歴、通話テキストのすべてをカスタマー サービスに渡さないでください。 概要では、ユーザーが明示的に述べた内容とエージェントが推測した内容をマークする必要があります。

アウトバウンド呼び出しにはより厳格な認証が必要

アウトバウンド SIP は、コールバック、リマインダー、アンケートに使用できます。 ただし、スパム電話、タイムゾーン、同意の問題が発生する可能性もあります。 番号リストは、法的根拠のあるビジネス システムから取得されたものでなければなりません。 電話をかける前に、現地時間、登録解除ステータス、フリークエンシー キャップを確認してください。 LLM にダイヤルする番号を選択させることは禁止されています。 各アウトバウンド呼び出しには、明示的なビジネス タスク ID が必要です。

通話録音と文字起こしの個別管理

録音、ライブ文字起こし、要約、ビジネスフィールドは異なるデータオブジェクトです。 録音に対するユーザーの同意は、必ずしもユーザーが完全な転写の長期保存に同意することを意味するものではありません。 アクセス権限と保存期間を個別に設定します。 記録 URL は短期署名を使用し、通常のアプリケーション ログには記録されません。 削除リクエストは、オブジェクト ストレージ、インデックス作成、要約、およびバックアップ ポリシーを上書きします。

イベント ログに元のキー

が記録されない 推奨レコード:

1
2
3
4
5
6
7
8

{
  "session_id": "sess_example",
  "call_id": "call_example",
  "event": "human_handoff_requested",
  "timestamp": "2026-07-28T12:00:00Z",
  "target_queue": "support_cn",
  "result": "queued"
}

電話番号にはマスクまたは内部 ID のみが保持されます。 デフォルトでは、STT テキストはインフラストラクチャ デバッグ ログに記録されません。

遅延バジェットはセグメント

で測定する必要があります 合計の応答遅延は次のように分類できます:

1

VAD + final STT + LLM first token + TTS first audio + network

P50、P95、故障率を個別に記録します。 平均により、時折発生する 10 秒間の一時停止が隠蔽されます。 LLM ツールの呼び出し中に短い待機プロンプトを再生しますが、毎秒繰り返さないでください。 固定されたグリーティングをキャッシュすると、最初の TTS 遅延が短縮されます。

エコーとデュアルボイスを見つける方法

まず、発信者が 1 つのエージェント音声トラックのみを購読していることを確認してください。 エージェントが同じルームに繰り返し参加していないか確認してください。 オペレータ側の録音は正常であるにもかかわらず、携帯電話にエコーが聞こえる場合、それは端末の音響エコーである可能性があります。 室内録音に二重音声がある場合は、トラックのパブリケーションと繰り返し送信される TTS を確認してください。 VAD しきい値を増やして繰り返しトラックをマスクしないでください。

ワーカーが切断されたときに回復可能なエクスペリエンスを維持する

エージェント ワーカーがクラッシュした後も、SIP コールが接続されている可能性があります。 ジョブのタイムアウト、ワーカーのヘルスチェック、バックアップルートを設定します。 回復時間が短いため、新しいワーカーはセッション状態を読み取ることができます。 回復できない場合は、再生障害の説明とマニュアル番号が提供されます。 ユーザーをサイレント回線で無限に待たせないでください。

ストレス テストの場合、同じ携帯電話番号から

に手動でダイヤルすることはできません。 公式テスト ツールまたは制御された SIP テスト アカウントを使用して同時実行性を生成します。 同時実行数、観察室、ワーカー、STT、LLM、TTS、オペレーター割り当てを徐々に増やします。 制限はプロバイダーごとに異なる場合があります。 ストレステスト番号は製造番号から分離されています。 異常電話と判断されないよう、オペレータに事前に連絡してください。

料金は完全なコール チェーン

に基づいて計算されます 料金には、電話番号、SIP 時間、LiveKit、STT、LLM、TTS、録音ストレージ、転送作業が含まれます。 ツールの呼び出しにもビジネス API コストが発生する場合があります。 各通話の実際の秒数とプロバイダーの使用状況を記録します。 失敗した通話や待機中の通話にも料金が請求されます。 正常に解決された通話ごとに単価を計算することは、単に 1 分あたりの料金を調べるよりも合理的です。

フォールト ドリル チェックリストのセット

Agent ワーカーを停止し、音の低下を確認します。 STT キーを無効にし、ユーザーに対して間違った質問に繰り返し回答しないことを確認します。 LLM をタイムアウトさせ、手動作業に移行できることを確認します。 TTS を失敗させて、システムがミュート状態のままにならないことを確認します。 手動キューを使用不可にして、コールバックまたは確認のメッセージを提供します。 DTMF を 2 回押して、書き込み操作が繰り返されないことを確認します。

オンライン判定

  • ブラウザルームのエージェントは独立して通過しました。
  • SIP トランクとディスパッチ ID を追跡できます。
  • 通話ごとに別の部屋を使用します。
  • ユーザーによる割り込みにより TTS が停止する場合があります。
  • 読み取りツールと書き込みツールの権限の分離。
  • 実際の電話ルーティングを完了するには、手動に切り替えます。
  • 録音、文字起こし、要約は個別に管理されます。
  • キャリアと LiveKit コール ID を関連付けることができます。
  • 切断、タイムアウト、クォータ障害はすべて、音声の劣化を引き起こします。
  • 発信通話には同意、タイムゾーン、頻度の制御があります。

電話の音声 AI の品質は、1 回の応答のパフォーマンスではなく、通話チェーン全体に依存します。まずブラウザ ルームをクリアし、次に SIP、DTMF、手動転送、および記録をレイヤーごとに追加して、各障害に明確な責任の位置を持たせることができます。

LiveKit ドキュメント エントリ