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 as Planilhas Google, usada como um projeto vinculado do Apps Script com tecnologia de um agente da Vertex AI e 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 das 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 > 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 os locais possíveis 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 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

Se não for possível vincular uma conta de faturamento, significa que você não tem as permissões necessárias para fazer essa mudança. Para mais informações, consulte Permissões necessárias para ativar o faturamento.

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

Console do Google Cloud

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

   Ativar as APIs

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

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. Ative a API Vertex AI com o comando gcloud services enable:

   gcloud services enable aiplatform.googleapis.com

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

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 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 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 conheça 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 das Planilhas 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 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, recomendamos que você 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

• Funções personalizadas no Planilhas Google
• Extensão das Planilhas Google