ThunderPhone 2.0 正式登場。自助開通，每分鐘 2¢ 起。查看公告
立即開始

Connect tools & data

透過 LiveKit Agents 使用 ThunderPhone

在 LiveKit Agents 工作階段中，以 ThunderPhone 語音智能體作為即時（語音對語音）模型，並配合 LiveKit 房間、SIP 及電話功能。

LiveKit Agents 是一個建基於 LiveKit 房間、用於建立即時語音智能體的開源框架。ThunderPhone 以 即時模型 形式整合：框架傳送參與者的音訊，ThunderPhone 回傳智能體語音、逐字稿及函式呼叫，而 LiveKit 的房間、SIP 中繼及電話服務則負責傳送音訊。語音辨識、語言模型、語音、輪流對話、47 種語言及工具均在 ThunderPhone 上運行。

以此方式進行的通話會顯示於通話記錄，並與其他即時通話一樣，按你的產品每分鐘收費率計費。無需訂閱，亦不涉及 ThunderPhone 電話號碼。

安裝

pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key

此插件封裝 LiveKit 的 OpenAI Realtime 模型，因為 ThunderPhone 的 Realtime WebSocket 採用相同協議。需要使用 livekit-agents 1.8 或更新版本。

執行已儲存的智能體

智能體的一切設定（提示詞、語音、引擎、語言、工具、問候語及靜默跟進）均在 ThunderPhone 上配置。工作階段只會傳送音訊。

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 取得。product 用於選擇引擎，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(product="bolt", voice="olivia", language="es"),
    )
    await session.start(agent=Receptionist(), room=ctx.room)
    await session.generate_reply()   # the agent speaks first

ThunderPhone 會在通話開始時鎖定指示及工具，因此通話途中不支援會修改它們的 update_instructions、update_tools 及智能體交接。內嵌工作階段由客戶端控制：當你呼叫 generate_reply()，或參與者完成一輪發言時，智能體便會說話。

選項

參數說明
api_key密鑰（sk_live_...）。預設為 THUNDERPHONE_API_KEY。
agent_id執行已儲存的智能體。不可與 product 及 voice 同時使用。
product內嵌工作階段使用的引擎：spark、bolt 或 storm。
voice內嵌工作階段使用的 ThunderPhone 語音名稱。
language內嵌工作階段的主要語言提示，例如 es。
from_number、to_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。
  • 影片畫面會被忽略。