Open in
從 LiveKit Agents 使用 ThunderPhone
將 ThunderPhone 語音智慧體作為 LiveKit Agents 工作階段的即時(語音對語音)模型執行,並由 LiveKit 房間、SIP 與電話服務環繞支援。
LiveKit Agents 是一個以 LiveKit 房間為基礎的開源框架, 用於建立即時語音智慧體。ThunderPhone 可作為 即時模型 整合:框架會傳送參與者的音訊,ThunderPhone 回傳智慧體語音、逐字稿和函式呼叫,而 LiveKit 的房間、 SIP 中繼和電話系統則傳輸音訊。語音辨識、語言模型、語音、輪流對話、62 種語言及工具皆在 ThunderPhone 上執行。
以這種方式撥打的通話會顯示在通話紀錄中,並與其他即時通話一樣計費(定價)。不涉及訂閱,也不需要 ThunderPhone 電話號碼。
安裝
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_... # a secret API key使用 uv 時,uv add "livekit-agents[thunderphone]~=1.8" 會安裝相同的
外掛程式。它位於 livekit/agents
儲存庫中,並與 livekit-agents 一同發布,因此請讓兩者維持相同版本。LiveKit 在其
ThunderPhone 外掛程式指南中提供相關說明。
此插件封裝了 LiveKit 的 OpenAI Realtime 模型,因為 ThunderPhone 的
Realtime WebSocket 使用相同的通訊協定。它需要 livekit-agents 1.8 或更新版本。
執行已儲存的智慧體
智慧體執行的所有事項(提示詞、語音、引擎、語言、工具、問候語、靜默檢查)都在 ThunderPhone 上設定。工作階段僅傳送音訊。在控制台建立智慧體,或讓 Zeus(可建置、測試並調校 ThunderPhone 智慧體的 AI 智慧體)完成設定,然後在此傳入其 ID。你部署至 ThunderPhone 的變更會套用到下一通電話,無須修改 LiveKit 程式碼。
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import thunderphone
async def entrypoint(ctx: JobContext):
session = AgentSession(llm=thunderphone.RealtimeModel(agent_id=12))
await session.start(agent=Agent(instructions=""), room=ctx.room)
if __name__ == "__main__":
cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))已儲存的智慧體會在 ThunderPhone 上問候來電者並執行自己的工具;LiveKit
Agent 的指示與工具不會被傳送。當 ThunderPhone 智慧體掛斷時,通話便會結束,工作階段也會隨之關閉。
內嵌設定工作階段
未設定 agent_id 時,指令與工具會如同 OpenAI 的運作方式,取自 LiveKit Agent。model 用於選擇引擎,voice 用於選擇 ThunderPhone 語音。
from livekit.agents import Agent, AgentSession, RunContext, function_tool
from livekit.plugins import thunderphone
class Receptionist(Agent):
def __init__(self):
super().__init__(instructions="You are Acme Dental's receptionist. Be brief.")
@function_tool
async def check_availability(self, context: RunContext, date: str) -> dict:
"""Free appointment slots on a date."""
return {"slots": await calendar.free_slots(date)}
async def entrypoint(ctx: JobContext):
session = AgentSession(
llm=thunderphone.RealtimeModel(model="bolt", voice="olivia", language="es"),
)
await session.start(agent=Receptionist(), room=ctx.room)
await session.generate_reply() # the agent speaks firstThunderPhone 會在通話開始時凍結指示與工具,因此通話期間不支援 update_instructions、update_tools,以及會變更它們的智慧體交接。內嵌工作階段由用戶端控制:當你呼叫 generate_reply(),或參與者完成一輪對話時,智慧體便會說話。
選項
| 參數 | 說明 |
|---|---|
api_key | 密密鑰(sk_live_...)。預設為 THUNDERPHONE_API_KEY。 |
agent_id | 執行已儲存的智慧體。不可與 model 和 voice 同時使用。 |
model | 內嵌工作階段使用的引擎:bolt(仍接受較舊的 spark 和 storm)。 |
voice | 內嵌工作階段使用的 ThunderPhone 語音名稱。 |
language | 內嵌工作階段的主要語言提示,例如 es。 |
caller_number, callee_number | 當房間連接電話線路時的通話電話號碼。它們會在通話紀錄中顯示為來電與受話號碼。 |
live_transcripts | 在來電者說話途中串流逐字稿片段(額外計費)。 |
base_url | 端點覆寫,預設為 wss://api.thunderphone.com/v1/realtime。 |
事件
ThunderPhone 在即時通訊協定之上新增平台事件。工作階段會發出這些事件:
@session.llm.session.on("thunderphone_call_ended") # or on the RealtimeSession you hold
def on_call_ended(event):
print("call ended:", event["reason"])工作階段啟用後,RealtimeSession 會提供 call_id。通話結束後,請搭配
GET /v1/calls/{call_id} 擷取錄音、逐字稿和評分。其他所有 call.* 事件(轉接、按鍵、忽略語音)都會以 thunderphone_call_event 傳送。
限制
- 輪次偵測在伺服器端進行且一律啟用;框架端的輪次偵測
(
AgentSession上的turn_detection)會被忽略。 - 通話開始後,無法變更指示和工具。
- 雙向音訊皆為 24 kHz 的 16 位元單聲道 PCM。
- 影片影格會被忽略。