---
title: "Use o ThunderPhone com o Pipecat"
description: "Execute um agente de voz do ThunderPhone como o serviço de fala para fala em um pipeline do Pipecat, com seu próprio transporte e telefonia."
---

[Pipecat](https://github.com/pipecat-ai/pipecat) é um framework de código aberto
para criar agentes de voz a partir de serviços componíveis. O ThunderPhone se integra como
um **serviço de LLM de fala para fala**: o Pipecat envia o áudio de quem liga, o ThunderPhone
retorna a voz do agente, transcrições e chamadas de função, e o transporte do Pipecat
(Daily, LiveKit, Twilio, WebRTC, um microfone local) transmite 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 pipecat-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key
```

O pacote encapsula o serviço OpenAI Realtime do Pipecat, porque o
[Realtime WebSocket](/api-reference/realtime) do ThunderPhone usa o mesmo protocolo. Ele
requer `pipecat-ai` 1.8 ou mais recente.

## Executar um agente salvo

Tudo o que o agente faz (prompt, voz, mecanismo, idiomas, ferramentas, saudação,
verificações durante o silêncio) é configurado no ThunderPhone. O pipeline apenas transmite á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 que
você implanta no ThunderPhone se aplicam à próxima chamada sem alterar seu pipeline.

```python
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.worker import PipelineParams, PipelineWorker
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat_thunderphone import ThunderPhoneRealtimeLLMService

llm = ThunderPhoneRealtimeLLMService(agent_id=12)

context = LLMContext()
aggregators = LLMContextAggregatorPair(context)
pipeline = Pipeline([
    transport.input(),
    aggregators.user(),
    llm,
    aggregators.assistant(),
    transport.output(),
])
worker = PipelineWorker(pipeline, params=PipelineParams(allow_interruptions=True))
```

Um agente salvo inicia a chamada conforme sua própria programação, então o serviço não
solicita uma resposta inicial do Pipecat. Passe `greet_on_connect=True` se ainda
quiser uma.

## Configurar a sessão em linha

Sem `agent_id`, as instruções e ferramentas vêm do contexto do Pipecat, da
mesma forma que no OpenAI. `product` seleciona o mecanismo e `voice` seleciona a
voz do ThunderPhone.

```python
from pipecat.adapters.schemas.function_schema import FunctionSchema
from pipecat.adapters.schemas.tools_schema import ToolsSchema
from pipecat.services.llm_service import FunctionCallParams

llm = ThunderPhoneRealtimeLLMService(product="bolt", voice="olivia", language="es")

async def check_availability(params: FunctionCallParams):
    slots = await calendar.free_slots(params.arguments["date"])
    await params.result_callback({"slots": slots})

llm.register_function("check_availability", check_availability)

context = LLMContext(
    messages=[{"role": "system", "content": "You are Acme Dental's receptionist."}],
    tools=ToolsSchema(standard_tools=[
        FunctionSchema(
            name="check_availability",
            description="Free appointment slots on a date",
            properties={"date": {"type": "string"}},
            required=["date"],
        )
    ]),
)
```

As sessões em linha são conduzidas pelo cliente: o agente fala primeiro porque o Pipecat
solicita uma resposta quando o contexto chega e permanece em silêncio durante períodos de silêncio,
a menos que você adicione uma mensagem ou solicite outra resposta.

## Opções

| Argumento | Significado |
|---|---|
| `api_key` | Chave secreta (`sk_live_...`). O padrão é `THUNDERPHONE_API_KEY`. |
| `agent_id` | Execute um agente salvo. Mutuamente exclusivo com `product` e `voice`. |
| `product` | Mecanismo para sessões inline: `bolt` (os antigos `spark` e `storm` ainda são aceitos). |
| `voice` | Nome da voz do ThunderPhone para sessões inline. |
| `language` | Indicação do idioma principal para sessões inline, por exemplo, `es`. |
| `from_number`, `to_number` | Números a registrar na chamada quando o pipeline fica à frente de uma linha telefônica. |
| `live_transcripts` | Transmita fragmentos da transcrição de quem liga durante a fala (cobrança adicional). |
| `greet_on_connect` | Solicite uma primeira resposta assim que a sessão estiver pronta. |
| `end_task_on_call_ended` | Envie `EndWorkerFrame` quando o ThunderPhone encerrar a chamada (ativado por padrão). |

## Eventos

O ThunderPhone adiciona eventos da plataforma ao protocolo em tempo real. O serviço
os entrega aos handlers:

```python
@llm.event_handler("on_call_ended")
async def on_call_ended(service, event):
    print("call ended:", event["reason"], "call id:", service.call_id)
```

`service.call_id` é definido quando a sessão entra em operação. 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.

## Limites

- A detecção de turnos ocorre no servidor e está sempre ativada; turnos controlados pelo Pipecat
  (`turn_detection=False`) não são compatíveis.
- Funções registradas no serviço são executadas apenas em sessões inline. Um agente
  salvo executa suas próprias ferramentas no ThunderPhone.
- O áudio é PCM mono de 16 bits a 24 kHz em ambas as direções.
- Quadros de vídeo são ignorados.

<Note>
Está criando com LiveKit Agents? Consulte
[Use o ThunderPhone com LiveKit Agents](/pt/guides/use-with-livekit).
</Note>
