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

Esta página explica 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 em Vertex AI Agent Engine.

Observação:no Google Chat, os complementos aparecem para os usuários como apps do Google Chat. Também é possível criar seu app do Chat usando eventos de interação da API Google Chat. Para saber mais, consulte a visão geral de como estender o Google Chat.

Os agentes de IA percebem o ambiente de forma autônoma, raciocinam e executam ações complexas de várias etapas para alcançar um objetivo definido. Neste tutorial, você vai implantar o exemplo 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 que interage com um app do 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 do 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 no Vertex AI Agent Engine recebe e processa a interação.
4. Opcionalmente, o app do Chat ou o agente de IA pode se integrar aos serviços do Google Workspace, como a Agenda ou o Planilhas, ou a outros serviços do Google, como o Google Maps ou o YouTube.
5. O app do 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 do Chat.
• Configure o app do Chat.
• Teste o app do 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 atual tem o faturamento ativado, consulte Verificar o status de faturamento dos seus projetos. Para criar um projeto na nuvem e configurar o faturamento, consulte Criar um projeto na nuvem 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 da tela de permissão. A configuração da tela de permissão OAuth do seu app define o que é mostrado aos usuários e revisores de apps e registra seu app para que você possa publicá-lo mais tarde.

1. No console de APIs do Google, acesse Menu > Plataforma de autenticação do Google > Branding.

   Acessar Branding

2. Se você já tiver configurado a plataforma de autenticação do Google, poderá configurar as seguintes configurações da tela de permissão OAuth em Branding, Público-alvo e Acesso a dados. Se você vir uma mensagem informando que a plataforma de autenticação do Google ainda não está configurada, 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 de suporte para que os usuários possam entrar em contato com você se tiverem dúvidas sobre o consentimento.
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, revise 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, ao criar um app para uso fora da sua organização do Google Workspace, será necessário mudar 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 guide.

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

Crie uma nova 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"

   As etapas restantes aparecem no console do Google Cloud.

2. Selecione um projeto do Google Cloud.
3. Clique em Criar conta de serviço.
4. Insira um nome de conta de serviço a ser exibido no console do Google Cloud.
   Observação: por padrão, o Google cria um ID de conta de serviço exclusivo com base no nome da conta de serviço. É possível modificar o ID no campo "ID da conta de serviço". Não é possível mudar o ID mais tarde.
5. Se você não quiser definir controles de acesso agora, clique em Concluído para finalizar a criação da conta de serviço. Para definir os controles de acesso agora, clique em Criar e continuar e avance para a próxima etapa.
   Observação:a concessão de controle de acesso aqui afeta apenas os recursos do Google Cloud. Os recursos do Google Workspace (como o Planilhas Google e o Google Drive) são compartilhados e configurados separadamente.
6. Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do projeto do Google Cloud, além dos recursos do Google Workspace. Para mais detalhes, consulte Gerenciar o acesso a projetos, pastas e organizações.
7. Clique em Continuar.
8. Opcional: insira usuários ou grupos que podem gerenciar e realizar ações com essa conta de serviço. Para mais detalhes, consulte identidade temporária de conta de serviço.
9. Clique em Concluído para terminar a criação da conta de serviço.

   Anote o endereço de e-mail da conta de serviço.

CLI 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, além dos recursos do Google Workspace. Para mais detalhes, consulte Gerenciar o acesso a projetos, pastas e organizações.

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 por simplicidade. A exportação de uma chave privada não é recomendada na produção porque ela não deve ser armazenada em um local não seguro, 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"

   As etapas restantes aparecem no console do Google Cloud.

2. Selecione um projeto do Google Cloud.
3. Clique no endereço de e-mail da conta de serviço para a qual você quer criar uma chave.
4. Clique na guia Chaves.
5. Clique no menu suspenso Adicionar chave e selecione Criar nova chave.
6. Selecione JSON como o Tipo de chave e clique em Criar.

   Seu novo par de chave pública/privada é gerado e transferido por download para sua máquina como um arquivo de chave de conta de serviço. Salve o arquivo JSON transferido por download como credentials.json no seu diretório de trabalho. Esse é o único arquivo da chave. Depois de fazer o download do arquivo de chave, não é possível fazer o download novamente. Para informações sobre como armazenar a chave com segurança, consulte Práticas recomendadas para gerenciar chaves de contas de serviço.

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

Implantar o agente de IA do ADK

1. Abra o exemplo do LLM Auditor no Vertex AI Agent Garden:

   Abrir o exemplo

2. Clique em Implantar.

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

4. Clique em Implantar no Cloud Shell.

5. Se solicitado, 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 solicitado a inserir a região, pressione Enter para usar o padrão.

8. Quando terminar, acesse o Vertex AI Agent Engine:

   Abrir o Vertex AI Agent Engine

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 do script:

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

4. Clique em Salvar propriedades do script

5. No console de APIs do Google, 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 na nuvem do Google copiado nas etapas anteriores.

10. Clique em Configurar projeto. O projeto na nuvem 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 usá-lo na próxima etapa.

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

1. No projeto do Apps Script do app do 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 de APIs, pesquise Google Chat API, e clique em API Google Chat.
2. Clique em Gerenciar.

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

   1. No campo Nome do app, insira 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, insira 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 de implantação, cole o ID da implantação principal que você copiou anteriormente.
   7. Em "Visibilidade", selecione Pessoas e grupos específicos do seu domínio e insira seu e-mail.

4. Clique em Salvar.

O app do 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ê forneceu ao se adicionar como um testador confiável.

   Acessar o Google Chat

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

4. Selecione o 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 de APIs do Google.

5. Na nova mensagem direta com o app, digite The Eiffel Tower was completed in 1900 e pressioneenter.

   O app do Chat responde com as respostas do subagente Critic e Reviser.

Para adicionar testadores confiáveis 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 uma mensagem informando que "Algo deu errado." 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 de card pode não aparecer.

Embora uma mensagem de erro não seja exibida na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar a corrigir erros quando o registro de erros para apps do Chat está ativado. Para receber ajuda para visualizar, depurar e corrigir erros, consulte Resolver 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:a exclusão de 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 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 de APIs do Google, 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 Desativar para excluir o projeto.

Temas relacionados

• Criar um app do Google Chat com um agente de IA do ADK exposto pelo A2A
• Criar um app do Google Chat com um agente de IA do ADK exposto pelo A2UI
• Criar agentes do Gemini Enterprise que são integrados aos repositórios de dados, APIs e apps do Chat do Workspace
• Criar agentes da Vertex AI que são integrados aos repositórios de dados, APIs e apps do Chat do Workspace
• 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 no Google Workspace
• Criar um app do Google Chat com um agente de IA do Gemini Enterprise
• Integrar conceitos básicos de IA aos apps do Chat
• Responda perguntas com base em conversas com IA usando um app do Chat com IA do Gemini
• Responde 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