Criar um app do Google Chat para Dialogflow CX que entende e responde com linguagem natural

Nesta página, explicamos como criar um app do Google Chat capaz de entender e responder com linguagem natural usando o Dialogflow (em inglês). Este guia usa o Dialogflow CX, que tem uma integração direta com o Google Chat. Você também pode usar o Dialogflow ES para criar um app do Google Chat dessa plataforma seguindo o guia do Dialogflow ES para Google Chat.

Por exemplo, considere um app do Chat que ajuda pessoas a alugar carros. Um usuário escreve "Quero alugar um carro". O app do Chat pode responder com uma pergunta como "Onde você quer retirar o veículo?", o que inicia uma conversa semelhante à humana com o usuário. Nessa conversa, o app do Chat entenda e responde com fala humana ao reservar o aluguel do carro.

Esse é apenas um exemplo. Os apps do Dialogflow Chat são úteis em todos os tipos de interações. Se precisar de fala humana natural, ele chamará um app do Dialogflow Chat. Os agentes pré-criados ajudam você a começar rapidamente e mostram o que o Dialogflow pode fazer, como:

• Reservar voos
• Agendar consultas médicas
• Pedir comida para entrega
• Responda a perguntas sobre um catálogo de produtos de varejo, por exemplo, se os itens estão disponíveis em outras cores

• 

  Figura 1. Como selecionar um agente pré-criado para um app do Dialogflow Chat.

• 
  Figura 2. Teste o agente no Dialogflow CX para garantir que a lógica e a configuração dele funcionem conforme o esperado. O diagrama mostra um conjunto sequencial de páginas com temas relacionados a etapas específicas da conversa, como definir um local de embarque e devolução de um carro alugado, e configura a lógica que as conecta. A conversa é testada em um simulador.
• 
  Figura 3. Como configurar um app do Chat para processar respostas usando o agente do Dialogflow CX na página de configuração da API Chat no console do Google Cloud.
• 
  Figura 4. Conversar sobre como reservar um carro alugado com o app Dialogflow Chat no Google Chat.

Objetivos

• Configurar o ambiente.
• Criar e implantar um agente do Dialogflow CX.
• Crie e implante um app do Chat com a tecnologia do agente do Dialogflow CX.
• Teste o app do Chat.

Pré-requisitos

• Uma conta do Google Workspace com acesso ao Google Chat.
• Um projeto do Google Cloud.
• Ative o faturamento do seu projeto do Cloud. Saiba como verificar o status de faturamento dos projetos.

Arquitetura

O diagrama a seguir mostra a arquitetura de um app do Chat criado com o Dialogflow:

No diagrama anterior, um usuário que interage com um app do Dialogflow Chat tem o seguinte fluxo de informações:

1. Um usuário envia uma mensagem no Chat para um app do Chat em uma mensagem direta ou em um espaço do Chat.
2. Um agente virtual do Dialogflow, localizado no Google Cloud, recebe e processa a mensagem para produzir uma resposta.
3. Opcionalmente, usando um webhook do Dialogflow, o agente do Dialogflow pode interagir com serviços externos de terceiros, como um sistema de gerenciamento de projetos ou uma ferramenta de emissão de tíquetes.
4. O agente do Dialogflow envia uma resposta ao serviço de app do Chat no Chat.
5. A resposta é entregue ao espaço do Chat.

Configure o ambiente

Antes de usar as APIs do Google, você precisa ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.

1. No console do Google Cloud, ative as APIs Google Chat e Dialogflow.

   Ativar as APIs

2. Confirme se você está ativando as APIs no projeto correto do Cloud e clique em Próxima.

3. Confirme se você está ativando as APIs corretas e clique em Ativar.

Criar um agente do Dialogflow CX

Um agente do Dialogflow CX é um agente virtual que gerencia conversas simultâneas com seus usuários finais. Ele é um módulo de compreensão de linguagem natural que entende as nuances da linguagem humana. O Dialogflow converte textos do usuário final durante uma conversa em dados estruturados que seus aplicativos e serviços podem entender. Você projeta e cria um agente do Dialogflow para lidar com os tipos de conversas necessárias para seu sistema.

Um agente do Dialogflow é como um agente humano de call center. Você o treina para que lide com os cenários esperados de conversas, e o treinamento não precisa ser excessivamente explícito.

Veja como criar o agente do Dialogflow CX:

1. Abra o console do Dialogflow CX. Clique em Menu > Dialogflow CX.

   Acesse o console do Dialogflow CX

2. Escolha um projeto do Google Cloud. Para encontrar seu projeto, pode ser necessário clicar em Todos e pesquisar por ele.

3. Agora você tem a opção de escolher um agente pré-criado ou criar seu próprio agente. Se preferir explorar a personalização do agente em detalhes mais tarde, escolha um dos agentes pré-criados, que também são úteis para aprender sobre o que os agentes podem fazer.

   Para escolher um agente pré-criado, siga estas etapas:

   1. Clique em Usar agentes pré-criados.

   2. Selecione um agente pré-criado. Para este guia, selecione Viagem: aluguel de carros.

      Os agentes são classificados como iniciantes, intermediários ou avançados com base no número de recursos usados e na sofisticação da lógica de conversa. A escolha de um agente intermediário ou avançado pode exigir personalizações e configurações específicas do agente, incluindo a ativação de recursos e APIs no console do Google Cloud.

   3. Clique em Importar como agente.

   Para criar seu próprio agente, siga estas etapas:

   1. Clique em Criar agente.
   2. Selecione Gerar automaticamente para criar um agente de repositório de dados ou selecione Criar seu próprio para criar outros tipos de agentes.

   Para ver um tutorial detalhado do processo de criação do agente, consulte Criar um agente do Dialogflow CX.

4. Defina as configurações básicas do agente:

   1. Em Nome de exibição, digite um nome de exibição.
   2. Selecione um local. Se você quiser mudar as configurações de localização avançadas, clique em Editar.
   3. Selecione o fuso horário.
   4. Selecione o idioma padrão do agente. Não é possível alterar o idioma padrão de um agente após a criação.

5. Clique em Criar. O Dialogflow CX começa a criar o agente e, em seguida, exibe o fluxo inicial padrão dele.

6. Se quiser, personalize o agente. Para ver um tutorial detalhado sobre o processo de personalização do agente, consulte Criar um agente do Dialogflow CX.

7. Como prática recomendada, teste o agente:

   1. Clique em Testar agente.
   2. Selecione Agente de teste no ambiente.
   3. Em "Ambiente", selecione Rascunho.
   4. No fluxo, selecione Fluxo inicial padrão.
   5. Em "Página", selecione Página inicial.
   6. Na barra de escrita Talk to agent, digite Hello e pressione Enter. O agente responde se apresentando.
   7. Conclua o teste usando o exemplo de conversa de teste.

8. O agente do Dialogflow CX foi criado. Volte para o console do Dialogflow CX. Clique em Menu > Dialogflow CX.

   Acesse o console do Dialogflow CX

9. Em Agentes, clique em > Copiar nome. Salve esse nome, porque ele é usado na configuração do app do Chat.

Criar um app do Chat e conectá-lo ao agente do Dialogflow

Depois de criar um agente do Dialogflow CX, siga estas etapas para transformá-lo em um app do Chat:

1. No console do Google Cloud, acesse a API Google Chat. Pesquise "API Google Chat", clique em API Google Chat e em Gerenciar.

   Acessar a API Chat

2. Clique em Configuração e configure o app do Chat:

   1. Em Nome do app, digite Dialogflow App.
   2. No URL do avatar, digite https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png.
   3. Em Descrição, digite Responds to real human conversation.
   4. Em Funcionalidade, selecione Receber mensagens individuais e Participar de espaços e conversas em grupo.
   5. Em Configurações de conexão, selecione Dialogflow.
   6. Em Configurações do Dialogflow, selecione Dialogflow CX.
   7. Em Nome do recurso do agente ou ambiente, cole o nome do agente do Dialogflow CX que você copiou no final de Criar um agente do Dialogflow CX.
   8. Disponibilize este app do Chat para pessoas e grupos específicos no seu domínio e digite o endereço de e-mail.
   9. Em Registros, selecione Registrar erros no Logging.

3. Clique em Salvar.

O app do Chat está pronto para receber e responder a mensagens no Chat.

Teste o app do Chat

Envie uma mensagem no Google Chat para testar o app Dialogflow CX.

1. Abra o Google Chat usando a conta do Google Workspace que você forneceu ao se adicionar como trusted tester.

   Acessar o Google Chat

2. Clique em Nova conversa.
3. No campo Adicionar uma ou mais pessoas, digite o nome do seu app do Chat.

4. Selecione seu app do Chat nos resultados. Uma mensagem direta será aberta.

   Observação:se o app do Chat não aparecer na lista de resultados, verifique se você incluiu sua conta do Google Workspace nas configurações de Visibilidade da página Configuração da API Chat no console do Google Cloud.

5. Na nova mensagem direta com o app, digite Hello e pressione enter.

   O app Dialogflow Chat responde apresentando-se.

6. Conclua o teste usando a conversa de teste de amostra.

Exemplo de conversa de teste

Para testar o app do Dialogflow CX Chat no console do Dialogflow CX ou no Google Chat, converse a seguir. A explicação ajuda você a entender como o agente do Dialogflow CX interpreta a linguagem natural do usuário e produz a própria resposta de linguagem natural em cada etapa da conversa. Essa conversa de amostra é baseada no agente pré-criado chamado Viagens: aluguel de carros.

Caixa de diálogo	Explicação
Usuário final: Olá! Agente: Olá! Sou o agente virtual de aluguel de carros. Posso ajudar você a fazer uma nova reserva de aluguel de carro. Como posso ajudar?	A rota de Intent de boas-vindas padrão é chamada no fluxo inicial padrão. O fulfillment para esse gerenciador de estado ("Hi! Eu sou...") foi adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final.
Usuário final:quero alugar um carro. Agente:onde você quer pegar o veículo?	A rota da intent car_rental.reservation_create na Página inicial é correspondida. A sessão é transferida para a página Local de retirada. O formulário da página Local de retirada não está completo. Portanto, o agente usa o parâmetro pickup_location para solicitar ao usuário ("Onde você quer retirar..."), que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final.
Usuário final: Las Vegas Agente: Ok, sua retirada será em Las Vegas. Agente:O local de entrega é diferente do local de embarque?	A entrada do usuário final preenche o parâmetro pickup_location solicitado pelo agente na rodada de conversa anterior. A rota de intent car_rental.return_different_location no fluxo inicial padrão é correspondida. O trajeto de preenchimento do formulário na página Local de retirada é avaliado e chamado. Ela tem um fulfillment ("Ok, retirada..."), que é adicionado à fila de respostas com as referências de parâmetro resolvidas para os valores reais informados pelo usuário final. A sessão é transferida para a página Confirmar local. A página Confirmar local tem um fulfillment de entrada ("O local de entrega é diferente..."), que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final.
Usuário final:sim. Vou deixar o carro em Los Angeles. Agente: Ok, o desembarque será em Los Angeles. Agente: Em que data e hora você quer retirar o veículo?	A rota de intent car_rental.return_different_location no fluxo inicial padrão é correspondida. A sessão é transferida para a página Drop Off Location. A entrada do usuário final preenche o parâmetro drop_off_location solicitado pelo agente na rodada de conversa anterior. A rota de preenchimento do formulário na página Drop Off Location é avaliada e chamada. Ela tem um fulfillment ("Ok, devolução..."), que é adicionado à fila de resposta. A sessão é transferida para a página Rental Duration. A página Rental Duration tem valores de formulário incompletos, então ela solicita ao usuário o parâmetro pickup_date_time ("Qual data e hora você quer pegar..."). que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final.
Usuário final:quero pegar o carro no dia 5 de março ao meio-dia. Agente:qual é a data e hora para a entrega do veículo?	A entrada do usuário final preenche o parâmetro pickup_date_time solicitado pelo agente na conversa anterior. A página Rental Duration tem outro valor de formulário ausente, então ela solicita ao usuário o parâmetro drop_off_date_time ("Qual data e hora você quer para..."). que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final.
Usuário final:15 de março ao meio-dia. Agente: então, para confirmar: Você vai pegar o veículo em Las Vegas 05/03/2024, às 12:00:00, e deixar o veículo em Los Angeles 15/03/2024 12:00:00 Está certo?	A entrada do usuário final preenche o parâmetro drop_off_date_time solicitado pelo agente na rodada de conversa anterior. A sessão é transferida para a página Confirmar duração da locação. A página Confirmar duração da locação tem um cumprimento da entrada ("Para confirmar..."), que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final.
Usuário final: sim, obrigado. Agente: Ótimo! Agora, vamos escolher um veículo. Agente:você quer um veículo econômico ou de luxo?	A rota da intent small_talk.confirmation.yes na página Confirm Rental Duration é correspondida. O agente confirma a escolha do usuário com uma mensagem ("Ótimo! Agora, vamos escolher..."), que é adicionado à fila de respostas. A sessão é transferida para a página Desambiguação do veículo. Como o formulário da página Desambiguação de veículos não está completo, o agente usa o parâmetro vehicle_type para pedir ao usuário: "Você quer uma economia ou um luxo...". que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final.
Usuário final:economia, por favor. Agente: você quer o carro ou o caminhão Cymbal?	O trajeto da intent $session.params.vehicle_type="economy_vehicle" é correspondente. A sessão é transferida para a página Opções econômicas. A página Opções de economia tem um fulfillment de entrada ("Você gostaria de..."), que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final.
Usuário final:Cymbal Truck. Agente: o caminhão Cymbal custa US $50,33 por dia. Ele acomoda quatro pessoas e vem com rádio AM/FM. Quer prosseguir para o pagamento? Usuário final:sim.	O trajeto da intent $session.params.vehicle_type="Cymbal Truck" é correspondido, e o parâmetro vehicle_model é preenchido. A sessão é transferida para a página Confirm Cymbal Truck. A página Confirmar caminhão da Cymbal tem um cumprimento de entrada ("O caminhão da Cymbal custa US $50,33 por dia..."), que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final. A resposta do usuário corresponde à rota small_talk.confirmation.yes.
Agente: Qual tipo de cartão você vai usar? Usuário final: Altostrat Agent: Insira o número do cartão. Usuário final:1234 1234 1234 1234 Agente: Qual é o nome do cartão? Usuário final: Carlos Agente: Qual é o endereço de faturamento? Usuário final: 1800 Amphibious Blvd. Mountain View, CA Agent: Qual é o CEP de faturamento? Usuário final: 94045 Agente: você vai escolher o carro Cymbal em Las Vegas, 05/03/2024, 12:00:00, e deixá-lo embora, em 15/03/2024, às 12:00:00. O total dessa viagem será de US$ 175,38. Agente: Agradecemos o aluguel. Tenha um ótimo dia.	A sessão é transferida para a página Pagamento. O formulário Payment não está completo, então o agente solicita ao usuário os parâmetros card_type, card_number, billing_name, billing_street_address e billing_zip_code ("Qual tipo de cartão será..."), que são adicionados sequencialmente à fila de resposta e enviados à medida que o usuário responde. As respostas do usuário definem cada valor de parâmetro. A sessão é transferida para a página Confirmação de locação. A página Confirmação de locação tem um atendimento de entrada ("Ok, sua retirada será..."), que é adicionado à fila de respostas. O agente envia a fila de respostas ao usuário final. A sessão é transferida para a página Encerrar sessão.

Enviar mensagens de cartão do Dialogflow

Codelab:para ver um exemplo aplicado de como enviar mensagens de card do Dialogflow, consulte Exibir fontes de informações nas respostas do app do Chat no codelab "Criar apps para o Google Chat com o Gemini".

O Dialogflow pode responder com mensagens de texto ou cartão. Para responder com uma mensagem de cartão, especifique-a como um payload personalizado no fulfillment.

O JSON a seguir mostra como enviar uma mensagem de cartão como um payload personalizado no fulfillment:

json

{
  'cardsV2': [{
    'cardId': 'createCardMessage',
    'card': {
      'header': {
        'title': 'A card message!',
        'subtitle': 'Sent from Dialogflow',
        'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
        'imageType': 'CIRCLE'
      },
      'sections': [
        {
          'widgets': [
            {
              'buttonList': {
                'buttons': [
                  {
                    'text': 'Read the docs!',
                    'onClick': {
                      'openLink': {
                        'url': 'https://developers.google.com/workspace/chat'
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }]
}

Limites e considerações

• Os eventos de interação de chat têm suporte limitado e algumas considerações:
  • Há suporte para os seguintes tipos de eventos de interação:
    • MESSAGE
    • ADDED_TO_SPACE
    • CARD_CLICKED
  • Para eventos MESSAGE ou ADDED_TO_SPACE, a entrada da consulta enviada ao agente do Dialogflow corresponde ao valor do campo argumentText na mensagem do Chat. Se a mensagem incluir um comando de barra, o valor do campo text será usado.
  • Para eventos CARD_CLICKED, a entrada da consulta enviada ao agente do Dialogflow é formatada como CARD_CLICKED.functionName, em que functionName corresponde ao valor do campo function do objeto Action anexado ao elemento interativo do cartão (como um botão).
  • O payload completo do JSON de cada evento de interação do Chat é enviado para o Dialogflow como payload personalizado no parâmetro de consulta e pode ser acessado com um webhook do Dialogflow consultando o valor do campo WebhookRequest.payload.
• Considerações para responder a comandos de barra e receber dados de cards ou caixas de diálogo:
  • Quando os apps do Dialogflow Chat recebem uma mensagem com um comando de barra, a entrada da consulta contém apenas o valor do campo text. O campo text começa com o nome do comando de barra (por exemplo, /command), que pode ser usado para configurar a intent de um agente do Dialogflow para detectar um comando de barra.
  • Se o agente do Dialogflow precisar processar o payload JSON do evento de interação de chat, use um webhook do Dialogflow para inspecionar o payload personalizado no parâmetro de consulta.
  • Para exibir uma caixa de diálogo do agente do Dialogflow, responda com um único payload JSON personalizado que inclua uma mensagem contendo uma resposta de ação DIALOG.
  • Para processar dados inseridos de cartões, o agente do Dialogflow pode detectar intents que começam com o texto CARD_CLICKED e responder com um único payload JSON personalizado contendo a ação apropriada.
• Visualizações de links não são compatíveis.
• Se o agente do Dialogflow responder com apenas uma mensagem, ela será enviada ao Google Chat de maneira síncrona. Se o agente do Dialogflow responder com várias mensagens, todas elas serão enviadas ao Chat de forma assíncrona, chamando o método create no recurso spaces.messages na API Chat uma vez para cada mensagem.
• Ao usar a integração do Dialogflow CX com o Chat, o agente do Dialogflow e o app do Chat precisam ser configurados no mesmo projeto do Google Cloud. Se você precisar configurar o Dialogflow e o Chat em projetos diferentes do Cloud, defina um servidor intermediário para facilitar a conexão. Para saber como fazer isso, consulte este exemplo de integração do Chat para o Dialogflow CX no GitHub.

Resolver problemas

Quando um app ou card do Google Chat retorna um erro, a interface do Chat mostra uma mensagem dizendo "Algo deu errado". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não exibe nenhuma mensagem de erro, mas o app ou card produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.

Embora uma mensagem de erro possa não ser exibida na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar você a corrigir erros quando a geração de registros de erros para apps do Chat está ativada. Se precisar de ajuda para visualizar, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, recomendamos excluir o projeto do Cloud.

Cuidado:excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para seguir este tutorial, a exclusão dele incluirá quaisquer outras ações feitas no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL em appspot.com, exclua os recursos selecionados dentro do projeto em vez de excluir o projeto inteiro.

Se você planeja ver vários tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites de cota do projeto.

1. No Console do Google Cloud, acesse a página Gerenciar recursos. Clique em Menu > IAM e administrador > Gerenciar recursos.

   Acessar o Resource Manager

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Temas relacionados

• O Dialogflow CX usa uma abordagem de máquina de estado para o design do agente do Dialogflow, o que oferece controle claro e explícito sobre uma conversa, uma experiência melhor para o usuário final e um melhor fluxo de trabalho de desenvolvimento. Ao criar um app do Dialogflow Chat, recomendamos o uso do Dialogflow CX.
  • Para saber mais sobre como criar e configurar agentes, consulte Agentes do Dialogflow CX.
  • Para um tutorial detalhado sobre como criar e configurar agentes, consulte Criar um agente do Dialogflow CX.
  • Codelab:para conferir um exemplo de como criar um agente de armazenamento de dados do Dialogflow CX, consulte o app de conhecimento do Chat no codelab Criar apps para o Google Chat com o Gemini.
  • Codelab:para conferir um exemplo de como criar um agente de conversação do Dialogflow CX, consulte o app de feedback do Chat do codelab Criar apps para o Google Chat com o Gemini.
• Dialogflow ES é outra maneira de usar o Dialogflow com um app do Chat.