Open in
透過 LiveKit Agents 使用 ThunderPhone
在 LiveKit Agents 工作階段中,以 ThunderPhone 語音智能體作為即時(語音對語音)模型,並配合 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。
- 影片畫面會被忽略。