---
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) и се таксуват като всяко друго обаждане в реално време ([цени](/bg/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 (AI агентът, който създава, тества и настройва 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;
инструкциите и инструментите на LiveKit `Agent` не се изпращат. Обаждането приключва, когато
агентът на 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 kHz в двете посоки.
- Видеокадрите се игнорират.

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