---
title: "從 LiveKit Agents 使用 ThunderPhone"
description: "將 ThunderPhone 語音智慧體作為 LiveKit Agents 工作階段的即時（語音對語音）模型執行，並由 LiveKit 房間、SIP 與電話服務環繞支援。"
---

[LiveKit Agents](https://github.com/livekit/agents) 是一個以 LiveKit 房間為基礎的開源框架，
用於建立即時語音智慧體。ThunderPhone 可作為 **即時模型** 整合：框架會傳送參與者的音訊，ThunderPhone
回傳智慧體語音、逐字稿和函式呼叫，而 LiveKit 的房間、
SIP 中繼和電話系統則傳輸音訊。語音辨識、語言模型、語音、輪流對話、62 種語言及工具皆在 ThunderPhone 上執行。

以這種方式撥打的通話會顯示在[通話紀錄](/api-reference/calls)中，並與其他即時通話一樣計費（[定價](/zh-Hant/guides/pricing)）。不涉及訂閱，也不需要 ThunderPhone 電話號碼。

## 安裝

```bash
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](https://github.com/livekit/agents)
儲存庫中，並與 `livekit-agents` 一同發布，因此請讓兩者維持相同版本。LiveKit 在其
[ThunderPhone 外掛程式指南](https://docs.livekit.io/agents/models/realtime/thunderphone/)中提供相關說明。

此插件封裝了 LiveKit 的 OpenAI Realtime 模型，因為 ThunderPhone 的
[Realtime WebSocket](/api-reference/realtime) 使用相同的通訊協定。它需要 `livekit-agents` 1.8 或更新版本。

## 執行已儲存的智慧體

智慧體執行的所有事項（提示詞、語音、引擎、語言、工具、問候語、靜默檢查）都在 ThunderPhone 上設定。工作階段僅傳送音訊。在控制台建立智慧體，或讓 Zeus（可建置、測試並調校 ThunderPhone 智慧體的 AI 智慧體）完成設定，然後在此傳入其 ID。你部署至 ThunderPhone 的變更會套用到下一通電話，無須修改 LiveKit 程式碼。

```python
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 語音。

```python
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 first
```

ThunderPhone 會在通話開始時凍結指示與工具，因此通話期間不支援 `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 在即時通訊協定之上新增平台事件。工作階段會發出這些事件：

```python
@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}`](/api-reference/calls) 擷取錄音、逐字稿和評分。其他所有 `call.*` 事件（轉接、按鍵、忽略語音）都會以 `thunderphone_call_event` 傳送。

## 限制

- 輪次偵測在伺服器端進行且一律啟用；框架端的輪次偵測
  （`AgentSession` 上的 `turn_detection`）會被忽略。
- 通話開始後，無法變更指示和工具。
- 雙向音訊皆為 24 kHz 的 16 位元單聲道 PCM。
- 影片影格會被忽略。

<Note>
改用 Pipecat 建置嗎？請參閱[從 Pipecat 使用 ThunderPhone](/zh-Hant/guides/use-with-pipecat)。
</Note>
