ThunderPhone v3 já está no ar.Contrate online, a partir de 2¢/min.Leia o anúncio

Connect tools & data

Use o ThunderPhone a partir do LiveKit Agents

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 é 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 e são cobradas como qualquer outra chamada em tempo real (preços). Não há assinatura nem número de telefone do ThunderPhone envolvido.

Instalar

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 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.

O plugin encapsula o modelo OpenAI Realtime do LiveKit, porque o WebSocket 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.

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.

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

ArgumentoSignificado
api_keyChave secreta (sk_live_...). O padrão é THUNDERPHONE_API_KEY.
agent_idExecuta um agente salvo. Mutuamente exclusivo com model e voice.
modelMecanismo para sessões em linha: bolt (os mais antigos spark e storm ainda são aceitos).
voiceNome da voz do ThunderPhone para sessões em linha.
languageDica de idioma principal para sessões em linha, por exemplo, es.
caller_number, callee_numberNú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_transcriptsTransmite fragmentos da transcrição de quem liga durante a fala (cobrado à parte).
base_urlSubstituiçã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:

@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} 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.