Compartilhar:
Autores
){kind=small}
){kind=small}
Integre o Deepgram ao Vonage AI Studio para reconhecimento de fala
Tempo de leitura: 11 minutos
Este artigo foi atualizado em julho de 2025
O Reconhecimento Automático de Fala (ASR) é um componente essencial das aplicações modernas controladas por voz, permitindo que as máquinas convertam a linguagem falada em texto para processamento e interação. O ASR desempenha um papel fundamental em centrais de atendimento, assistentes virtuais e outros serviços habilitados para voz, facilitando a comunicação em tempo real entre usuários e agentes de IA. Embora o Vonage AI Studio ofereça uma solução de ASR integrada, há cenários em que o uso de um motor de ASR personalizado possa ser preferível. O ASR personalizado pode ser adaptado a jargões específicos do setor, idiomas ou sotaques regionais que o ASR integrado talvez não consiga lidar com a mesma eficácia.
Além disso, a integração de um mecanismo externo de reconhecimento de fala (ASR), como Deepgram , pode oferecer maior controle sobre a precisão, a velocidade de transcrição e o vocabulário personalizado, proporcionando um maior grau de flexibilidade em aplicações especializadas.
Este artigo utilizará o Deepgram, um provedor de serviços de reconhecimento de fala (ASR). Utilizaremos o Conector ASR fornecido para integrar o agente de IA de exemplo ou o seu próprio agente de IA ao mecanismo ASR da Deepgram. Como o ASR Connector gerencia a parte de telefonia, utilizaremos um agente de IA do tipo HTTP em vez de um do tipo Telefonia. O agente de IA e o ASR Connector se comunicam via HTTP.
Resumo: Você pode encontrar a integração no GitHub
Todos os links e as versões correspondentes dos pré-requisitos estão disponíveis no repositório de código:
Um account da API da Vonage
> Observação: Se você estiver usando o Deepgram Node SDK diretamente, certifique-se de usar a versão 3.x ou superior, que é a versão mais recente compatível em julho de 2025. Este tutorial utiliza integração direta via WebSocket, que permanece estável e não depende do SDK.
ASR Connector Key Components
Nesse processo, um cliente inicia uma chamada telefônica pela Rede Telefônica Pública Comutada (PSTN), que é processada pelo Conector ASR. O ASR Connector faz a ponte entre a chamada Voice do cliente (PSTN 1) e uma conexão WebSocket, permitindo que o sistema processe a chamada em tempo real. O áudio do cliente é transmitido por meio desse WebSocket para o Mecanismo ASR, que transcreve as palavras faladas em texto. Essa transcrição é então encaminhada pelo ASR Connector para o AI Studio Agent.
Assim que o Agente do AI Studio recebe o texto transcrito, ele processa a entrada do cliente e gera uma resposta adequada. Essa resposta é enviada de volta ao ASR Connector, onde é convertida em Text-to-Speech (TTS) e reproduzida para o cliente. Ao longo da interação, a IA escuta e responde continuamente ao cliente, conduzindo a conversa. A qualquer momento, se a IA determinar que é necessária mais assistência, o sistema pode transferir a chamada para um atendente humano (PSTN 2), sinalizando que a sessão com a IA chegou ao fim.
Essa configuração garante uma comunicação contínua entre o cliente e a IA por meio do reconhecimento e da resposta de voz automatizados. O Conector ASR atua como intermediário, gerenciando tanto a transcrição quanto a interação com a IA, enquanto o Mecanismo ASR permite o processamento em tempo real das palavras faladas. O sistema foi projetado para lidar com chamadas de forma eficiente, mas pode encaminhar a chamada para um atendente humano caso seja necessária uma interação mais complexa.
O Conector ASR é um único programa executável que gerencia o fluxo de chamadas de voz entre um cliente, o mecanismo ASR e o Agente de IA. Embora o programa possa funcionar como um único arquivo de código, ele é conceitualmente dividido em duas partes para simplificar a compreensão e a implantação. A Parte 2 gerencia as chamadas telefônicas (PSTN 1 e PSTN 2) e a interação com o Agente de IA, enquanto a Parte 1 cuida do processamento de áudio, retransmitindo o áudio do cliente para o mecanismo ASR e retornando as transcrições à Parte 2. Essa divisão facilita a compreensão do fluxo e também pode ser implementada em servidores separados, se necessário.
Quando uma chamada é iniciada (seja recebida ou efetuada), Parte 2 estabelece uma sessão com o Agente de IA e usa um WebSocket para transmitir o áudio do cliente para Parte 1. Esse áudio é então encaminhado ao mecanismo de ASR para transcrição. O mecanismo de ASR retorna o texto transcrito à Parte 2, que o envia ao Agente de IA como parte de uma “etapa” de IA. O Agente de IA processa essa transcrição e retorna uma resposta, que é reproduzida para o cliente por meio da conversão de texto em fala (TTS) pelo canal PSTN 1.
A interação continua dessa forma, com cada transcrição sendo enviada como uma etapa da IA e as respostas sendo reproduzidas para o cliente. Se o agente de IA determinar que o cliente precisa ser transferido para um agente humano, ele envia uma solicitação para Parte 2 para encerrar a sessão de IA e iniciar a transferência. A Parte 2, então, conecta o cliente (PSTN 1) ao agente humano (PSTN 2), encerrando a conexão WebSocket e a sessão de ASR. A partir desse ponto, o áudio flui diretamente entre o cliente e o agente humano, concluindo a transferência.
ASR Connector Overview
A amostra do AI Studio Agent opera nos modos de chamadas recebidas e efetuadas, e a direção é determinada pelo Conector ASR, que inicia o fluxo do Agente de IA. A principal função do agente é solicitar que o usuário informe seu nome e, em seguida, colocá-lo em um loop, no qual ele pode ouvir uma piada ou ser transferido para um agente humano. Quando a sessão do agente é inicializada, ela recebe parâmetros-chave, como a direção da chamada, um ID de chamada exclusivo (UUID) e um endereço de webhook para lidar com as transferências de chamadas.
O agente começa verificando o parâmetro de direção e cumprimenta o usuário de acordo com isso. Em seguida, ele solicita que o usuário digite seu nome por meio de um nó “Collect Input”, que armazena a resposta. Toda a comunicação entre o agente de IA e o usuário passa pelo Conector ASR, que atua como intermediário na transmissão de mensagens e entradas do usuário entre os dois. O Agente de IA não interage diretamente com o usuário, mas sim por meio de chamadas de API, nas quais o Conector ASR informa ao Agente de IA as entradas do usuário e aguarda a resposta do agente.
O agente continua perguntando se o usuário deseja ouvir uma piada ou ser transferido para um agente humano. Para reproduzir as piadas, o agente aciona um Webhook que busca piadas em um site externo (como uma API de “Piadas de Pai”) e, em seguida, lê a piada para o usuário por meio de um nó “Enviar mensagem”. O usuário é solicitado novamente a decidir se deseja ouvir outra piada ou ser transferido. Com base na resposta do usuário, uma nó de Classificação determina se o usuário quer outra piada ou se deseja falar com um atendente ao vivo.
Quando o usuário opta por ser transferido para um atendente ao vivo, o atendente utiliza outro Webhook para notificar o aplicativo que controla a parte de telefonia. O webhook transmite informações essenciais, como um anúncio para o usuário, o UUID para identificar a chamada de forma exclusiva e o número de telefone do agente humano. Assim que esse webhook é acionado, o agente conclui sua tarefa, e o fluxo é encerrado à medida que a chamada é transferida para o agente humano.
Crie um projeto no Deepgram e obtenha sua chave de API do Deepgram
Crie um túnel ngrok para escutar na porta 8000
Anote a URL do endpoint do ngrok, pois ela será necessária nas próximas seções. Essa URL tem o seguinte formato: https://yyyyyyyy.ngrok.io
Para obter mais ajuda, consulte testes com o ngrok
Faça login no seu Painel do Desenvolvedor da Vonage e crie um novo aplicativo e faça o seguinte:
Ativar recursos de voz
Você encontrará essa opção na seção “Recursos” ou clique em “Editar” caso não a veja.
Em “URL da resposta”, mantenha HTTP GET e digite https://yyyyyyyy.ngrok.io/answer (substitua <HOST> e <PORT> pelo nome de host público e, se necessário, pela porta pública do servidor onde este aplicativo de exemplo está sendo executado)
Em “URL do evento”, selecione HTTP POST e insira https://yyyyyyyy.ngrok.io/event (substitua <HOST> e <PORT> pelo nome de host público e, se necessário, pela porta pública do servidor onde este aplicativo de exemplo está em execução)
Anote a região do seu pedido
Clique em “Gerar chave pública e privada”
Salve o arquivo da chave privada nesta pasta do aplicativo como .private.key
IMPORTANTE: Não se esqueça de clicar em [Salvar alterações] na parte inferior da tela caso tenha criado um novo conjunto de chaves.
Associe um número de telefone a este aplicativo, caso ainda não haja nenhum associado a ele.
Anote alguns valores dos quais você precisará mais adiante neste tutorial:
Sua chave de API da conta Vonage chave de API do Account da sua conta Vonage, doravante denominada variável de ambiente API_KEY
Sua API da Vonage segredo da API do Account Vonage, doravante denominada variável de ambiente API_SECRET
O ID do seu aplicativo, doravante denominado APP_ID
A região selecionada por você, doravante denominada variável de ambiente API_REGION
O número de telefone vinculado à sua inscrição, doravante denominado variável de ambiente SERVICE_PHONE_NUMBER
Acesse o Painel do AI Studio
Importar o agente de IA de exemplo BlogAgent.zip do repositório do GitHub
Você pode alterar o Nome do agente
Clique em [Importar agente].
Abra seu novo agente
Configurar o número de telefone do Live Agent
Vá para Propriedades (ícones da coluna à esquerda) > Parâmetros > Parâmetros personalizados > callee
Altere o valor para o número do destinatário desejado
deve ser um número de telefone no formato E.164, sem o sinal “+” no início
Clique em “Fechar”
Anote mais alguns valores de que você precisará mais adiante neste tutorial:
Seu ID de agente, doravante denominado variável de ambiente AGENT_ID
Sua Vonage chave de API de IA chave de API, doravante denominada variável de ambiente X_VGAI_KEY
Não confunda sua chave da API de IA da Vonage (X-Vgai-Key) com a chave da API da sua conta da Vonage
O Vonage AI Studio agora oferece suporte a recursos avançados, como webhooks de eventos em tempo real (`onSpeechEnd`,
onStepComplete), seleção personalizada de voz para conversão de texto em fala e o modo sussurro. Você pode explorar esses recursos nas guias “Eventos” e “Configurações de Voice” no criador de agentes.
Copie ou renomeie o arquivo .env-example para .env
Atualize todos os parâmetros no arquivo .env de acordo com o conteúdo das seções anteriores. O valor da variável de ambiente VG_AI_HOST deve ser consistente com o valor da variável de ambiente API_REGION.
Instale os módulos do Node com o comando: npm install
Inicie o aplicativo em uma aba do terminal diferente daquela em que está o túnel do ngrok: node asr-connector
O aplicativo é executado, por padrão, na porta 8000. Lembre-se de manter seu túnel ngrok rodando na mesma porta que o aplicativo.
Essa configuração é ótima para testes, mas não deve ser usada em produção sem que o ASR Connector seja protegido. Em ambientes de produção, use sempre HTTPS, valide as solicitações recebidas com tokens assinados e restrinja intervalos de IP ou cabeçalhos de autenticação para proteger dados confidenciais de áudio e transcrição.
Seja a primeira chamada efetuada ou recebida, será solicitado ao usuário (por exemplo, o cliente) que diga seu nome; em seguida, serão reproduzidas algumas piadas em vez da música de espera, até que o usuário diga “não” para interromper as piadas; após isso, a chamada será transferida para o outro usuário (por exemplo, Agente ao Vivo), cujo número de telefone é aquele que foi definido durante a implantação do Agente de IA.
Você pode iniciar a chamada de saída abrindo o seguinte endereço da web com sua URL do ngrok: https://yyyyyyyy.ngrok.io/startcall?callee=12995551515
Ligue para o número de telefone vinculado à sua conta da API da Vonage.
Neste tutorial, você aprendeu como ampliar o Vonage AI Studio para integrá-lo a um mecanismo ASR alternativo, utilizando um Agente de IA do tipo HTTP e o aplicativo de servidor ASR Connector, que lida com a parte de telefonia (por meio da Voice API) e gerencia a conexão com o mecanismo ASR.
Essa integração lida com eficiência com chamadas do tipo PSTN, mas também pode ser ampliada para oferecer suporte a canais de comunicação adicionais. Uma possível melhoria é expandir essa configuração para chamadas SIP, o que permitiria aproveitar a telefonia baseada em IP, proporcionando ainda mais flexibilidade para empresas que utilizam redes privadas. Além disso, seria possível adaptar a integração para funcionar com clientes WebRTC, possibilitando a comunicação em tempo real diretamente por meio de navegadores da web, tornando-a uma solução adequada para atendimento ao cliente em sites sem a necessidade de serviços de telefonia tradicionais.
Você também pode considerar substituir o mecanismo padrão de conversão de texto em fala do AI Studio por um provedor terceirizado, como o Eleven Labs ou o Google Cloud TTS, utilizando webhooks para controlar a experiência de voz com maior precisão. Os metadados de transcrição em tempo real do Deepgram também podem ser usados para acionar eventos em sistemas externos; isso é útil para registro, análise ou lógica de escalonamento.
Se você tiver dúvidas, participe da nossa Comunidade no Slack ou envie uma mensagem para nós no X.
Tenho uma enorme dívida de gratidão para com Mark Berkeland, cuja ajuda inestimável e brilhantismo impressionante transformaram este blog, que de outra forma seria apenas mais um blog comum, em uma obra de arte técnica de nível mundial.