Solução de problemas

Ativar o Cloud Logging para o agente

Ative o Cloud Logging para seu agente. Isso é essencial para capturar dados e diagnosticar problemas em conversas reais.

Coletar IDs de conversa

Quando ocorrer um comportamento inesperado, colete os IDs de conversa do Dialogflow. Esses IDs, encontrados no histórico de conversas, permitem rastrear o caminho de execução de uma conversa e examinar interações específicas.

A chamada de API tem a permissão negada

Problema

Resposta PERMISSION_DENIED recebida na chamada de API.

Solução

Verifique se você configurou corretamente a autenticação e os papéis do (Dialogflow CX, Dialogflow ES). Em particular, verifique se você fez o seguinte:

• Criou uma conta de serviço e não a excluiu acidentalmente.
• Forneceu à conta de serviço um papel que concede permissão para chamar o método escolhido.
• Fez o download do arquivo de chave privada da conta de serviço.
• Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o arquivo de chave privada.

A chamada de API menciona um projeto desconhecido

Problema

Recebido o erro Dialogflow API has not been used in project 32555940559 para a chamada de API.

Solução

Verifique se você fez o seguinte:

• Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS (consulte PERMISSION_DENIED).
• Forneceu o ID do projeto correto para a chamada de API.

A chamada de API recebe um erro de credenciais de autenticação inválidas

Problema

Resposta Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. recebida na chamada de API.

Solução

Isso pode acontecer ao criar credenciais manualmente com a biblioteca de cliente e especificar uma região não padrão. Veja orientações sobre um dos seguintes tópicos:

• Selecionar uma região com a API (Dialogflow CX)
• Selecionar uma região com a API (Dialogflow ES)

A resposta da chamada de API solicita uma troca para um host diferente

Problema

Recebeu a resposta Please switch to 'REGION-dialogflow.googleapis.com' to access resources located in 'REGION' para a chamada de API, em que REGION é um ID da região específico.

Solução

Isso acontece quando você especifica a região na solicitação, mas não o endpoint. Veja orientações sobre um dos seguintes tópicos:

• Selecionar uma região com a API (Dialogflow CX)
• Selecionar uma região com a API (Dialogflow ES)

Campos ausentes na resposta da chamada de API

Problema

Alguns campos estão ausentes na resposta da API.

Solução

Se você espera um valor numérico para um campo específico na resposta da API, o campo pode estar ausente da resposta se o valor retornado for 0.

Para mais informações sobre o comportamento do valor padrão (incluindo valores não numéricos), consulte:

• Buffers de protocolo (Dialogflow CX)
• Buffers de protocolo (Dialogflow ES)

Não é possível excluir o projeto por causa da garantia

Problema

Ao tentar excluir um projeto do Google Cloud , você recebe uma notificação de que o projeto não pode ser excluído porque tem garantias, e uma delas está relacionada ao Dialogflow ES.

Solução

1. Verifique se você não precisa mais do agente do Dialogflow ES associado ao projeto. Se você receber uma notificação de que o agente não existe, isso significa que ele já foi excluído.

   Console do Dialogflow ES

   Abra https://dialogflow.cloud.google.com/#/agent/project-id/intents.

   Esse link é diferente do que aparece na caixa de diálogo de exclusão do projeto do Google Cloud .

   API Dialogflow

   Use o método search do tipo agent.

2. Pegue o nome da garantia.

   gcloud

   Use o comando gcloud alpha resource-manager liens list, conforme descrito na documentação Como listar garantias em um projeto.

   API Explorer

   Use o painel Testar esta API na página Método: liens.list:

   • Preencha o campo parent, conforme sugerido na descrição do parâmetro.
   • Clique em Executar.

3. Exclua a garantia.

   gcloud

   Use o comando gcloud alpha resource-manager liens delete LIEN_NAME, conforme descrito na documentação Como remover garantias de um projeto.

   API Explorer

   Use o painel Testar esta API na página Método: liens.delete:

   • Preencha o campo name com o nome da garantia que você recebeu na etapa 2.
   • Clique em Executar.

4. Encerre o projeto.

O webhook do Dialogflow CX falha com o erro de prazo excedido

Problema

Um webhook chamado pelo Dialogflow CX pode falhar com esta mensagem de erro:

Webhook call failed. Error: DEADLINE_EXCEEDED

Isso pode acontecer porque a chamada de webhook excede o limite de tempo limite do webhook. Estes são os possíveis motivos para a chamada de webhook exceder o limite de tempo:

• Tentativa de acionar uma intent inexistente.
• Um problema de inicialização a frio com o back-end do webhook (por exemplo, Cloud Functions).
• O webhook chama outros serviços, aumentando o tempo de resposta.
• Não há conexão entre o agente e o back-end do webhook (por exemplo, balanceador de carga configurado incorretamente).
• Política da organização que impede a execução de tráfego de entrada ou métodos do Dialogflow.

Alternativa

Por padrão, um webhook tem um limite de tempo limite de 5 segundos. É possível aumentar o limite de tempo limite do webhook ao criar ou editar o recurso de webhook, o que daria mais tempo para o webhook responder.

O console falha ao configurar o projeto

Problema

Recebi o erro Failed to set up GCP project ao criar um agente com o console.

Solução

Talvez você não tenha permissão para criar projetos do Google Cloud . Verifique se é possível criar um projeto do Google Cloud diretamente no console. Se não for possível criar um projeto, siga as recomendações fornecidas na mensagem de erro.

Referência de parâmetro de sessão mostrada na resposta

Problema

As respostas retornadas do Dialogflow incluem as referências de parâmetro, em vez dos valores dos parâmetros. Por exemplo:
Hello, $session.params.customer_name

Os parâmetros não serão resolvidos, e a referência do parâmetro será mostrada se ele não for encontrado na sessão atual ou se não estiver sendo usado de acordo com o tipo.

Solução

Esse problema pode aparecer porque o parâmetro usado não está incluído na conversa, tem um erro de digitação ou tem um tipo diferente do usado.

Falha na criação do agente no console quando a API não foi ativada

Problema

Exibiu o erro Dialogflow API has not been enabled for the project. Code: FAILED_PRECONDITION ao criar um agente com o console.

Solução

Siga as etapas de configuração para ativar a API Dialogflow.

Ao tentar acessar o console pela conta da organização, recebi um erro de serviço

Problema

Recebeu o erro You don't have access to this service ao tentar acessar o console pela conta da organização.

Solução

Entre em contato com o administrador do sistema da sua organização e verifique se as configurações dela dão acesso ao console. Caso contrário, verifique se a conta migrada de outra organização foi sinalizada como restrita pelo Google. É provável que esse seja o problema se outros usuários da sua organização puderem acessar o console, mas você não.

Se preferir, entre em contato com o suporte para receber ajuda.

Não é possível exportar o agente no formato JSON porque o fluxo está ausente

Problema

A exportação do agente como bytes brutos é concluída, mas a exportação do agente no formato JSON falha com uma mensagem de erro semelhante a esta:

Flow 'projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/flows/FLOW_ID' does not exist
in the agent

Esse problema pode ser causado por um caso de teste que faz referência a um fluxo que foi excluído.

Solução

Para resolver esse problema, analise os casos de teste não utilizados para confirmar se o fluxo mencionado na mensagem de erro está sendo usado em algum caso de teste e exclua os casos de teste confirmados.

Conectividade do gateway telefônico

Problema

Ao usar um gateway de telefone, você recebe um sinal de ocupado ou a chamada é encerrada.

Solução

Há cotas e limites para esse recurso. Se você receber um sinal de ocupado ou a chamada cair, talvez tenha excedido sua cota.

Erro RESOURCE_EXHAUSTED ao tentar criar um novo número de telefone

Problema

Ao tentar criar um novo número de telefone no Dialogflow CX, no Dialogflow ES ou no Agent Assist, um erro RESOURCE_EXHAUSTED é retornado.

Solução

Esse erro significa que você excedeu o limite de números de telefone por projeto. Para criar um novo número de telefone, exclua os números não utilizados associados ao seu projeto até que você esteja abaixo do limite.

Se você criou números de telefone no gateway telefônico do Dialogflow CX ou no gateway telefônico do Dialogflow ES, é possível excluí-los no console. A exclusão do agente sem a exclusão do número de telefone não exclui o número de telefone associado a ele.

Como alternativa, é possível usar a API seguindo as etapas abaixo.

Etapa 1: Identifique todos os números de telefone associados ao seu projeto

Para identificar os números de telefone associados ao seu projeto, use o método de API projects.phoneNumbers/list ou projects.locations.phoneNumbers.list para todas as regiões em que você criou números de telefone.

• Para a região global, use o seguinte comando:

  curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth print-access-token) \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/phoneNumbers
  

• Para outras regiões, é necessário especificar a região em dois lugares:

  curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth print-access-token) \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  https://REGION_ID-dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/REGION_ID/phoneNumbers
  

Etapa 2: (Opcional) Identificar agentes associados aos perfis de conversa

Receber o ID do agente de CX do Dialogflow CX associado ao número de telefone pelo perfil de conversa pode ajudar a identificar se o agente ainda está em uso e se o número de telefone ainda é necessário. Para isso, use o método de API projects.conversationProfiles/get. Você encontra os IDs de perfil de conversa nas respostas aos comandos executados na etapa 1.

• Para a região global, use o seguinte comando:

  curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth print-access-token) \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/conversationProfiles/CONVERSATION_PROFILE_ID
  

• Para outras regiões, especifique a região em dois lugares:

  curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth print-access-token) \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  https://REGION_ID-dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/REGION_ID/conversationProfiles/CONVERSATION_PROFILE_ID
  

Encontre o agente pelo ID no console do Dialogflow CX usando a opção Pesquisar na página Ver todos os agentes.

No Dialogflow ES, um projeto pode ser associado a no máximo cinco agentes, e um agente do Dialogflow ES pode ser associado a um número de telefone. Assim, é possível abrir o agente no console do Dialogflow ES em https://dialogflow.cloud.google.com/#/editAgent/PROJECT_ID/intents.

Se nenhum agente for encontrado, você ainda poderá excluir o número de telefone se tiver certeza de que ele não é mais necessário.

Etapa 3: Excluir números de telefone não utilizados

Para excluir números de telefone que não são mais necessários, use o método de API projects.phoneNumbers/delete ou projects.locations.phoneNumbers.delete. Encontre os IDs de número de telefone na resposta aos comandos executados na etapa 1.

• Para a região global, use o seguinte comando:

  curl -X DELETE \
      -H "Authorization: Bearer "$(gcloud auth print-access-token) \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -H "Content-Type: application/json; charset=utf-8" \
      https://dialogflow.googleapis.com/v2beta1/PHONE_NUMBER_ID
  

• Para outras regiões, especifique a região:

  curl -X DELETE \
      -H "Authorization: Bearer "$(gcloud auth print-access-token) \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -H "Content-Type: application/json; charset=utf-8" \
      https://REGION_ID-dialogflow.googleapis.com/v2beta1/PHONE_NUMBER_ID
  

Sem resposta do Dialogflow CX Messenger

Problema

Nenhuma resposta do agente para interações do Dialogflow CX Messenger.

Solução

Se você não receber respostas do Dialogflow CX Messenger, verifique se o faturamento e a API Dialogflow estão ativados no projeto. Veja as instruções de configuração.

O valor de parâmetro correspondeu, mas não é um sinônimo de entidade

Problema

• Caso geral:um valor de parâmetro é extraído no ambiente de execução, mesmo que a entidade correspondente ao parâmetro não contenha o valor correspondente como sinônimo.
• Um caso mais específico:depois que um sinônimo é excluído de uma entidade e o agente é treinado novamente, esse sinônimo ainda é extraído como um valor de parâmetro para essa entidade.

Solução

1. Use a opção pesquisar para verificar se o valor correspondente pode estar presente no agente como uma entidade implícita (Dialogflow CX, Dialogflow ES). Encontre todas as intents que têm anotações com esse parâmetro e entidade.
2. Corrija as anotações garantindo que nenhuma delas seja aplicada ao texto que representa o valor correspondente indesejado.
3. Teste o agente no ambiente de execução para verificar se o problema foi resolvido.
4. Se o problema persistir, verifique se as opções Expansão automática e Correspondência aproximada estão desmarcadas nas configurações avançadas da entidade e teste o agente novamente.

O bot de voz pula algumas respostas

Problema

Para um agente projetado para texto e voz, o bot de voz não lê algumas respostas.

Solução

Se pelo menos uma resposta de texto de áudio de saída for definida para uma determinada rodada de conversa, verifique se a opção de texto de áudio de saída está sempre presente nas respostas de fulfillment e webhook do agente em todas as etapas dessa rodada de conversa.

As tags SSML não entram em vigor

Problema

As tags SSML são definidas no fulfillment do agente, mas o bot de voz lê o texto sintetizado sem efeitos SSML.

Solução

Verifique se há apenas um par <speak></speak> por card de resposta no console do Dialogflow ou por objeto de mensagem de resposta se as respostas forem fornecidas pela API ou pelo webhook.

O agente de voz pronuncia zero como a letra O

Problema

Para um agente projetado para voz, o agente de voz lê zeros como a letra O, em vez de zero.

Solução

1. Mude O agente diz para usar a opção de diálogo de texto de áudio de saída.
2. Marque a caixa de seleção "SSML".
3. Coloque o texto entre uma tag SSML:

     <speak>
       <say-as interpret-as='verbatim'>YOUR_TEXT</say-as>
     </speak>

4. Salvar.

Por exemplo, os zeros dos números de cartão de crédito serão escritos como zeros:

   <speak>
      <say-as interpret-as='verbatim'>5177 7702 8500 4578</say-as>
   </speak>

Pronúncia sintetizada inesperada

Problema

A pronúncia sintetizada das respostas do agente (por exemplo, nomes próprios, acrônimos) não é a esperada.

Solução

Para garantir pronúncias específicas de palavras não muito conhecidas, use a tag SSML say-as ou phoneme nas respostas do agente.

O número máximo de etapas de execução da máquina de estado foi atingido

Problema

Recebeu a seguinte mensagem de erro no console do Dialogflow CX ou nos registros ao enviar solicitações de ambiente de execução para o agente:

You have reached the maximum allowed state machine execution steps. You may consider simplifying your agent/flow design. Current execution steps are: [<array_of_objects>]

A matriz na mensagem de erro contém uma lista de etapas de execução da solicitação. A lista pode estar incompleta se o número de etapas for muito grande.

Solução

Essa mensagem de erro geralmente indica que o número de transições para uma única conversa é muito grande. Um exemplo comum é a transição para a mesma página, o que cria um loop infinito.

Para resolver o problema:

1. Copie a matriz JSON da mensagem de erro.
2. (Opcional) Formate a matriz copiada como JSON para melhorar a legibilidade. Se a mensagem de erro estiver truncada, procure o último objeto "Step", exclua o objeto de etapa incompleto e a vírgula anterior e adicione um colchete de fechamento antes de validar e formatar o JSON.
3. Observe os valores "TriggeredTransitionRouteId" e "TargetPage" de cada etapa. No caso de loop infinito, os campos "TriggeredTransitionRouteId" e "TargetPage" têm valores repetidos para a maioria das etapas.
4. Modifique o design do agente para remover as transições de loop infinito ou reduzir o número de transições para uma única conversa.

A correspondência de expressão regular é muito ampla

Problema

Recebeu um erro Regular expression match is too broad ao criar uma entidade de regexp (Dialogflow CX, Dialogflow ES).

Solução

Considere a seguinte abordagem:

• Use ^ e $ na expressão regular para indicar o início e o fim do texto, respectivamente.
• Use a entidade regexp com um parâmetro obrigatório (Dialogflow CX, Dialogflow ES).
• Defina os comandos de parâmetro obrigatórios para pedir que o usuário final forneça apenas o valor da entidade, sem palavras ao redor.

Caracteres não alfanuméricos indesejados inseridos pelo reconhecimento de fala

Problema

Ao tentar fazer a correspondência de caracteres alfanuméricos, caracteres não alfanuméricos indesejados (espaços, traços etc.) são inseridos pelo reconhecedor de fala, o que resulta na não correspondência da entidade.

Solução

1. Se você usa entidades do sistema para correspondência de números, use entidades de regexp (Dialogflow CX, Dialogflow ES).
2. Siga todas as recomendações da seção Reconhecimento de fala alfanumérico impreciso por entidades regexp.
3. Para números correspondentes que usam integrações de telefonia, considere uma opção de DTMF, além do reconhecimento de voz.

Transcrições vazias para entradas de texto por voz

Problema

As respostas do Dialogflow para entradas de voz retornam transcrições vazias. As solicitações são processadas como sem entrada ou sem correspondência.

Solução

Ouça a gravação de áudio para confirmar que ela contém fala.

Verifique se a adaptação de fala está ativada nas configurações do agente (Dialogflow CX, Dialogflow ES).

Se a ativação da adaptação de fala não ajudar, teste os seguintes modelos de fala em uma configuração de não produção e use o que render os melhores resultados:

• latest_short
• phone_call
• command_and_search

Para outros idiomas, consulte os modelos de fala compatíveis na documentação de idiomas compatíveis com a Speech-to-Text.

A maneira de especificar um modelo de fala depende de como você configura as interações com o Dialogflow.

• Para solicitações de API, informe o nome do modelo no campo model em InputAudioConfig (Dialogflow CX, Dialogflow ES).

• Se você usa o gateway telefônico (Dialogflow CX, Dialogflow ES), é possível atualizar o modelo de fala no perfil de conversa criado pelo Dialogflow quando você ativou a integração:

  1. Recupere o ID do perfil de conversa:

     • Use o método conversationProfiles.list para recuperar todos os perfis de conversa vinculados ao seu projeto.
     • Encontre o perfil de conversa que você quer atualizar e copie o valor do campo name.

     Para o gateway telefônico do Dialogflow CX, o nome de exibição do perfil de conversação pode ser encontrado nas configurações de integração. No gateway telefônico do Dialogflow ES, o nome de exibição do perfil de conversa corresponde ao nome do agente em que a integração foi ativada.

     Se você tiver vários perfis de conversa com o mesmo nome de exibição, verifique o ID do agente no campo automatedAgentConfig da resposta do método conversationProfiles.list.

  2. Use o método da API conversationProfiles.patch para atualizar o campo model em SpeechToTextConfig.

• Para integrações da Contact Center AI, verifique com seu integrador de telefonia como atualizar o modelo de fala para a integração ou para solicitações individuais.

Noções básicas sobre erros de loop do playbook

Problema

Ao vincular playbooks, você encontra o erro Playbook <playbookID> caused loop in playbook routes.

Solução

Um loop pode ocorrer se você tentar rotear para um playbook "ancestral", ou seja, um que chamou direta ou indiretamente o atual. Para corrigir isso, verifique se o roteamento do playbook é unidirecional e não volta para um playbook pai no mesmo caminho de conversa.

Erro de tela em branco "O tamanho do arquivo excede 2 MB" ao comparar versões de agentes

Problema

Ao tentar comparar duas versões diferentes do agente, a tela fica em branco com a mensagem de erro:

File size exceeds 2MB

Esse problema ocorre porque um dos arquivos excede 2 MB.

Solução

Para comparar versões de agentes em que um dos arquivos excede 2 MB, é recomendável usar o método de API compareVersion.

Reconhecimento de fala alfanumérico impreciso por entidades regexp

Problema

Recebimento de transcrições imprecisas para entradas de voz de caracteres alfanuméricos projetados para serem correspondidos a uma entidade regexp (Dialogflow CX, Dialogflow ES).

Solução

1. Verifique se a adaptação de fala está ativada nas configurações do agente (Dialogflow CX, Dialogflow ES).
2. Verifique se pelo menos uma entrada de entidade segue todos os requisitos de entrada de regex (Dialogflow CX, Dialogflow ES).
3. Para padrões específicos, use as expressões regulares mais específicas. Por exemplo, para um valor alfanumérico que começa com duas letras seguidas por cinco dígitos, use [a-zA-Z]{2}\d{5} em vez de [a-zA-Z0-9]{7}.
4. Verifique se a entidade regexp permite a correspondência de caracteres não alfanuméricos (espaços, traços etc.) que podem ser inseridos pelo reconhecedor de fala. Para atender ao requisito 2 desta lista, crie várias entradas de entidade: uma para atender ao requisito 2 desta lista e outra para considerar caracteres não alfanuméricos. Por exemplo, para corresponder a cinco dígitos e permitir caracteres não alfanuméricos:

    \d{5}
    (\d[^a-zA-Z0-9]*){5}
   

5. Verifique se o agente segue o requisito de definição de parâmetro (Dialogflow CX, Dialogflow ES).

   Exemplo para o Dialogflow CX

   

   Exemplo para o Dialogflow ES

   
6. Verifique se o agente segue o requisito de anotação de frases de treinamento (Dialogflow CX, Dialogflow ES).

   Exemplo para o Dialogflow ES

   
7. Verifique se os testes seguem as diretrizes de teste (Dialogflow CX, Dialogflow ES).
8. Para remover caracteres não alfanuméricos que podem ter sido inseridos pelo reconhecedor de fala, use o seguinte:
   • Para o Dialogflow CX: função do sistema SUBSTITUTE ou webhook
   • Para o Dialogflow ES: webhook
9. Verifique as limitações de adaptação de fala (Dialogflow CX, Dialogflow ES).

Design para conversas controladas

Crie seu agente com caminhos de conversa claramente definidos. Verifique se o agente pode solicitar as informações necessárias para atender aos requisitos do usuário. Evite um escopo de conversa muito amplo, que pode levar a um comportamento imprevisível.

Analisar registros

As entradas e saídas de playbooks, ferramentas e repositórios de dados são capturadas nos registros. Use os IDs de conversa coletados para seguir a cadeia de chamadas e identificar onde a execução deu errado.

Teste vários comandos

Se um conjunto específico de instruções não estiver funcionando como esperado, tente reformulá-lo. Como alternativa, você pode usar o Gemini para gerar comandos (meta-prompting). Essa abordagem iterativa pode ajudar a encontrar a frase ideal para seu caso de uso.

Forneça informações completas para o suporte

Ao abrir um caso de suporte com o Cloud Support, inclua os IDs de conversa relevantes e os registros coletados durante a investigação. Essas informações são essenciais para depurar problemas de maneira eficiente.