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 checagem de fatos para o Google Planilhas que será usada como um projeto vinculado do Apps Script com tecnologia de um agente da Vertex AI e de um modelo do Gemini.

Este exemplo demonstra como usar dois tipos poderosos de recursos de IA diretamente nas suas planilhas Google:

1. Agentes de IA para recursos sofisticados de raciocínio com várias ferramentas e etapas usando agentes do ADK implantados no Vertex AI Agent Engine.
2. Modelos de IA para recursos avançados de compreensão, geração e resumo usando modelos do Gemini da Vertex AI.

Objetivos

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

Sobre esta solução

A função personalizada do Planilhas é chamada de FACT_CHECK e funciona como uma solução de ponta a ponta. Ele analisa uma declaração, fundamenta a resposta usando as informações mais recentes da Web e retorna o resultado no formato necessário:

• 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 da 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 instalar, siga as instruções no site oficial do Google Cloud.

Prepare o ambiente

Nesta seção, mostramos 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 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 ID 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.
4. Clique em Criar. O console do Google Cloud navega até a página "Painel", e seu projeto é criado em alguns minutos.

CLI da gcloud

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

• Cloud Shell: para usar um terminal on-line com a CLI gcloud já configurada, ative o Cloud Shell.
  Ativar o 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

Console do Google Cloud

1. No console do Google Cloud, acesse Faturamento. Clique em Menu menu > Faturamento > 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 (more_vert), clique em Mudar faturamento e escolha a conta do Cloud Billing.
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 do projeto do Cloud em que você quer ativar o faturamento.
   • BILLING_ACCOUNT_ID é o ID da conta de faturamento a ser vinculado ao projeto do Google Cloud.

Ativar a API Vertex AI

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 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.
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 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 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

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 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 do LLM Auditor

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 do Cloud que você criou.

2. Faça o download deste 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ê quer 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 pelo ID do projeto do Cloud que você criou.
   3. PROJECT_LOCATION com o local do projeto do Cloud que você criou.

6. Instale e implante o agente do ADK no 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ê vai 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 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 Adicionar propriedade do script para adicionar as seguintes propriedades:

   1. LOCATION com o local do projeto do Google Cloud criado nas etapas anteriores, como us-central1.
   2. GEMINI_MODEL_ID com o modelo do Gemini que você quer usar, como gemini-2.5-flash-lite.
   3. REASONING_ENGINE_ID com o ID do agente do ADK do LLM Auditor 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.

1. No console do Google Cloud, acesse a página Gerenciar recursos. Clique em Menu 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 delete.
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