---
title: "Use o ThunderPhone a partir do LiveKit Agents"
description: "Execute um agente de voz do ThunderPhone como o modelo em tempo real (fala para fala) de uma sessão do LiveKit Agents, com salas do LiveKit, SIP e telefonia ao redor dele."
---

[LiveKit Agents](https://github.com/livekit/agents) é um framework de código aberto
para agentes de voz em tempo real sobre salas do LiveKit. O ThunderPhone se integra como o
**modelo em tempo real**: o framework envia o áudio do participante, o ThunderPhone
retorna a voz, as transcrições e as chamadas de função do agente, e a sala, os
troncos SIP e a telefonia do LiveKit transportam o áudio. O reconhecimento de fala, o modelo
de linguagem, a voz, a alternância de turnos, 62 idiomas e as ferramentas são executados no ThunderPhone.

As chamadas feitas dessa forma aparecem no [histórico de chamadas](/api-reference/calls) e são
cobradas como qualquer outra chamada em tempo real ([preços](/pt/guides/pricing)). Não há
assinatura nem número de telefone do ThunderPhone envolvido.

## Instalar

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

Com uv, `uv add "livekit-agents[thunderphone]~=1.8"` instala o mesmo
plugin. Ele está no repositório [livekit/agents](https://github.com/livekit/agents)
e é lançado junto com o próprio `livekit-agents`, portanto mantenha ambos na
mesma versão. O LiveKit o documenta em seu próprio
[guia do plugin ThunderPhone](https://docs.livekit.io/agents/models/realtime/thunderphone/).

O plugin encapsula o modelo OpenAI Realtime do LiveKit, porque o
[WebSocket Realtime](/api-reference/realtime) do ThunderPhone usa o mesmo protocolo. Ele
requer `livekit-agents` 1.8 ou mais recente.

## Executar um agente salvo

Tudo o que o agente faz (prompt, voz, mecanismo, idiomas, ferramentas, saudação,
verificações de silêncio) é configurado no ThunderPhone. A sessão apenas transporta áudio.
Crie o agente no painel ou peça ao Zeus (o agente de IA que cria, testa
e ajusta agentes do ThunderPhone) para configurá-lo e, em seguida, informe o ID dele aqui. As alterações
implantadas no ThunderPhone são aplicadas à próxima chamada sem modificar seu código 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))
```

Um agente salvo cumprimenta quem liga e executa suas próprias ferramentas no ThunderPhone; as
instruções e ferramentas do `Agent` do LiveKit não são enviadas. A chamada termina quando o
agente do ThunderPhone desliga, e a sessão é encerrada com ele.

## Configurar a sessão em linha

Sem `agent_id`, as instruções e as ferramentas vêm do `Agent` do LiveKit, da mesma forma que no OpenAI. `model` seleciona o mecanismo e `voice` seleciona a voz do 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
```

O ThunderPhone congela as instruções e ferramentas quando a chamada começa; portanto,
`update_instructions`, `update_tools` e transferências de agente que as alteram não são
compatíveis durante a chamada. As sessões em linha são controladas pelo cliente: o agente fala
quando você chama `generate_reply()` ou quando o participante termina um turno.

## Opções

| Argumento | Significado |
|---|---|
| `api_key` | Chave secreta (`sk_live_...`). O padrão é `THUNDERPHONE_API_KEY`. |
| `agent_id` | Executa um agente salvo. Mutuamente exclusivo com `model` e `voice`. |
| `model` | Mecanismo para sessões em linha: `bolt` (os mais antigos `spark` e `storm` ainda são aceitos). |
| `voice` | Nome da voz do ThunderPhone para sessões em linha. |
| `language` | Dica de idioma principal para sessões em linha, por exemplo, `es`. |
| `caller_number`, `callee_number` | Números de telefone da chamada quando a sala atende uma linha telefônica. Eles aparecem como os números de origem e destino no histórico de chamadas. |
| `live_transcripts` | Transmite fragmentos da transcrição de quem liga durante a fala (cobrado à parte). |
| `base_url` | Substituição do endpoint; o padrão é `wss://api.thunderphone.com/v1/realtime`. |

## Eventos

O ThunderPhone adiciona eventos da plataforma ao protocolo em tempo real. A sessão
os emite:

```python
@session.llm.session.on("thunderphone_call_ended")  # or on the RealtimeSession you hold
def on_call_ended(event):
    print("call ended:", event["reason"])
```

O `RealtimeSession` expõe `call_id` quando a sessão está ativa. Use-o com
[`GET /v1/calls/{call_id}`](/api-reference/calls) para buscar a gravação,
a transcrição e a avaliação após a chamada. Todos os outros eventos `call.*` (transferência,
teclado, fala ignorada) chegam como `thunderphone_call_event`.

## Limites

- A detecção de turnos é feita no servidor e está sempre ativada; a detecção de turnos
  do framework (`turn_detection` no `AgentSession`) é ignorada.
- Não é possível alterar instruções e ferramentas após o início da chamada.
- O áudio é PCM mono de 16 bits a 24 kHz em ambas as direções.
- Quadros de vídeo são ignorados.

<Note>
Está desenvolvendo com Pipecat? Consulte [Use o ThunderPhone com Pipecat](/pt/guides/use-with-pipecat).
</Note>
