Planejar viagens com um agente de IA acessível em todo o Google Workspace

Nível de programação: avançado
Duração: 45 minutos
Tipo de projeto: complemento do Google Workspace que estende o Chat, Gmail, Agenda, Drive, Documentos, Planilhas e Apresentações.

Neste tutorial, você aprende a publicar agentes de IA no Google Workspace como complementos do Google Workspace usando o Apps Script ou endpoints HTTP. Depois de publicar o complemento, os usuários podem interagir com os agentes de IA nos fluxos de trabalho.

Visão geral

Neste tutorial, você implantará o exemplo Travel Concierge do Agent Development Kit (ADK). O Travel Concierge é uma IA de conversação com vários agentes que usa ferramentas como a API Places da plataforma Google Maps, o Grounding da Pesquisa Google e um servidor do protocolo de contexto de modelo (MCP).

O ADK fornece interfaces de chat e texto para desenvolvedores por padrão. Neste tutorial, você adiciona uma interface gráfica do usuário (GUI) aos aplicativos do Google Workspace que seus usuários podem acessar diretamente no Chat, Gmail, Agenda, Drive, Documentos, Planilhas e Apresentações.

• 

  Figura 1. Usar o agente de IA do chat para discutir ideias de viagens.

• 

  Figura 2. Utilizando o agente de IA do Gmail para planejar uma viagem com base no contexto do e-mail selecionado.

Objetivos

• Configure o ambiente.
• Implante o agente de IA.
• Configure o projeto.
• Implante no Gmail, Agenda, Drive, Documentos, Planilhas e Apresentações.
• Implantar no Chat.
• Testar a solução.

Sobre esta solução

Esta solução depende das seguintes tecnologias principais: ADK, Google Cloud eAPIs do Google Workspace ,Motor de Agentes de IA Vertex , eEstrutura do cartão.

As interfaces gráficas de usuário (GUIs) são projetadas de forma diferente para aplicativos de bate-papo e aplicativos que não são de bate-papo (Gmail, Calendário, Drive, Documentos, Planilhas, Apresentações) para levar em consideração seus recursos e limitações específicos.

Recursos

Os seguintes recursos do aplicativo Travel Concierge são comuns a todos os aplicativos do Google Workspace:

• Sessões de usuário persistentes: As sessões são gerenciadas pela Vertex AI para persistência. Cada usuário compartilha uma única sessão em todos os aplicativos do Workspace. Os usuários podem redefinir manualmente sua sessão para iniciar uma nova conversa.

• Mensagens avançadas:os usuários enviam mensagens de texto e recebem respostas com texto avançado e widgets de card.

• Tratamento de erros: Erros inesperados são tratados de forma elegante usando novas tentativas configuráveis e status nas respostas.

O app Chat tem os seguintes recursos extras:

• Mensagens multimodais do usuário:os usuários podem enviar mensagens com anexos, incluindo áudio e vídeo gravados diretamente no espaço do Chat.

• Respostas visualmente mais avançadas:as respostas podem ser geradas com widgets mais avançados, como carrosséis com imagens, usando recursos somente de chat da estrutura de cards e mais espaço de renderização.

Outros apps têm estes recursos adicionais:

• Contexto do perfil do Google:os usuários podem enviar mensagens com as informações do perfil (limitadas a aniversários neste exemplo).

• Contexto do Gmail: Os usuários podem enviar mensagens por e-mail (limitadas a um assunto e corpo neste exemplo).

• Acesso ao espaço de bate-papo do agente: Os usuários podem abrir o espaço de mensagens diretas (DM) do aplicativo de bate-papo em uma nova guia com um clique de botão.

Arquitetura

O aplicativo Travel Concierge recebe e processa eventos de interação do complemento Google Workspace provenientes de aplicativos do Google Workspace, utiliza o Vertex AI para acionar o agente ADK AI e gerenciar sessões de usuário, e depende das APIs do Google Cloud e do Google Workspace para coletar contexto e exibir respostas.

Os diagramas a seguir mostram o fluxo principal do usuário: enviar uma mensagem para o agente de IA.

HTTP

• 

  Figura 3. O aplicativo Chat completa o contexto com anexos da mensagem do usuário e envia um conjunto de mensagens com o histórico das interações do subagente e a resposta geral final em ordem cronológica.

• 

  Figura 4. Os aplicativos que não são do Chat completam o contexto com o perfil do Google do usuário e a seleção de itens, além de mostrar um conjunto de seções com o histórico das interações do subagente e a resposta geral final em ordem cronológica inversa.

Apps Script

• 

  Figura 3. O aplicativo Chat completa o contexto com anexos da mensagem do usuário e envia um conjunto de mensagens com o histórico das interações do subagente e a resposta geral final em ordem cronológica.

• 

  Figura 4. Os aplicativos que não são do Chat completam o contexto com o perfil do Google do usuário e a seleção de itens, além de mostrar um conjunto de seções com o histórico das interações do subagente e a resposta geral final em ordem cronológica inversa.

Pré-requisitos

• Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.

• Um navegador web com acesso à internet.

• Pré-requisitos específicos para o agente de IA ADK do Travel Concierge

  • Python 3.10+: Para instalação, siga as instruções no site oficial do Python.
  • uv: para a instalação, siga as instruções no site oficial do uv.
  • CLI do Google Cloud: Para instalação, siga as instruções no site oficial.Site do Google Cloud .

Prepare o ambiente

Esta seção mostra como criar e configurar um projeto do Google Cloud.

Criar um projeto do Google Cloud

Console do Google Cloud

1. No console do Google Cloud, acesse o Menu. > IAM e Administração > Criar um projeto .

   Acesse Criar um Projeto

2. No campo Nome do Projeto, insira um nome descritivo para o seu projeto.

   Opcional: para editar o ID do projeto, clique em Editar. O ID não pode ser alterado após a criação do projeto. Portanto, escolha um código que atenda às suas necessidades durante a vida útil dele.

3. No campo Local, clique em Procurar para mostrar possíveis locais para seu projeto. Em seguida, clique em Selecionar.
   Atenção: não consegue encontrar sua organização do Google Workspace?
   Isso significa que você não fez login em uma conta do Google Workspace. Alguns dos recursos descritos na documentação para desenvolvedores do Google Workspace só estão disponíveis para projetos associados a uma organização.
4. Clique em Criar. O console do Google Cloud direciona você para a página do Painel de Controle e seu projeto é criado em poucos minutos.

CLI da gcloud

Em um dos seguintes ambientes de desenvolvimento, acesse a CLI do Google Cloud (gcloud):

• Cloud Shell: Para usar um terminal online com a CLI gcloud já configurada, ative o Cloud Shell.
  Ativar Cloud Shell
• Shell local: para usar um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud.
  Para criar um projeto do Cloud, use o comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID definindo o ID do projeto que você quer criar.

Ativar o faturamento para o projeto do Cloud

Se você não conseguir vincular uma conta de faturamento, significa que não possui as permissões necessárias para fazer essa alteração. Para obter mais informações, consulte Permissões necessárias para ativar a cobrança.

Console do Google Cloud

1. No console do Google Cloud, acesse Faturamento. Clique Menu > Cobrança > Meus projetos.

   Acessar o faturamento dos meus projetos

2. Em Selecionar uma organização, escolha a organização associada ao seu projeto do Google Cloud.
3. Na linha do projeto, abra o menu Ações (), clique em Alterar faturamento e escolha a conta Faturamento na nuvem.
4. Clique em Definir conta.

CLI da gcloud

1. Para listar as contas de faturamento disponíveis, execute o seguinte comando:

   gcloud billing accounts list

2. Vincule uma conta de faturamento a um projeto do Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Substitua:

   • PROJECT_ID é o ID do projeto para o projeto Cloud para o qual você deseja habilitar o faturamento.
   • BILLING_ACCOUNT_ID é o ID da conta de faturamento a ser vinculado ao projeto do Google Cloud.

Ativar as APIs do Google Cloud

HTTP

1. No console do Google Cloud, habilite as APIs de complementos do Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run e Google Workspace.

   Ativar as APIs

2. Confirme se você está habilitando as APIs no projeto Cloud correto e clique em Próximo.

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

Apps Script

1. No console do Google Cloud, ative as APIs Vertex AI, Places, People e Google Chat.

   Ativar as APIs

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

3. Confirme se você está habilitando as APIs corretas e clique em Habilitar.

Obtenha uma chave da API Places da Plataforma Google Maps

1. No console do Google Cloud, acesse a página Google Maps Platform > Chaves e credenciais.

   Acessar "Chaves e credenciais"

2. A caixa de diálogo Vamos começar na Plataforma Google Maps mostra a chave de API recém-criada, uma string alfanumérica. Você vai precisar dessa string nas próximas seções.

Nota: Se você já tiver uma chave de API adequada, a lista de chaves de API será exibida, e não a caixa de diálogo Comece na Plataforma Google Maps. Selecione Mostrar chave para exibir a chave.

Crie uma conta de serviço no console do Google Cloud.

Crie uma nova conta de serviço com a função Vertex AI User seguindo estes passos:

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 desejar alterar o ID, modifique-o no campo ID da conta de serviço.
4. Opcional: Atribua funções à sua conta de serviço para conceder acesso aos recursos do seu projeto do Google Cloud. Para obter mais detalhes, consulte 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 obter mais detalhes, consulte Gerenciando 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 Conceder, alterar e revogar o acesso a recursos.

A conta de serviço aparece na página de contas de serviço. Em seguida, crie uma chave privada para a conta 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 baixar uma chave privada para a conta de serviço, siga estes passos:

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

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

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

   Seu novo par de chaves pública/privada foi gerado e baixado para o seu computador como um novo arquivo. Salve o arquivo JSON baixado como credentials.json em seu diretório de trabalho. Este arquivo é a única cópia desta chave. Para obter informações sobre como armazenar sua chave com segurança, consulte Gerenciando chaves de conta de serviço.

5. Clique em Fechar.

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

Configurar a tela de permissão OAuth

Os complementos do Google Workspace exigem uma configuração de tela de consentimento. Ao configurar a tela de permissão OAuth do seu complemento, você define o que o Google mostra aos usuários.

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

   Acessar Branding

2. Se você já configurou o Google Auth platform, você pode configurar as seguintes configurações da tela de consentimento OAuth em Branding, Audience e Data Access. Se você vir uma mensagem dizendo Google Auth platform ainda não 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 de suporte para que os usuários possam entrar em contato com você 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.

Implante o agente de IA ADK para concierge de viagens.

1. Se ainda não tiver feito isso, autentique-se com sua conta do Google Cloud e configure a CLI do Google Cloud para usar seu projeto do Google Cloud.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Substitua PROJECT_ID pelo ID do projeto na nuvem que você criou.

2. Baixe este repositório do GitHub

   Fazer download

3. No seu ambiente de desenvolvimento local preferido, extraia o arquivo compactado baixado e abra o diretório adk-samples/python/agents/travel-concierge.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/travel-concierge

4. Crie um bucket do Cloud Storage dedicado ao agente de IA do ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Substitua:

   1. CLOUD_STORAGE_BUCKET_NAME com um nome de bucket exclusivo que você quer usar.
   2. PROJECT_ID com o ID do projeto Cloud que você criou.
   3. PROJECT_LOCATION com a localização do projeto na nuvem que você criou.

5. Configure as variáveis de ambiente a seguir:

   export GOOGLE_GENAI_USE_VERTEXAI=1
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
   export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

   Substitua:

   1. PROJECT_ID pelo ID do projeto do Cloud que você criou.
   2. PROJECT_LOCATION com a localização do projeto na nuvem que você criou.
   3. PLACES_API_KEY com a string da chave de API que você criou.
   4. CLOUD_STORAGE_BUCKET_NAME com o nome do bucket que você criou.

6. Instale e implemente o agente ADK AI.

   uv sync --group deployment
   uv run python deployment/deploy.py --create

7. Recupere o número do projeto e o ID do mecanismo do último registro impresso como PROJECT_NUMBER e ENGINE_ID respectivamente, você precisará de ambos mais tarde para configurar seu projeto.

   Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

Analise o código de exemplo.

Opcionalmente, antes de configurar o projeto, reserve um momento para revisar e se familiarizar com o código de exemplo hospedado no GitHub.

Python

Ver no GitHub

Apps Script

Ver no GitHub

Criar e configurar o projeto

Python

1. Baixe este repositório do GitHub

   Fazer download

2. No ambiente de desenvolvimento local de sua preferência, extraia o arquivo compactado baixado e abra o diretório add-ons-samples/python/travel-adk-ai-agent.

   unzip add-ons-samples-main.zip
   cd add-ons-samples-main/python/travel-adk-ai-agent

3. Mova o arquivo de chave JSON credentials.json da conta de serviço baixada nas etapas anteriores para o diretório do projeto.

4. No console do Google Cloud, acesse Cloud Run:

   Acessar o Cloud Run

5. Clique em Escrever uma função.

6. Na página Criar serviço, configure sua função:

   1. No campo Nome da conta de serviço, insira travel-concierge-app.
   2. Na lista Região, selecione o local do projeto Cloud que você criou, PROJECT_LOCATION.
   3. Em URL do endpoint, clique em .
   4. Na lista Ambiente de execução, selecione a versão mais recente do Python.
   5. Na seção Autenticação, selecione Permitir acesso público.
   6. Na seção Contêineres, Volumes, Rede, Segurança, em Recursos:
      1. No campo Memória, selecione 1 GiB.
      2. No campo CPU, selecione 2.
   7. Clique em Criar e aguarde o Cloud Run criar o serviço. O console redireciona você para a guia Origem.

7. No seu ambiente de desenvolvimento local preferido, implante o código-fonte do projeto:

   gcloud run deploy travel-concierge-app --quiet --source . \
       --region PROJECT_LOCATION  \
       --function adk_ai_agent  \
       --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

   Substitua:

   1. PROJECT_LOCATION com a localização da função Cloud Run que você criou anteriormente.
   2. LOCATION com a localização do projeto do Google Cloud criado nas etapas anteriores, PROJECT_LOCATION.
   3. PROJECT_NUMBER com o número do projeto do agente de IA do Travel Concierge ADK implantado nas etapas anteriores.
   4. ENGINE_ID com o ID do mecanismo do Agente de IA ADK do Travel Concierge implantado nas etapas anteriores.
   5. BASE_URL com o URL do Endpoint que você copiou anteriormente.

Apps Script

Para criar um projeto do Apps Script e configurá-lo para usar o agente de IA do Travel Concierge ADK implantado:

1. Clique no botão a seguir para abrir o projeto Travel Concierge ADK AI Agent do Apps Script.
   Abrir o projeto

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

3. Dê um nome à sua cópia do projeto do Apps Script:

   1. Clique em Cópia do agente de IA do ADK do Travel Concierge.
   2. Em Título do projeto, digite Travel Concierge ADK AI Agent.
   3. Clique em Renomear.

4. No projeto do Apps Script, clique em Editor e mova o arquivo VertexAi.gs para cima até que ele fique acima do arquivo AgentHandler.gs usando a ação Mover arquivo para cima.

5. No seu projeto do Apps Script, clique em Configurações do projeto, clique em Editar propriedades do script e, em seguida, clique em Adicionar propriedade do script para adicionar as seguintes propriedades do script:

6. ENGINE_ID com o ID do mecanismo do Agente de IA ADK do Travel Concierge implantado nas etapas anteriores, ENGINE_ID.

7. LOCATION com a localização do projeto do Google Cloud criado nas etapas anteriores, PROJECT_LOCATION.

8. PROJECT_NUMBER com o número do projeto do agente de IA do ADK do Travel Concierge implantado nas etapas anteriores, PROJECT_NUMBER.

9. SERVICE_ACCOUNT_KEY com a chave JSON da conta de serviço baixada nas etapas anteriores, como { ... }.

10. Clique em Salvar propriedades do script.

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

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

13. Em Número do projeto GCP, cole o número do projeto do Agente de IA do Travel Concierge ADK implantado nas etapas anteriores, PROJECT_NUMBER.

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

Publicar no Gmail, Agenda, Drive, Documentos, Planilhas e Apresentações

Python

Use uma implantação de complemento do Google Workspace para instalar o projeto de amostra em todos os aplicativos do Google Workspace (exceto o Google Chat) e ativar os testes.

1. No ambiente de desenvolvimento local de sua preferência, abra o arquivo deployment.json da origem do código do projeto e substitua todas as ocorrências de $BASE_URL pelo valor de BASE_URL, o URL do endpoint que você copiou nas etapas anteriores.

2. Crie uma implantação de complemento do Google Workspace chamada travel-concierge-addon:

   gcloud workspace-add-ons deployments create travel-concierge-addon \
       --deployment-file=deployment.json

3. Instale a implantação do complemento do Google Workspace:

   gcloud workspace-add-ons deployments install travel-concierge-addon

Apps Script

Instale o projeto do Apps Script em todos os aplicativos do Google Workspace (exceto o Google Chat) para ativar o teste.

1. No projeto do Apps Script, clique em Implantar > Testar implantações e em Instalar.

O complemento agora pode ser acessado nas barras laterais do aplicativo Google Workspace.

Implantar no Chat

Python

Instale o projeto de exemplo no Chat usando o URL do endpoint para habilitar os testes.

1. No console, pesquise por Google Chat API, clique em Google Chat API, depois em Gerenciar e em Configuração.

   Acesse a página de configuração da API do Google Chat

2. Configure o aplicativo de bate-papo:

   1. No campo Nome do aplicativo, insira Travel ADK AI Agent.
   2. No campo URL do Avatar, insira https://goo.gle/3SfMkjb.
   3. No campo Descrição, use Travel ADK AI Agent.
   4. Em Configurações de conexão, selecione URL do endpoint HTTP.
   5. Em Gatilhos, selecione Usar um URL de endpoint HTTP comum para todos os gatilhos.
   6. No campo URL do endpoint HTTP, cole o URL do endpoint que você copiou anteriormente, BASE_URL.
   7. Registre um comando rápido que o aplicativo Chat totalmente implementado usa:
      1. Em Comandos, clique em Adicionar um comando.
      2. Em ID do comando, digite 1.
      3. Em Descrição, digite Reset session.
      4. Em Tipo de comando, selecione Comando rápido.
      5. Em Nome, digite Reset session.
      6. Clique em Concluído. O comando rápido está registrado e listado.
   8. Em Visibilidade, selecione Disponibilizar este app de chat para pessoas e grupos específicos no domínio do Workspace e digite seu endereço de e-mail.
   9. Em Registros, selecione Registrar erros no Logging.
   10. Clique em Salvar.

Apps Script

Instale o projeto do Apps Script no Chat usando o ID da implantação principal para ativar os testes.

1. No projeto do Apps Script, clique em Implantar > Testar implantações e, em seguida, Copiar em ID da implantação principal.

2. No console, pesquise por Google Chat API, clique em Google Chat API, depois em Gerenciar e em Configuração.

   Acesse a página de configuração da API do Google Chat

3. Configure o aplicativo de bate-papo:

   1. No campo Nome do aplicativo, insira Travel ADK AI Agent.
   2. No campo URL do Avatar, insira https://goo.gle/3SfMkjb.
   3. No campo Descrição, use Travel ADK AI Agent.
   4. Em Configurações de conexão, selecione Apps Script.
   5. No campo ID de implantação, cole o ID de implantação principal que você copiou anteriormente.
   6. Registre um comando rápido que o aplicativo Chat totalmente implementado usa:
      1. Em Comandos, clique em Adicionar um comando.
      2. Em ID do comando, digite 1.
      3. Em Descrição, digite Reset session.
      4. Em Tipo de comando, selecione Comando rápido.
      5. Em Nome, digite Reset session.
      6. Clique em Concluído. O comando rápido está registrado e listado.
   7. Em Visibilidade, selecione Disponibilizar este app de chat para pessoas e grupos específicos no domínio do Workspace e digite seu endereço de e-mail.
   8. Em Registros, selecione Registrar erros no Logging.
   9. Clique em Salvar.

O app agora pode ser acessado no Google Chat.

1. Abra o Google Chat.

   Acessar o Google Chat

2. Crie um espaço para mensagens diretas no chat:

   1. Clique em Novo chat.
   2. Digite e selecione o aplicativo Travel ADK AI Agent na pesquisa.
   3. Na caixa de diálogo Install app, clique em Instalar app.
   4. A caixa de diálogo Install app fecha e o espaço de bate-papo DM recém-criado é selecionado.

O app Chat está pronto para responder a mensagens.

Testar o agente

1. Abra o Gmail.

   Acessar o Gmail

2. Envie o seguinte e-mail para você mesmo:

   • Assunto: You need to travel to Paris
   • Body: Please be there between 11/25/2025 and 11/30/2025!

3. Abra o complemento Travel ADK AI Agent na barra lateral.

4. Clique em Conceder permissões para concluir a configuração do complemento.

5. Clique em Enviar após configurar a seguinte solicitação para o agente:

   • Mensagem: Please help me plan this travel!
   • Contexto:selecione E-mail atual

   A barra lateral é atualizada com a resposta do agente.

   

6. Clique em Abrir chat para ser redirecionado ao espaço de MD do Chat.

7. Clique em + > Redefinir sessão.

   Você vai receber uma nova mensagem confirmando que a ação foi concluída: OK, let's start from the beginning, what can I help you with?

8. Envie a mensagem Give me ideas.

   Você recebe novas mensagens com a resposta do agente.

   

9. Envie a mensagem I want to go there! após carregar uma foto de qualquer local, como a Torre Eiffel.

   Você recebe novas mensagens com a resposta do agente.

   

Nota: O complemento Agente de IA ADK para Viagens também pode ser aberto na barra lateral do Calendário, Drive, Documentos, Planilhas e Apresentações, de forma semelhante ao Gmail.

Limitações

HTTP

Em outros apps do Google Workspace que não sejam o Chat, o agente de IA tem as seguintes limitações:

• É síncrono:as barras laterais só podem ser atualizadas em resposta às interações do usuário. Portanto, as respostas do agente de IA são exibidas somente após a conclusão total (sem streaming).

• Pode expirar: As atualizações da barra lateral expiram quando demoram mais do que alguns minutos para serem concluídas.

Essas limitações não existem no Chat.

Apps Script

Em todos os aplicativos do Google Workspace, o agente de IA chama as APIs REST da Vertex AI usando UrlFetchApp, o que causa as seguintes limitações:

• É síncrono: As respostas do agente de IA são retornadas somente após a conclusão completa (sem streaming).

• Pode expirar o tempo limite: As solicitações do agente de IA expiram quando levam mais de um minuto para serem concluídas.

Personalização

Essa solução é compatível com agentes de IA do ADK hospedados no Vertex AI Agent Engine, um subconjunto das interfaces de aplicativos do Google Workspace, e renderizações de respostas específicas para as respostas do exemplo de concierge de viagens. A solução usa um framework extensível, então é possível personalizá-la modificando os seguintes arquivos:

Python

• main.py: Define as principais interfaces de usuário e a lógica de interação do usuário (manipuladores de eventos do Google Workspace). Uma extensão típica seria ativar os documentos do Drive como um recurso de contexto para o aplicativo Drive, semelhante ao que é feito com mensagens do Gmail para o aplicativo Gmail.

• vertex_ai.py: Gerencia as sessões, respostas e erros do agente de IA, e define interfaces específicas do Vertex AI para implementar suporte às interações do agente e à renderização das respostas. Extensões típicas incluiriam a adição de suporte para múltiplas sessões em conversas separadas entre usuários, além de outras plataformas de gerenciamento de agentes de IA.

• agent_handler.py: Implementa interfaces específicas do Vertex AI definidas em vertex_ai.py nos casos específicos de aplicativos de bate-papo e não bate-papo. Uma extensão típica seria adicionar botões para que os usuários enviem feedback sobre as respostas do agente de IA.

• google_workspace.py: Implementa interações de plataforma de gerenciamento de agentes não IA usando chamadas de API. Neste exemplo, são utilizadas apenas as APIs do Google Workspace para coletar detalhes contextuais e executar ações. Uma extensão típica seria adicionar funções para recuperar dados comerciais do Google Agenda ou de um sistema de Gestão de Relacionamento com o Cliente (CRM).

• travel_agent_ui_render.gs::implementa renderizações de resposta específicas do concierge de viagens para os subagentes e aplicativos do Workspace. As extensões típicas seriam adicionar suporte para novas renderizações de resposta para mostrar graficamente opções de voos e outros agentes de IA.

Apps Script

• Code.gs: Define as principais interfaces de usuário e a lógica de interação do usuário (manipuladores de eventos do Google Workspace). Uma extensão típica seria habilitar o recurso de documentos do Drive como contexto para o aplicativo Drive, semelhante ao que é feito com as mensagens do Gmail para o aplicativo Gmail.

• VertexAi.gs::gerencia as sessões, respostas e erros do agente de IA e define interfaces específicas da Vertex AI para implementar e oferecer suporte a interações e renderizações de respostas do agente. Extensões típicas seriam adicionar suporte a várias sessões para conversas separadas de usuários e outras plataformas de gerenciamento de agentes de IA.

• AgentHandler.gs:implementa interfaces específicas da Vertex AI definidas em VertexAi.gs nos casos específicos de aplicativos de chat e não chat. Uma extensão típica seria adicionar botões para que os usuários enviassem feedback sobre as respostas do agente de IA.

• GoogleWorkspace.gs::implementa interações de plataforma de gerenciamento de agentes não relacionados à IA usando chamadas de API. Apenas as APIs do Google Workspace são usadas neste exemplo para coletar detalhes de contexto e realizar ações. Uma extensão típica seria adicionar funções para recuperar dados comerciais da Agenda Google ou de um sistema de gestão de relacionamento com o cliente (CRM).

• TravelAgentUiRender.gs::implementa renderizações de resposta específicas do concierge de viagens para os subagentes e aplicativos do Workspace. As extensões típicas seriam adicionar suporte para novas renderizações de resposta para mostrar graficamente opções de voos e outros agentes de IA.

Limpar

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

Atenção: 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 o projeto inteiro.

Se você planeja explorar vários tutoriais e guias de início rápido, reutilizar projetos pode ajudá-lo a evitar exceder os limites de cota de projetos.

1. No console do Google Cloud, acesse a página Gerenciar recursos. Clique Menu > IAM e Administração > Gerenciar recursos.

   Ir para o Gerenciador de Recursos

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 Desligar para excluir o projeto.

Temas relacionados

• Verificar a veracidade de declarações com um agente de IA do ADK e um modelo do Gemini
• Integrar conceitos fundamentais de IA em aplicativos de bate-papo
• Crie um aplicativo de bate-papo como um complemento do Google Workspace usando o Apps Script.