---
title: "Использование ThunderPhone в LiveKit Agents"
description: "Запускайте голосового агента ThunderPhone как модель реального времени (речь-в-речь) в сеансе LiveKit Agents, используя комнаты LiveKit, SIP и телефонию."
---

[LiveKit Agents](https://github.com/livekit/agents) — это фреймворк с открытым исходным кодом
для голосовых агентов реального времени поверх комнат LiveKit. ThunderPhone подключается как
**модель реального времени**: фреймворк отправляет аудио участника, ThunderPhone
возвращает голос агента, расшифровку и вызовы функций, а комната LiveKit,
SIP-транки и телефония передают аудио. Распознавание речи, языковая
модель, голос, управление очередностью реплик, 62 языка и инструменты — всё работает на ThunderPhone.

Звонки, совершённые таким способом, отображаются в [истории звонков](/api-reference/calls) и тарифицируются как любые другие звонки в реальном времени ([тарифы](/ru/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/).

Плагин оборачивает модель OpenAI Realtime из LiveKit, поскольку
[Realtime WebSocket](/api-reference/realtime) ThunderPhone использует тот же протокол. Для него требуется `livekit-agents` версии 1.8 или новее.

## Запустите сохранённого агента

Всё, что делает агент (промпт, голос, движок, языки, инструменты, приветствие,
проверки тишины), настраивается в ThunderPhone. Сессия только передаёт аудио.
Создайте агента в панели управления или поручите это Zeus (ИИ-агенту, который создаёт, тестирует
и настраивает агентов ThunderPhone), затем передайте сюда его 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; инструкции и инструменты `Agent` из LiveKit не отправляются. Звонок завершается, когда агент ThunderPhone кладёт трубку, и вместе с ним закрывается сеанс.

## Настройте сеанс прямо в коде

Без `agent_id` инструкции и инструменты берутся из LiveKit `Agent`, так же, как для OpenAI. `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`.

## Ограничения

- Определение завершения реплики выполняется на стороне сервера и всегда включено; определение завершения реплики на стороне фреймворка
  (`turn_detection` в `AgentSession`) игнорируется.
- Инструкции и инструменты нельзя изменить после начала вызова.
- Аудио — 16-битный моно PCM с частотой 24 кГц в обоих направлениях.
- Видеокадры игнорируются.

<Note>
Используете Pipecat? См. [Использование ThunderPhone из Pipecat](/ru/guides/use-with-pipecat).
</Note>
