---
title: "Używaj ThunderPhone z LiveKit Agents"
description: "Uruchom agenta głosowego ThunderPhone jako model czasu rzeczywistego (mowa na mowę) w sesji LiveKit Agents, z pokojami LiveKit, SIP i telefonią wokół niego."
---

[LiveKit Agents](https://github.com/livekit/agents) to framework open source
dla agentów głosowych działających w czasie rzeczywistym w pokojach LiveKit. ThunderPhone integruje się jako
**model czasu rzeczywistego**: framework wysyła dźwięk uczestnika, ThunderPhone
zwraca głos agenta, transkrypcje i wywołania funkcji, a pokoje LiveKit,
łącza SIP i telefonia przesyłają dźwięk. Rozpoznawanie mowy, model językowy,
głos, zarządzanie kolejnością wypowiedzi, 62 języki i narzędzia działają w ThunderPhone.

Połączenia wykonywane w ten sposób pojawiają się w [historii połączeń](/api-reference/calls) i są rozliczane jak każde inne połączenie w czasie rzeczywistym ([cennik](/pl/guides/pricing)). Nie wymagają subskrypcji ani numeru telefonu ThunderPhone.

## Instalacja

```bash
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key
```

W przypadku uv polecenie `uv add "livekit-agents[thunderphone]~=1.8"` instaluje tę samą
wtyczkę. Jest ona dostępna w repozytorium [livekit/agents](https://github.com/livekit/agents)
i jest wydawana razem z samym `livekit-agents`, dlatego zachowaj tę samą wersję obu
pakietów. LiveKit dokumentuje ją we własnym
[przewodniku po wtyczce ThunderPhone](https://docs.livekit.io/agents/models/realtime/thunderphone/).

Wtyczka opakowuje model OpenAI Realtime LiveKit, ponieważ [Realtime WebSocket](/api-reference/realtime) ThunderPhone
obsługuje ten sam protokół. Wymaga `livekit-agents` w wersji 1.8 lub nowszej.

## Uruchamianie zapisanego agenta

Wszystko, co robi agent (prompt, głos, silnik, języki, narzędzia, powitanie,
sprawdzanie ciszy), jest konfigurowane w ThunderPhone. Sesja tylko przesyła dźwięk.
Zbuduj agenta w panelu lub zleć jego skonfigurowanie Zeusowi (agentowi AI, który tworzy, testuje
i dostraja agentów ThunderPhone), a następnie przekaż tutaj jego identyfikator. Zmiany
wdrożone w ThunderPhone zostaną zastosowane przy następnym połączeniu bez modyfikowania kodu 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))
```

Zapisany agent wita i uruchamia własne narzędzia w ThunderPhone; instrukcje i narzędzia
`Agent` LiveKit nie są wysyłane. Połączenie kończy się, gdy
agent ThunderPhone się rozłączy, a sesja zamyka się razem z nim.

## Konfigurowanie sesji w kodzie

Bez `agent_id` instrukcje i narzędzia pochodzą z `Agent` LiveKit, tak
samo jak w przypadku OpenAI. `model` wybiera silnik, a `voice` wybiera głos
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 blokuje instrukcje i narzędzia w chwili rozpoczęcia połączenia, dlatego
`update_instructions`, `update_tools` i przekazania agenta, które je zmieniają, nie są
obsługiwane w trakcie połączenia. Sesje w kodzie są sterowane przez klienta: agent mówi,
gdy wywołasz `generate_reply()` lub gdy uczestnik zakończy swoją turę.

## Opcje

| Argument | Znaczenie |
|---|---|
| `api_key` | Tajny klucz (`sk_live_...`). Domyślnie: `THUNDERPHONE_API_KEY`. |
| `agent_id` | Uruchamia zapisanego agenta. Wzajemnie wykluczające się z `model` i `voice`. |
| `model` | Silnik dla sesji wbudowanych: `bolt` (starsze `spark` i `storm` są nadal obsługiwane). |
| `voice` | Nazwa głosu ThunderPhone dla sesji wbudowanych. |
| `language` | Wskazówka dotycząca głównego języka dla sesji wbudowanych, np. `es`. |
| `caller_number`, `callee_number` | Numery telefonów połączenia, gdy pokój obsługuje linię telefoniczną. Pojawiają się jako numery od i do w Historii połączeń. |
| `live_transcripts` | Przesyła fragmenty transkrypcji rozmówcy w trakcie wypowiedzi (dodatkowo płatne). |
| `base_url` | Zastępuje punkt końcowy; domyślnie `wss://api.thunderphone.com/v1/realtime`. |

## Zdarzenia

ThunderPhone dodaje zdarzenia platformy do protokołu czasu rzeczywistego. Sesja
je emituje:

```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` udostępnia `call_id`, gdy sesja jest aktywna. Użyj go z
[`GET /v1/calls/{call_id}`](/api-reference/calls), aby pobrać nagranie,
transkrypcję i ocenę po połączeniu. Każde inne zdarzenie `call.*` (przekazanie,
klawiatura, zignorowana mowa) dociera jako `thunderphone_call_event`.

## Ograniczenia

- Wykrywanie końca wypowiedzi odbywa się po stronie serwera i jest zawsze włączone; wykrywanie końca wypowiedzi po stronie frameworka
  (`turn_detection` w `AgentSession`) jest ignorowane.
- Instrukcje i narzędzia nie mogą zostać zmienione po rozpoczęciu połączenia.
- Dźwięk to 16-bitowy monofoniczny PCM o częstotliwości 24 kHz w obu kierunkach.
- Klatki wideo są ignorowane.

<Note>
Tworzysz rozwiązanie w Pipecat? Zobacz [Używanie ThunderPhone z Pipecat](/pl/guides/use-with-pipecat).
</Note>
