Verificar a veracidade de declarações com um agente de IA do ADK e o modelo do Gemini

Nível de programação: avançado
Duração: 30 minutos
Tipo de projeto: função personalizada

Visão geral

Uma função personalizada de verificação de fatos para o Google Sheets, a ser usada como um projeto vinculado do Apps Script, com o auxílio de um...Vertex AI agente e modelo Gemini.

Este exemplo demonstra como você pode usar dois tipos poderosos de recursos de IA diretamente em suas planilhas do Google Sheets:

1. Agentes de IA para capacidades de raciocínio sofisticadas, com múltiplas ferramentas e várias etapas, usando agentes ADK implantados no Vertex AI Agent Engine.
2. Modelos de IA para capacidades avançadas de compreensão, geração e sumarização usando modelos Gemini da Vertex AI.

Objetivos

• Entenda o que a solução faz.
• Compreenda como a solução é implementada.
• Implante o agente Vertex AI.
• Configure o script.
• Execute o script.

Sobre esta solução

A função personalizada do Sheets é chamada FACT_CHECK e opera como uma solução de ponta a ponta. Analisa uma declaração, fundamenta sua resposta com base nas informações mais recentes da web e retorna o resultado no formato desejado:

• Uso:
  • =FACT_CHECK("Your statement here") para uma saída concisa e resumida.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") para um formato de saída específico.
• Motivo: Agente de IA do ADK do LLM Auditor (exemplo em Python).
• Formatação de saída: modelo do Gemini.

Essa solução solicita APIs REST da Vertex AI usando UrlFetchApp.

Arquitetura

O diagrama a seguir mostra a arquitetura dos recursos do Google Workspace e do Google Cloud usados pela função personalizada.

Pré-requisitos

Para usar esta amostra, você precisa atender aos seguintes pré-requisitos:

• Uma Conta do Google (as contas do Google Workspace podem exigir a aprovação do administrador).

• Um navegador web com acesso à internet.

• Pré-requisitos do agente do ADK do LLM Auditor

  • Python 3.11 ou mais recente: para instalação, siga as instruções no site oficial do Python.
  • Python Poetry: para instalação, siga as instruções no site oficial do Poetry (em inglês).
  • 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 Menu > IAM e administrador > Criar um projeto.

   Acessar "Criar um projeto"

2. No campo Nome do projeto, insira um nome descritivo.

   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 está conectado a uma conta do Google Workspace. Algumas das funcionalidades descritas na documentação para desenvolvedores do Google Workspace estão disponíveis apenas 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 na nuvem, use o comando gcloud projects create:

  gcloud projects create PROJECT_ID

  SubstituirPROJECT_ID Ao definir o ID do projeto que deseja criar.

Ativar a cobrança para o projeto na nuvem

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 em Menu > Faturamento > Meus projetos.

   Acessar o faturamento dos meus projetos

2. Em Selecione 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:

   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 a API Vertex AI

Console do Google Cloud

1. No console do Google Cloud, habilite a API Vertex AI.

   Ativar as APIs

2. Confirme se você está habilitando a API Vertex AI no projeto Cloud correto e clique em Próximo.

3. Confirme se você está ativando a API correta e clique em Ativar.

CLI da gcloud

1. Se necessário, defina o projeto atual do Cloud como aquele que você criou com o comando gcloud config set project:

   gcloud config set project PROJECT_ID

   Substitua PROJECT_ID pelo ID do projeto do projeto do Cloud que você criou.

2. Habilite a API Vertex AI com o comando gcloud services enable:

   gcloud services enable aiplatform.googleapis.com

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

Crie uma conta de serviço com a função 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 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 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.

A conta de serviço aparece na página da conta 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 Escolha 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 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. Esse arquivo é a única cópia da 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.

Implante o agente de IA do LLM Auditor ADK.

1. Caso ainda não o tenha feito, 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 ambiente de desenvolvimento local de sua preferência, extraia o arquivo baixado e abra o diretório adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. Crie um bucket do Cloud Storage dedicado ao agente 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ê deseja usar.
   2. PROJECT_ID pelo ID do projeto do Cloud que você criou.
   3. PROJECT_LOCATION com o local do projeto do Cloud que você criou.

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

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   Substitua:

   1. CLOUD_STORAGE_BUCKET_NAME com o nome do bucket que você criou.
   2. PROJECT_ID com o ID do projeto Cloud que você criou.
   3. PROJECT_LOCATION com o local do projeto do Cloud que você criou.

6. Instale e implemente o agente ADK a partir de um ambiente virtual.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Recupere o ID do agente; você precisará dele mais tarde para configurar a função personalizada.

   python3 deployment/deploy.py --list

Analisar o exemplo de código

Se quiser, antes de criar a nova planilha, revise e se familiarize com o exemplo de código hospedado no GitHub.

Ver no GitHub

Criar e configurar em uma nova planilha

1. Clique no botão a seguir e faça uma cópia completa da planilha de exemplo do Google Sheets, incluindo o projeto do Apps Script vinculado ao contêiner.

   Copiar uma planilha Google

2. Na planilha recém-criada, acesse Extensões > Apps Script.

3. No projeto do Apps Script, acesse 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:

   1. LOCATION com o local do projeto do Google Cloud criado nas etapas anteriores, como us-central1.
   2. GEMINI_MODEL_ID com o modelo Gemini que você deseja usar, como gemini-2.5-flash-lite.
   3. REASONING_ENGINE_ID com o ID do Agente ADK do Auditor LLM implantado nas etapas anteriores, como 1234567890.
   4. SERVICE_ACCOUNT_KEY com a chave JSON da conta de serviço baixada nas etapas anteriores, como { ... }.

4. Clique em Salvar propriedades do script.

Testar a função personalizada

1. Acesse a planilha recém-criada.
2. Mude as declarações na coluna A.
3. As fórmulas na coluna B são executadas e mostram os resultados da verificação de fatos.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, 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.

Próximas etapas

• Planeje viagens com um agente de IA acessível em todo o Google Workspace
• Funções personalizadas no Google Planilhas
• Extender o Google Planilhas