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 do agente, transcrições e chamadas de função, e a sala do LiveKit, os troncos SIP e a telefonia transportam o áudio. Reconhecimento de fala, o modelo de linguagem, a voz, a alternância de turnos, 47 idiomas e as ferramentas são todos executados no ThunderPhone.

As chamadas feitas dessa forma aparecem no histórico de chamadas e são cobradas pela tarifa por minuto do seu produto, como qualquer outra chamada em tempo real. 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

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 durante o silêncio) é configurado no ThunderPhone. A sessão apenas transfere áudio.

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 ferramentas vêm do Agent do LiveKit, da mesma forma que para o OpenAI. product 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(product="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#

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.