---
title: "LiveKit Agents から ThunderPhone を使用する"
description: "LiveKit ルーム、SIP、電話機能と組み合わせて、LiveKit Agents セッションのリアルタイム（音声対音声）モデルとして ThunderPhone 音声エージェントを実行します。"
---

[LiveKit Agents](https://github.com/livekit/agents) は、LiveKit ルーム上でリアルタイム音声エージェントを構築するためのオープンソースフレームワークです。ThunderPhone は**リアルタイムモデル**として統合されます。フレームワークが参加者の音声を送信し、ThunderPhone がエージェントの音声、文字起こし、関数呼び出しを返します。LiveKit のルーム、SIP トランク、電話機能が音声を伝送します。音声認識、言語モデル、音声、ターンテイキング、62 言語、ツールはすべて ThunderPhone 上で動作します。

この方法で行われた通話は[通話履歴](/api-reference/calls)に表示され、他のリアルタイム通話と同様に課金されます（[料金](/ja/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/)で説明されています。

このプラグインは、ThunderPhone の
[Realtime WebSocket](/api-reference/realtime) が同じプロトコルを使用するため、LiveKit の OpenAI Realtime モデルをラップします。
`livekit-agents` 1.8 以降が必要です。

## 保存済みエージェントを実行する

エージェントが行うすべての処理（プロンプト、音声、エンジン、言語、ツール、挨拶、無音時のチェックイン）はThunderPhoneで設定します。セッションは音声のみを転送します。ダッシュボードでエージェントを構築するか、ThunderPhoneエージェントを構築、テスト、調整するAIエージェントであるZeusに設定させてから、その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を使用する](/ja/guides/use-with-pipecat)を参照してください。
</Note>
