LiveKit Voice AI 電話 Agent：SIP、打斷、轉接真人與通話日誌

LiveKit Agents 可以把語音識別、LLM、語音合成和工具呼叫放進一個實時會話，再透過 SIP 接入普通電話網路。 Google Trends 的 voice ai agents 在美國區上升 350%，但電話機器人上線失敗通常不是模型不夠聰明，而是 SIP 路由、打斷、轉人工和日誌鏈路沒有一起驗證。 本文用入站客服電話為例，先跑通房間 Agent，再接電話號碼，最後處理生產電話必須具備的失敗路徑。

一通電話會經過哪些元件

呼叫者撥打電話號碼。 電話運營商或 LiveKit Phone Numbers 把呼叫送入 SIP trunk。 Inbound Trunk 決定哪些號碼和來源可以進入。 Dispatch Rule 把 SIP participant 放進 LiveKit room。 Agent worker 接受 job，並建立 AgentSession。 STT 把音訊轉成文字，LLM 決定回答或呼叫工具，TTS 把答案送回電話。 轉人工時，系統建立新的 SIP participant 或把呼叫交給外部號碼。 每一層都有獨立日誌和失敗狀態。

先在瀏覽器房間驗證 Agent

電話網路會增加運營商、號碼和 SIP 配置變數。 先用 LiveKit Playground 或本地音訊房間驗證語音 Agent。 它應能完成：

• 聽到使用者語音。
• 在合理延遲內回答。
• 使用者插話時停止當前 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

按當前 quickstart 安裝 Agents 與所需外掛，不從舊部落格固定過期版本。

環境變數只放服務端

1
2
3

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

STT、LLM 和 TTS 供應商還會有各自 key。 把 .env.local 加入忽略列表：

1

git check-ignore .env.local

API secret 不能進入瀏覽器或移動端。 客戶端只獲取服務端簽發的短期 room token。

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
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。 確認狀態應由會話邏輯管理。

打斷能力決定電話體驗

使用者開始說話時，Agent 應停止或淡出當前 TTS。 過度敏感會把咳嗽、背景電視和回聲當成打斷。 過度遲鈍則讓使用者無法糾正錯誤。 除錯時記錄：

• 使用者語音開始時間。
• VAD 檢測時間。
• TTS 停止時間。
• STT 最終結果時間。
• 新回答首音訊時間。

只有端到端時間線才能說明延遲來自哪一段。

Turn Detection 與電話噪聲

電話音訊頻寬、壓縮和噪聲與網頁麥克風不同。 短暫停頓不一定表示使用者說完。 地址、訂單號和姓名中間可能自然停頓。 使用 LiveKit 當前提供的 turn detection 和 VAD 配置，從真實電話錄音做測試。 不要只拿安靜辦公室的瀏覽器麥克風調參數。

購買或接入電話號碼

可以使用 LiveKit Phone Numbers，或配置支援的第三方 SIP provider。 選擇號碼時確認國家、地區、簡訊能力、緊急呼叫限制和身份要求。 號碼購買成功不等於入站路由已經完成。 還需要 trunk 和 dispatch rule 把呼叫送進 room。 運營商控制檯與 LiveKit 控制檯各儲存一個可核對的 ID。

Inbound Trunk 限定允許的號碼

Inbound Trunk 定義接收哪些電話號碼和 SIP 來源。 生產與測試使用不同號碼或 trunk。 不要把任意 SIP 來源全部接受後再依賴 Agent 拒絕。 若運營商支援 IP 或憑據認證，按官方建議啟用。 修改 trunk 後撥打一次測試電話，確認命中的是新配置而非舊規則快取。

Dispatch Rule 決定 room 命名與 Agent

為每通電話生成唯一 room，避免兩個陌生來電進入同一會話。 room 名稱可以包含內部 call ID，但不要包含完整電話號碼。 metadata 中只放路由所需欄位。 Agent worker 根據 job metadata 選擇客服、銷售或預約 Agent。 沒有匹配 Agent 時，要有可聽見的失敗提示或轉接路徑，不能保持靜音。

入站電話的最小驗收

用一部不在公司 Wi-Fi 的真實手機撥號。 記錄：

1
2
3
4
5

carrier_call_id
sip_participant_id
room_name
agent_job_id
session_id

確認來電後 3–5 秒內至少有歡迎語或等待提示。 如果電話接通但沒有聲音，分別檢查 SIP participant 的 track、Agent 是否加入以及 TTS 是否釋出。

403 與 404 不要只看 Agent 日誌

SIP 層 403 可能來自認證、來源限制、號碼未驗證或運營商策略。 404 可能是號碼路由或 trunk 不匹配。 LiveKit room 已建立但沒有 Agent，重點看 dispatch 與 worker availability。 Agent 已啟動但沒有 caller participant，重點看 SIP 接入。 儲存運營商和 LiveKit 兩邊的 call ID。

DTMF 作為語音識別的備用輸入

電話鍵盤適合確認選單、數字選項和敏感操作。 例如按 1 轉人工、按 2 重複、按 9 結束。 不要讓 DTMF 與語音命令觸發兩次同一操作。 為每個輸入分配事件 ID，並用狀態機去重。 銀行卡、密碼等敏感資料不應由普通日誌記錄完整按鍵序列。

轉人工不是讓 Agent 說一句“已轉接”

真正的 handoff 至少包括目標佇列、上下文摘要和電話路由。 LiveKit Agent handoff 適合在不同 AI Agent 間切換角色。 轉真人客服則通常需要新的 SIP outbound participant 或外部呼叫中心整合。 排隊期間播放提示，並允許使用者取消。 轉接失敗要返回原 Agent 或提供回撥，而不是直接結束通話。

傳給人工的上下文應最小化

可以包含：

• 已驗證的客戶 ID。
• 使用者本次目標。
• 已執行的只讀查詢。
• 尚未完成的操作。
• 使用者是否同意錄音。

不要把完整模型思維過程、無關歷史或所有通話文字塞給客服。 摘要要標記哪些是使用者明確陳述，哪些是 Agent 推斷。

出站電話需要更嚴格的授權

出站 SIP 可以用於回訪、提醒和調查。 但它也容易觸發騷擾電話、時區和同意問題。 號碼列表必須來自有合法依據的業務系統。 呼叫前檢查當地時間、退訂狀態和頻率上限。 禁止讓 LLM 自行選擇任意號碼撥出。 每個 outbound call 需要明確的業務任務 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 文字預設不進入基礎設施 debug 日誌。

延遲預算要分段測量

總響應延遲可以拆成：

1

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

分別記錄 P50、P95 和失敗率。 平均值會掩蓋偶發十秒停頓。 LLM 工具呼叫期間播放短等待提示，但不要每一秒重複。 快取固定歡迎語可以減少首次 TTS 延遲。

回聲與雙重語音如何定位

先確認 caller 只訂閱一個 Agent 音軌。 檢查 Agent 是否重複加入同一 room。 運營商側錄音若正常而手機聽到回聲，可能是終端聲學回聲。 room 錄音已經雙聲，則檢查 track publication 和 TTS 重複傳送。 不要用增加 VAD 閾值掩蓋重複音軌。

Worker 斷線時保持可恢復體驗

Agent worker 崩潰後，SIP 電話可能仍處於接通狀態。 設定 job 超時、worker 健康檢查和備用路由。 短時間恢復可以讓新 worker 讀取會話狀態。 無法恢復時播放失敗說明並提供人工號碼。 不要讓使用者在靜音線路無限等待。

壓力測試不能用同一個手機號手工撥打

使用官方測試工具或受控 SIP 測試賬號產生併發。 逐步增加併發，觀察 room、worker、STT、LLM、TTS 和運營商配額。 每個供應商限制可能不同。 壓測號碼與生產號碼隔離。 提前通知運營商，避免被判定為異常呼叫。

費用按完整通話鏈計算

成本包括電話號碼、SIP 分鐘、LiveKit、STT、LLM、TTS、錄音儲存和轉人工。 工具呼叫還可能產生業務 API 成本。 記錄每通電話的實際秒數與供應商用量。 失敗和等待通話同樣計費。 按成功解決的電話計算單位成本，比只看每分鐘價格更有意義。

一套故障演練清單

停止 Agent worker，確認有可聽見的降級。 讓 STT key 失效，確認不會反覆向使用者答非所問。 讓 LLM 超時，確認可以轉人工。 讓 TTS 失敗，確認系統不會保持接通靜音。 讓人工佇列不可用，確認提供回撥或留言。 連續按兩次 DTMF，確認寫操作不會重複。

上線判定

• 瀏覽器房間內的 Agent 已獨立透過。
• SIP trunk 與 dispatch ID 可追蹤。
• 每通電話使用獨立 room。
• 使用者插話能停止 TTS。
• 讀寫工具許可權分離。
• 轉人工完成真實電話路由。
• 錄音、轉寫和摘要分別管理。
• 運營商與 LiveKit call ID 可以關聯。
• 斷線、超時和配額失敗均有語音降級。
• 出站電話有同意、時區和頻率控制。

電話 Voice AI 的質量取決於完整呼叫鏈，而不是單輪迴答效果。先把瀏覽器房間跑通，再逐層增加 SIP、DTMF、轉人工和錄音，能讓每種失敗都有明確責任位置。

LiveKit 文件入口

• LiveKit Telephony 文件
• LiveKit AgentSession
• LiveKit Agents 與 handoff