Solução de problemas

Ativar o Cloud Logging para seu agente

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

Coletar IDs de conversa

Quando um comportamento inesperado ocorrer, colete os IDs da conversa do Dialogflow. Esses IDs, encontrados no histórico de conversas, oferecem uma maneira de 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 a autenticação e os papéis (Dialogflow CX, Dialogflow ES) foram configurados corretamente. 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 ocorrer devido à criação manual de credenciais com sua biblioteca de cliente ao 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 a troca para um host diferente

Problema

Resposta Please switch to 'REGION-dialogflow.googleapis.com' to access resources located in 'REGION' recebida na 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 faltando 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 se o valor retornado for 0.

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

• Protocol buffers (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 não é possível excluir o projeto porque ele 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 link na caixa de diálogo de exclusão do projeto 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. Desligar o projeto.

O webhook do Dialogflow CX falha com o erro "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 do 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 limite:

• Tentativa de acionar uma intent inexistente.
• Um problema de inicialização a frio com o back-end do webhook (por exemplo, o 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 mal configurado).
• Uma política da organização impede que o tráfego de entrada ou os métodos do Dialogflow sejam executados.

Alternativa

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

O console falha ao configurar o projeto

Problema

Recebeu 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 Google Cloud . Verifique se é possível criar um projeto do Google Cloud diretamente no console. Se você não conseguir 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 a eles será mostrada se não forem encontrados na sessão atual ou se não estiverem sendo usados 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 é de 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 com uma 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 na conta da organização.

Solução

Entre em contato com o administrador de sistemas da sua organização e verifique se as configurações da organização dão acesso ao console. Caso contrário, verifique se sua conta migrada de outra organização foi sinalizada como restrita pelo Google. Esse é o problema mais provável se outros usuários da sua organização conseguem 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á faltando

Problema

A exportação do agente como bytes brutos é concluída com sucesso, mas a exportação 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 excluído.

Solução

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

Conectividade do gateway telefônico

Problema

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

Solução

Há cotas e limites para esse recurso. Se você receber um sinal de ocupado ou a chamada cair, é possível que você 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 usados associados ao seu projeto até ficar 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. Excluir o agente sem excluir o número de telefone não remove o número associado a ele.

Como alternativa, use a API seguindo estas etapas.

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ê pode ter criado 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, 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/phoneNumbers
  

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

Receber o ID do agente do Dialogflow CX associado ao número de telefone pelo perfil de conversa pode ajudar você 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 da API projects.conversationProfiles/get. Você pode encontrar 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
  

Para encontrar o agente pelo ID no console do Dialogflow CX, use 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. Abra 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 usados

Para excluir números de telefone que não são mais necessários, use o método da API projects.phoneNumbers/delete ou projects.locations.phoneNumbers.delete. Você pode encontrar os IDs dos números 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 estiver vendo 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.

Valor de parâmetro correspondente sem ser 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 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 para garantir que nenhuma delas seja aplicada ao texto que representa o valor correspondente indesejado.
3. Teste o agente durante a 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 de 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 troca de conversa, verifique se a opção de texto de áudio de saída está sempre presente em todas as etapas das respostas de fulfillment e webhook do agente para essa troca de conversa.

As tags SSML não entram em vigor

Problema

As tags SSML são definidas no atendimento do agente, mas o bot de voz lê o texto sintetizado sem efeitos de 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, ele 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 "Texto de áudio".
2. Marque a caixa de seleção SSML.
3. Coloque o texto entre tags SSML:

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

4. Salvar.

Por exemplo, os zeros de números de cartão de crédito serão pronunciados 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.

Você atingiu o número máximo de etapas de execução da máquina de estado permitidas

Problema

Recebeu a seguinte mensagem de erro no console do Dialogflow CX ou nos registros ao enviar solicitações de tempo de execução ao 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>]

O array na mensagem de erro contém uma lista de etapas de execução para a 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 rodada de 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 de matriz antes de validar e formatar o JSON.
3. Analise os valores de "TriggeredTransitionRouteId" e "TargetPage" para cada etapa. No caso de um loop infinito, os campos "TriggeredTransitionRouteId" e "TargetPage" têm valores repetidos na maioria das etapas.
4. Modifique o design do seu agente para remover as transições de loop infinito ou reduzir o número de transições em uma única rodada de 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 expressão regular (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 de expressão regular com um parâmetro obrigatório (Dialogflow CX, Dialogflow ES).
• Defina os prompts de parâmetro obrigatórios para pedir ao usuário final que forneça apenas o valor da entidade, sem palavras ao redor.

Inserção de caracteres não alfanuméricos indesejados pelo reconhecimento de fala

Problema

Ao tentar corresponder caracteres alfanuméricos, o reconhecedor de voz insere caracteres não alfanuméricos indesejados (espaços, traços etc.), o que faz com que a entidade não seja correspondida.

Solução

1. Se você usa entidades de sistema para corresponder a números, considere usar entidades de expressão regular (Dialogflow CX, Dialogflow ES).
2. Siga todas as recomendações da seção Reconhecimento de fala alfanumérico impreciso por entidades regexp.
3. Para corresponder números usando 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 se ela contém fala.

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

Se ativar a adaptação de voz não ajudar, teste os seguintes modelos de voz em uma configuração que não seja de produção e use aquele que apresentar os melhores resultados:

• latest_short
• phone_call
• command_and_search

Para outros idiomas, consulte os modelos de voz compatíveis na documentação de idiomas aceitos pelo Speech-to-Text.

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

• Para solicitações de API, forneça 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.

     No gateway telefônico do Dialogflow CX, o nome de exibição do perfil de conversa pode ser encontrado nas configurações de integração. Para o Dialogflow ES Phone Gateway, 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, consulte seu integrador de telefonia sobre como atualizar o modelo de fala para a integração ou para solicitações individuais.

Como entender erros de loop de 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 direcionar para um playbook "ancestral", ou seja, um que chamou o atual direta ou indiretamente. Para corrigir isso, verifique se o roteamento do playbook é unidirecional e não volta para um playbook principal no mesmo caminho de conversa.

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

Problema

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

File size exceeds 2MB

Isso acontece porque um dos arquivos tem mais de 2 MB.

Solução

Para comparar versões do agente em que um dos arquivos excede 2 MB, recomendamos usar o método da API compareVersion.

Reconhecimento de fala alfanumérico impreciso por entidades regexp

Problema

Recebimento de transcrições imprecisas para entradas de voz de alfanuméricos projetados para serem correspondidos a uma entidade de expressão regular (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 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 de regex permite a correspondência de caracteres não alfanuméricos (espaços, traços etc.) que podem ser inseridos pelo reconhecedor de voz. Para atender ao requisito 2 desta lista, crie várias entradas de entidade: uma para atender aos requisitos 2 desta lista e outra para considerar caracteres não alfanuméricos. Por exemplo, para corresponder a cinco dígitos e permitir 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 voz, use o seguinte:
   • Para o Dialogflow CX: função do sistema SUBSTITUTE ou webhook
   • Para o Dialogflow ES: webhook
9. Confira as limitações da adaptação de voz (Dialogflow CX, Dialogflow ES).

Projetar 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 acompanhar a cadeia de chamadas e identificar onde a execução deu errado.

Teste os comandos

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

Fornecer informações completas ao suporte

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