Criar um app do Google Chat com um agente de IA do ADK

Nesta página, explicamos como criar um complemento do Google Workspace que funciona no Google Chat e interage com um agente de IA do Kit de Desenvolvimento de Agente (ADK) hospedado no Vertex AI Agent Engine.

Observação:no Google Chat, os complementos aparecem para os usuários como apps do Google Chat. Você também pode criar seu app do Chat usando eventos de interação da API Google Chat. Para saber mais, consulte a Visão geral da extensão do Google Chat.

Os agentes de IA percebem o ambiente, raciocinam e executam ações complexas e de várias etapas de forma autônoma para alcançar uma meta definida. Neste tutorial, você vai implantar a amostra multiagente do ADK LLM Auditor que critica e revisa fatos usando o Gemini e o embasamento da Pesquisa Google.

O diagrama a seguir mostra a arquitetura e o padrão de mensagens:

No diagrama anterior, um usuário interagindo com um app de chat implementado com um agente de IA do ADK tem o seguinte fluxo de informações:

1. Um usuário envia uma mensagem para um app do Chat em uma mensagem direta ou em um espaço do Chat.
2. A lógica do app Chat implementada no Apps Script ou como um servidor da Web com endpoints HTTP recebe e processa a mensagem.
3. O agente de IA implementado com o ADK e hospedado com o Vertex AI Agent Engine recebe e processa a interação.
4. Opcionalmente, o app Chat ou o agente de IA podem se integrar aos serviços do Google Workspace, como Agenda ou Planilhas, ou a outros Serviços do Google, como Maps ou YouTube.
5. O app Chat envia respostas de forma assíncrona usando a API Google Chat para comunicar o progresso do agente de IA.
6. As respostas são entregues ao usuário.

Objetivos

• Prepare o ambiente.
• Implante o agente de IA do ADK.
• Implante o app Chat.
• Configure o app Chat.
• Teste o app Chat.

Pré-requisitos

• Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.
• Ter um projeto do Google Cloud com o faturamento ativado. Para verificar se um projeto já tem o faturamento ativado, consulte Verificar o status de faturamento dos seus projetos. Para criar um projeto e configurar o faturamento, consulte Criar um projeto do Google Cloud.

Configurar o ambiente

Ativar as APIs do Google Cloud

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

• No console do Google Cloud, ative as APIs Google Chat, Vertex AI e Cloud Resource Manager.

  Ativar as APIs

Configurar a tela de permissão OAuth

Todos os apps que usam o OAuth 2.0 exigem uma configuração de tela de permissão. Configurar a tela de consentimento do OAuth do app define o que é mostrado aos usuários e revisores de apps, além de registrar o app para que você possa publicá-lo mais tarde.

1. No console do Google Cloud, acesse Menu > Google Auth platform > Branding.

   Acessar a página "Branding"

2. Se você já tiver configurado o Google Auth platform, poderá definir as seguintes configurações da tela de permissão OAuth em Branding, Público-alvo e Acesso a dados. Se você receber uma mensagem informando que Google Auth platform ainda não foi configurado, clique em Começar:
1. Em Informações do app, no campo Nome do app, insira um nome para o app.
2. Em E-mail para suporte do usuário, escolha um endereço de e-mail para que os usuários possam entrar em contato se tiverem dúvidas sobre o consentimento deles.
3. Clique em Próxima.
4. Em Público-alvo, selecione Interno.
5. Clique em Próxima.
6. Em Informações de contato, insira um Endereço de e-mail para receber notificações sobre mudanças no seu projeto.
7. Clique em Próxima.
8. Em Concluir, leia a Política de dados do usuário dos serviços de API do Google e, se concordar, selecione Concordo com a Política de dados do usuário dos serviços de API do Google.
9. Clique em Continuar.
10. Clique em Criar.
3. Por enquanto, você pode pular a adição de escopos. No futuro, quando você criar um app para uso fora da sua organização do Google Workspace, mude o Tipo de usuário para Externo. Em seguida, adicione os escopos de autorização necessários para o app. Para saber mais, consulte o guia completo Configurar a permissão OAuth.

Criar uma conta de serviço no console do Google Cloud

Crie uma conta de serviço com o papel Vertex AI User seguindo estas etapas:

Console do Google Cloud

1. No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.

   Acessar a página "Contas de serviço"

2. Clique em Criar conta de serviço.
3. Preencha os detalhes da conta de serviço e clique em Criar e continuar.
   Observação: por padrão, o Google cria um ID exclusivo de conta de serviço. Se quiser mudar o ID, modifique o campo "ID da conta de serviço".
4. Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do projeto do Google Cloud. Para mais detalhes, consulte Como conceder, alterar e revogar o acesso a recursos.
5. Clique em Continuar.
6. Opcional: insira usuários ou grupos que podem gerenciar e realizar ações com essa conta de serviço. Para mais detalhes, consulte Como gerenciar a representação da conta de serviço.
7. Clique em Concluído. Anote o endereço de e-mail da conta de serviço.

CLI da gcloud

1. Crie a conta de serviço:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do projeto do Google Cloud. Para mais detalhes, consulte Como conceder, alterar e revogar o acesso a recursos.

A conta de serviço aparece na página de contas de serviço.

Criar uma chave privada

Aviso : este exemplo usa uma chave de conta de serviço exportada para simplificar. Não é recomendável exportar uma chave privada em produção porque ela não deve ser armazenada em um local inseguro, como o controle de origem.

Para saber mais sobre implementações seguras de contas de serviço e práticas recomendadas, consulte Escolher quando usar contas de serviço.

Para criar e fazer o download de uma chave privada para a conta de serviço, siga estas etapas:

1. No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.

   Acessar a página "Contas de serviço"

2. Selecione sua conta de serviço.
3. Clique em Chaves > Adicionar chave > Criar nova chave.
4. Selecione JSON e clique em Criar.

   Seu novo par de chave pública/privada é gerado e transferido por download para sua máquina como um novo arquivo. Salve o arquivo JSON baixado como credentials.json no seu diretório de trabalho. Esse arquivo é a única cópia da chave. Para saber como armazenar sua chave com segurança, consulte Como gerenciar chaves de contas de serviço.

5. Clique em Fechar.

Para mais informações sobre contas de serviço, consulte contas de serviço na documentação do IAM do Google Cloud.

Implantar o agente de IA do ADK

1. Abra a amostra do LLM Auditor no Agent Garden da Vertex AI:

   Abrir a amostra

2. Clique em Implantar.

3. Se solicitado, selecione seu projeto do Google Cloud.

4. Clique em Implantar no Cloud Shell.

5. Se for preciso, clique em Autorizar e siga o fluxo do OAuth para o Cloud Shell.

6. Quando o Cloud Shell estiver totalmente carregado, pressione Enter para executar a linha de comando pré-carregada e iniciar a implantação.

7. Se for preciso inserir a região, pressione Enter para usar a padrão.

8. Quando a operação for concluída, acesse o Vertex AI Agent Engine:

   Abra o mecanismo de agentes da Vertex AI

9. Clique em para copiar o nome do recurso do agente recém-implantado da tabela.

Criar e configurar o projeto do app do Chat

1. Clique no botão a seguir para abrir o projeto do Apps Script Guia de início rápido do agente de IA do ADK.

   Abrir o projeto

2. Clique em Visão geral > Fazer uma cópia.

3. No projeto do Apps Script, clique em Configurações do projeto > Editar propriedades do script > Adicionar propriedade do script para adicionar as seguintes propriedades:

   1. REASONING_ENGINE_RESOURCE_NAME com o nome do recurso do agente da Vertex AI copiado nas etapas anteriores.
   2. SERVICE_ACCOUNT_KEY com a chave JSON da conta de serviço baixada nas etapas anteriores, como { ... }.

4. Clique em Salvar propriedades do script.

5. No console do Google Cloud, acesse Menu > IAM e administrador > Configurações.

   Acessar as configurações do IAM e do administrador

6. No campo Número do projeto, copie o valor.

7. No projeto do Apps Script, clique em Configurações do projeto.

8. Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.

9. Em Número do projeto do GCP, cole o número do projeto do Google Cloud copiado nas etapas anteriores.

10. Clique em Configurar projeto. O projeto do Google Cloud e o projeto do Apps Script agora estão conectados.

Criar uma implantação de teste

Você precisa de um ID de implantação para esse projeto do Apps Script, para poder usá-lo na próxima etapa.

Para conseguir o ID da implantação principal, faça o seguinte:

1. No projeto do Apps Script do app Chat, clique em Implantar > Testar implantações.
2. Em ID da implantação principal, clique em Copiar.
3. Clique em Concluído.

Configurar o app do Chat

Usando a implantação do Apps Script, siga estas etapas para implantar o app do Google Chat para teste:

1. No console, pesquise Google Chat API e clique em API Google Chat.
2. Clique em Gerenciar.

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

   1. No campo Nome do app, digite ADK Quickstart.
   2. No campo URL do avatar, insira https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
   3. No campo Descrição, use ADK Quickstart.
   4. Em Funcionalidade, selecione Participar de espaços e conversas em grupo.
   5. Em "Configurações de conexão", selecione Projeto do Apps Script.
   6. No campo ID da implantação, cole o ID da implantação principal que você copiou antes.
   7. Em "Visibilidade", selecione Pessoas e grupos específicos do seu domínio e digite seu e-mail.

4. Clique em Salvar.

O app Chat está pronto para responder a mensagens.

Teste o app do Chat

Para testar o app do Chat, abra um espaço de mensagem direta com o app do Chat e envie uma mensagem:

1. Abra o Google Chat usando a conta do Google Workspace que você informou ao se tornar um testador de confiança.

   Acessar o Google Chat

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

4. Selecione seu app de chat nos resultados. Uma mensagem direta é aberta.

   Observação:se o app de 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 The Eiffel Tower was completed in 1900 e pressione enter.

   O app Chat responde com as respostas dos subagentes Crítico e Revisor.

Para adicionar testadores de confiança e saber mais sobre como testar recursos interativos, consulte Testar recursos interativos para apps do Google Chat.

Resolver problemas

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

Embora uma mensagem de erro não apareça na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar você a corrigir erros quando o registro de erros para apps do Chat está ativado. Para ajuda com a visualização, depuração e correção de 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 que você exclua 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 todo o projeto.

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

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

   Acesse 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

• Cheque a veracidade de declarações com um agente de IA do ADK e um modelo do Gemini
• Planejar viagens com um agente de IA acessível em todo o Google Workspace
• Integrar conceitos fundamentais de IA aos apps do Chat
• Responda perguntas com base em conversas do Chat usando um app do Chat com IA do Gemini
• Responder a incidentes com o Google Chat, a Vertex AI, o Apps Script e a autenticação de usuários
• Gerenciar projetos com o Google Chat, a Vertex AI e o Firestore