Como criar um agente de voz outbound com a Twilio e a Deepgram

Como criar um agente de voz outbound com a Twilio e a Deepgram

Criar um agente de voz para chamadas outbound com a Twilio significa resolver problemas que não existem em um agente de voz para chamadas inbound. Você precisa iniciar a chamada, detectar se ela foi atendida por uma pessoa ou pelo correio de voz, fornecer contexto para que o agente saiba com quem está falando e por quê, e registrar o resultado no seu sistema de registro quando a chamada terminar.

Minha equipe na Deepgram enviou uma implementação de referência para agentes de voz de telefonia outbound na Twilio que lida com tudo isso. Seu sistema aciona uma chamada por meio de uma API REST, um agente de IA executa uma conversa com script com o destinatário e um resultado estruturado da chamada é inserido no CRM após a conclusão. O correio de voz recebe uma mensagem personalizada.

Veja a arquitetura e os problemas que ela resolve, geralmente ignorados por implementações mais simples.

Como funciona a arquitetura do agente de voz outbound

Se você leu a publicação complementar sobre agentes de voz inbound, a estrutura básica de comunicação de áudio aqui é a mesma: um aplicativo Python criado no Starlette com uma classe VoiceAgentSession que contém duas conexões WebSocket (uma para Twilio, uma para API Voice Agent da Deepgram) e transfere áudio entre elas. A API Voice Agent da Deepgram combina conversão de fala em texto, raciocínio LLM e conversão de texto em fala em um loop em tempo real. Você envia o áudio e recebe o áudio de volta, sem precisar integrar serviços separados.

O Flux, modelo de conversão de fala em texto da Deepgram para agentes de voz, gerencia nativamente a alternância de turnos, permitindo que o agente saiba quando o interlocutor termina de falar. A entrada na chamada para acompanhamento (barge-in do autor da chamada) é conectada ao evento clear da Twilio, permitindo que o autor da chamada intervenha a qualquer momento.

O que diferencia esse processo do fluxo de chamadas recebidas (inbound) é tudo o que acontece antes de a conexão de áudio ser estabelecida.

O cenário de exemplo é o acompanhamento de um potencial cliente interessado em um seguro residencial. Um cliente envia uma solicitação de cotação pelo seu site. Mais tarde, seu sistema aciona uma chamada outbound para verificar seus detalhes, reunir mais alguns pontos de dados (como a idade do telhado e o histórico recente de sinistros) e agendar uma consulta com um corretor de seguros habilitado. Se a chamada for para o correio de voz, o corretor deixará uma mensagem personalizada.

Para iniciar essa chamada, um sistema externo (como seu CRM, um script CLI ou um webhook) faz uma requisição ao endpoint POST /make-call do servidor, enviando o número de telefone do destinatário e as informações contextuais do potencial cliente:

A partir daí, o servidor assume o processo: chama a API REST da Twilio com um TwiML incorporado que contém um <Connect><Stream> apontando para o próprio WebSocket. A Twilio liga para o destinatário e, assim que a chamada é atendida, a ponte VoiceAgentSession assume o controle. É um padrão que os clientes da Twilio sempre criam: Voz outbound acionada por CRM com dados estruturados fluindo de volta para o sistema de registro.

Reconhecimento de mensagem eletrônica, integração de CRM e outros aspectos de chamadas outbound

Reconhecimento de mensagem eletrônica (AMD) com a API assíncrona da Twilio. Quando a chamada é atendida, o servidor não sabe se quem atendeu foi uma pessoa ou um correio de voz. Ele armazena temporariamente o áudio recebido enquanto o reconhecimento de mensagem eletrônica assíncrono da Twilio é executado (cerca de 2 a 4 segundos). Quando o resultado é enviado ao /amd-result por meio de uma requisição POST, a sessão se ramifica:

• Pessoa detectada: conecte-se à API Voice Agent da Deepgram, envie todo o áudio armazenado temporariamente e inicie a conversa.
• Correio de voz detectado: entregue uma mensagem personalizada usando o modelo de conversão de texto para fala Aura-2 da Deepgram e desligue.

O repositório também lida com a detecção tardia. Se o AMD identificar um correio de voz depois que o agente já tiver começado a falar, acreditando estar falando com uma pessoa, a sessão encerra a conexão com o Deepgram durante a chamada e alterna para a entrega do correio de voz. Esse tipo de cenário só aparece em operações de chamadas outbound em larga escala, e essa situação já está tratada aqui.

Injeção de contexto de leads no prompt do agente de voz. O prompt do sistema do agente é criado dinamicamente a partir dos dados de lead na solicitação POST /make-call. O agente sabe o nome do destinatário, os detalhes da propriedade e o que ele solicitou antes do início da conversa. É isso que permite que a frase de abertura seja "Estou entrando em contato para dar continuidade à cotação do seu seguro residencial para o endereço 742 Evergreen Terrace", em vez de "Olá, esta é uma chamada automatizada".

Resultados estruturados de chamadas publicados de volta no CRM. Esse é o detalhe que transforma um agente de voz de uma demonstração em um fluxo de trabalho. A API Voice Agent da Deepgram é compatível com chamadas de função, o que significa que o LLM que alimenta o agente pode acionar ações específicas durante a conversa (verificação da disponibilidade de agendamento, reserva de um horário etc.). Uma função update_lead é executada no final de cada chamada, capturando disposição, informações verificadas, novas informações coletadas e um resumo em linguagem natural como JSON estruturado. Na implementação de referência, esses dados são registrados no console. Em produção, seriam enviados por uma requisição POST ao seu CRM, webhook ou banco de dados. O LLM determina quando a chamada foi concluída e quais informações devem ser relatadas, enquanto o servidor encaminha esses dados para o seu back-end.

Monitoramento de silêncio com o InjectAgentMessage da Deepgram. Um monitor de silêncio rastreia se o destinatário está respondendo. Após um período prolongado de silêncio na chamada, o agente pergunta ao autor da chamada: “Você ainda está na linha?” usando a API InjectAgentMessage da Deepgram. Este é um comando do lado do servidor que diz ao agente de voz para falar uma frase específica fornecida por você, em vez de fazer com que o LLM gere algo por conta própria. O servidor encerra a chamada após algum tempo, caso continue sem resposta. É um detalhe pequeno, mas faz diferença em operações de chamadas outbound em larga escala, nas quais o tempo de linha ociosa gera custos.

Introdução ao agente de voz outbound

O repositório inclui um assistente de configuração que configura a Twilio e implanta no Fly.io (uma plataforma para executar servidores de aplicativos próximos de seus usuários). Você precisará do Python 3.12+, de uma conta Twilio e de uma chave de API da Deepgram (gratuita, US$ 200 em créditos, sem necessidade de cartão de crédito).

O assistente de configuração orienta você passo a passo na escolha de um número da Twilio, na geração de um segredo de autenticação para o endpoint /make-call e na implantação da aplicação na Fly.io. Quando estiver pronto, acione uma chamada de teste:

Seu telefone toca. O agente de voz conduz a conversa de acompanhamento do lead de seguros. Consulte os logs do servidor para ver a transcrição completa da chamada e o JSON estruturado com o resultado do contato.

Faça um fork, remova o cenário de seguros e adicione seus próprios prompts, funções e integração com o CRM. Licenciado pelo MIT.

Se você estiver procurando a contraparte inbound, onde o autor da chamada disca seu número e conversa com um recepcionista de IA, consulte Como criar um agente de voz para chamadas inbound com Twilio e Deepgram.