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 Google 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 planilhas do Google:

1. Agentes de IA para recursos de raciocínio sofisticados, multi-ferramentas e em várias 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

• Entender o que a solução faz.
• Entender como a solução é implementada.
• Implantar o agente de IA da Vertex AI.
• Configurar o script.
• Executar o script.

Sobre esta solução

A função personalizada do Planilhas é chamada de FACT_CHECK e funciona como uma solução completa. Ela 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.
• Raciocínio: 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 este exemplo, você precisa dos 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.
  • CLI do Google Cloud: para instalação, siga as instruções no site oficial do Google Cloud.

Prepare o ambiente

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

Criar um projeto na nuvem do Google

Console do Google Cloud

1. No console do Google Cloud, acesse o menu menu > IAM e administrador > Criar um projeto.

   Acessar "Criar um projeto"

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

   Opcional: para editar o ID do projeto, clique em Editar. O ID do projeto não pode ser alterado depois que o projeto é criado. Portanto, escolha um ID que atenda às suas necessidades durante a vida útil do projeto.

3. No campo Local, clique em Procurar para mostrar possíveis locais para o seu projeto. Em seguida, clique em Selecionar.
4. Clique em Criar. O console do Google Cloud navega até a página "Painel", e o projeto é criado em alguns minutos.

CLI 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 na nuvem, 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 na nuvem

Console do Google Cloud

1. No console do Google Cloud, acesse Faturamento. Clique no menu > Faturamento > Meus projetos.menu

   Acessar o faturamento dos meus projetos

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

CLI 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 na nuvem para o qual você quer ativar o faturamento.
   • BILLING_ACCOUNT_ID é o ID da conta de faturamento a ser vinculada ao o 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 o 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 à 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 identidade temporária de conta de serviço.
7. Clique em Concluído. 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 à 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. 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 o menu menu > IAM e administrador > Contas de serviço.

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

2. Selecione a 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 transferido por download como credentials.json no seu diretório de trabalho. Esse arquivo é a única cópia da chave. Para informações sobre 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 Cloud 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 na nuvem 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 compactado transferido por download 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 por um nome de bucket exclusivo que você quer usar.
   2. PROJECT_ID pelo ID do projeto na nuvem que você criou.
   3. PROJECT_LOCATION pelo local do projeto na nuvem 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 pelo nome do bucket que você criou.
   2. PROJECT_ID pelo ID do projeto na nuvem que você criou.
   3. PROJECT_LOCATION pelo local do projeto na nuvem 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

Opcionalmente, antes de criar a nova planilha, reserve um momento para analisar e se familiarizar com o exemplo de código hospedado no GitHub.

Ver no GitHub

Criar e configurar em uma nova planilha

1. Para fazer uma cópia completa da planilha de exemplo do Planilhas, incluindo o projeto do Apps Script vinculado ao contêiner, clique no botão a seguir:

   Copiar planilha do Google Planilhas

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 Adicionar propriedade do script para adicionar as seguintes propriedades do script:

   1. LOCATION com o local do projeto na nuvem 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 transferida por download nas etapas anteriores, como { ... }.

4. Clique em Salvar propriedades do script.

Testar a função personalizada

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

Limpar

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

1. No console do Google Cloud, acesse a página Gerenciar recursos. Clique Menu 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 delete.
3. Na caixa de diálogo, digite o ID do projeto e clique em desligar para excluir o projeto.

Próximas etapas

• Planejar viagens com um agente de IA acessível no Google Workspace
• Criar agentes do Gemini Enterprise que são integrados aos repositórios de dados, APIs e complementos do Workspace
• Criar agentes da Vertex AI que são integrados aos repositórios de dados, APIs e complementos do Workspace
• Funções personalizadas no Planilhas
• Estender o Planilhas