Crie um Agente de Voz em Tempo Real do Gemini

Introdução

O exemplo geminivoiceagent.cs conecta uma chamada recebida no 3CX ao Google Gemini Live. O agente pode cumprimentar os chamadores, usar objetos de diretório autorizados, encaminhar chamadas, oferecer correio de voz ou chat e, quando configurado, salvar contexto útil do chamador.

O script inclui uma ferramenta personalizada get_department_hours desativada, que demonstra como registrar uma função segura que pode ser chamada pela IA.

Este script requer uma licença da Edição 3CX IA, uma versão do PABX com o Update 10 e uma conta da API Gemini.

Crie o Script de Chamada no 3CX

• Faça login no Console de Admin 3CX.
• Acesse Integrações > Scripts de Chamada.
• Selecione +Adicionar da Loja.

• Escolha o arquivo geminivoiceagent.cs.

• Digite um nome em letras minúsculas, sem espaços; por exemplo, geminireception.
• Selecione como o script será executado e atribua o DID, a rota de tronco ou o destino interno necessários.
• Selecione o departamento responsável.
• Passe para o editor de código.

Configure o Gemini e o Script

Adicione os seguintes parâmetros protegidos ao PABX:

• GEMINI_API_KEY — a chave de API do seu projeto de IA do Google.
• GEMINI_REALTIME_MODEL — o modelo Gemini em Tempo Real.

Deixe ApiKeyOverride e ModelOverride em branco no script. Quando esses valores estão em branco, o script lê automaticamente a chave da API e o modelo a partir dos parâmetros do PABX.

Não insira a chave da API do Gemini diretamente no script, especialmente se o script for compartilhado, exportado ou publicado. Um valor configurado em ApiKeyOverride ou ModelOverride tem precedência sobre o parâmetro correspondente do PABX.

Em seguida, verifique essas configurações do cliente na parte superior do script:

Defina AllowAllVisibilityForTesting como false antes da entrada em produção e configure a menor lista de visibilidade viável.

Para habilitar a função opcional “example”, verifique seus dados e remova o comentário:

RegisterExampleCustomTool();



Selecione “Salvar” e verifique se a compilação foi bem-sucedida.

Como Funciona

1. Uma chamada recebida é encaminhada ao ponto de encaminhamento do script.
2. O script limpa e reconfigura a visibilidade permitida do diretório 3CX no Gemini.
3. O 3CX prepara o canal de mídia.
4. O script inicia a sessão de voz do Gemini Live com as instruções, a voz, o nome do agente, a chave de API e o modelo configurados.
5. As ferramentas aprovadas realizam ações relacionadas a diretórios, transferências, correio de voz, chat e contexto.
6. As falhas são encaminhadas para o plano de contingência configurado e, caso o encaminhamento não esteja disponível, é exibido o prompt ERROR.

Teste o Script

• Verifique o comportamento da voz do Gemini selecionado e o comportamento em relação ao idioma do chamador.
• Pesquise objetos de diretório permitidos.
• Verifique se os destinos ocultos não podem ser selecionados.
• Teste a confirmação de transferência, o correio de voz e o chat.
• Experimente uma despedida natural.
• Simule uma falha do provedor e confirme o roteamento alternativo.

Solução de Problemas

• Falha na sessão do Gemini: Verifique a chave da API do Gemini, o modelo live compatível, a licença, a versão do PABX e a conectividade de saída.
• Uma voz foi rejeitada: use uma voz compatível com o modelo Gemini configurado.
• Faltam resultados no diretório: verifique a visibilidade do número, do departamento e da função.
• Há muitos objetos expostos: desative o AddAll().
• Falha no fallback ou no prompt: Verifique o destino e o prompt ERROR ativo.

Veja Também

• Crie um Script de Processamento de Chamadas
• Exemplo de Script de Processamento de Chamadas para PIN
• Manual de Administração do 3CX

Última Atualização

Este guia foi atualizado pela última vez em 30 de julho de 2026

https://www.3cx.com.br/docs/gemini-voice-agent/