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

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

透過此方式撥打的通話會顯示於[通話記錄](/api-reference/calls)，並按其他即時通話的方式收費（[定價](/yue/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](/yue/guides/use-with-pipecat)。
</Note>
