Usar o agente da CLI do Gemini para testar o contexto de dados

Os agentes de IA podem raciocinar, mas começam sem conhecimento sobre sua empresa específica. Imagine perguntar a um agente: "Qual é nossa receita do primeiro trimestre?" Sem orientação, o agente pode escolher entre dezenas de tabelas chamadas "receita" nos seus bancos de dados, que variam de relatórios oficiais a dados de teste desorganizados. Se o agente escolher a tabela com o nome mais parecido, ele poderá retornar respostas convincentemente erradas com base em fontes não verificadas.

O enriquecimento de metadados é a solução para esse problema de contexto. Neste tutorial, você vai configurar aspectos que fornecem esse contexto e usar a CLI do Gemini para testar o contexto de dados e verificar se um agente pode fundamentar com precisão as respostas em dados confiáveis e certificados.

Objetivos

• Crie um data lake realista para testes.
• Use aspectos do Knowledge Catalog para rotular seus dados "ouro" e diferenciá-los dos dados de teste.
• Teste seu contexto de dados localmente com a CLI do Gemini.

Antes de começar

Antes de começar, faça o seguinte:

• Escolha um Google Cloud projeto para este tutorial.
• Confirme se o faturamento está ativado para o projeto.

Para concluir este tutorial, você também precisa ter um entendimento básico do BigQuery, do Knowledge Catalog e do Terraform.

Preparar o ambiente

Este tutorial usa o Google Cloud Shell, um ambiente de linha de comando executado na nuvem.

1. No console Google Cloud , clique em Ativar Cloud Shell na barra de ferramentas no canto superior direito. O provisionamento e a conexão do ambiente podem levar alguns instantes.

2. No Cloud Shell, defina as variáveis PROJECT_ID e REGION para que todos os comandos futuros sejam direcionados ao seu projeto Google Cloud específico.

   export PROJECT_ID=$(gcloud config get-value project)
   gcloud config set project $PROJECT_ID
   export REGION="us-central1"
   

3. Ative os serviços Google Cloud necessários.

   gcloud services enable \
     artifactregistry.googleapis.com \
     bigqueryunified.googleapis.com \
     cloudaicompanion.googleapis.com \
     cloudbuild.googleapis.com \
     cloudresourcemanager.googleapis.com \
     datacatalog.googleapis.com \
     run.googleapis.com
   

4. Clone o repositórioGoogle Cloud DevRel Demos.

   Faça o download do código e dos scripts de infraestrutura no GitHub. Use um checkout esparso para extrair apenas a pasta específica necessária para este tutorial.

   # Perform a shallow clone to get only the latest repository structure without the full history
   git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
   cd devrel-demos
   
   # Specify and download only the folder you need for this tutorial
   git sparse-checkout set data-analytics/governance-context
   cd data-analytics/governance-context
   

Criar o data lake

Para tornar as coisas realistas, você precisa de uma mistura de dados oficiais e não confiáveis. Use o Terraform e os arquivos de configuração pré-configurados do repositório do tutorial para fazer isso rapidamente.

A configuração do Terraform processa duas tarefas:

• Configura os tipos de aspectos do Knowledge Catalog (modelos de metadados), os conjuntos de dados e as tabelas do BigQuery, incluindo finance_mart.fin_monthly_closing_internal e analyst_sandbox.tmp_data_dump_v2_final_real.
• Carrega dados de amostra nas tabelas.

1. Abra e inicialize o diretório terraform.

   cd terraform
   terraform init
   

2. Aplique a configuração. Isso pode levar até um minuto.

   terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
   

Agora você tem um data lake não gerenciado. Para um agente de IA, as tabelas no data lake parecem exatamente iguais, já que são apenas objetos com colunas. Para corrigir isso, aplique a governança na próxima etapa.

Aplicar governança

Essa é a parte mais importante da configuração. No momento, as duas tabelas parecem idênticas para um agente de IA. Para diferenciá-los, aplique aspectos, que são como rótulos de metadados certificados que fornecem ao agente o contexto necessário. Nesta seção, você vai usar dois scripts: um para gerar os metadados e outro para aplicá-los às tabelas.

Gerar payloads de governança

O Terraform já configurou os tipos de aspecto. Agora você precisa gerar os dados para preenchê-los.

Execute o script ./generate_payloads.sh para criar um diretório aspect_payloads/. O diretório contém quatro arquivos YAML que definem diferentes cenários de governança, que você vai aplicar na próxima etapa.

Volte para a raiz do diretório do tutorial e execute o script ./generate_payloads.sh:

cd ..
chmod +x ./generate_payloads.sh
./generate_payloads.sh

Aplicar aspectos

1. Antes de executar o script apply_governance.sh, confira os dados que serão anexados às suas tabelas. Execute o comando a seguir para conferir os metadados definidos para seus dados financeiros internos:

   cat aspect_payloads/fin_internal.yaml
   

   O arquivo YAML define o contexto comercial da tabela:

   your-project-id.us-central1.official-data-product-spec:
     data:
       product_tier: GOLD_CRITICAL
       data_domain: FINANCE
       usage_scope: INTERNAL_ONLY
       update_frequency: DAILY_BATCH
       is_certified: true
   

   Observe como isso marca explicitamente os dados como is_certified: true e atribui a eles o nível GOLD_CRITICAL. Isso fornece ao agente de IA regras claras e estruturadas para seguir.

2. Execute o script apply_governance.sh. Esse script itera pelas tabelas do BigQuery e usa a CLI gcloud para "marcar" os metadados dos payloads YAML em cada tabela.

   chmod +x ./apply_governance.sh
   ./apply_governance.sh
   

Verificar os metadados

Antes de continuar, verifique se o script aplicou os aspectos corretamente.

1. Abra a página Knowledge Catalog no console do Google Cloud . Use a barra de pesquisa na parte de cima para encontrá-lo.
2. Pesquisar por fin_monthly_closing_internal. Selecione o nome da tabela nos resultados para abrir a página de detalhes.
3. Na seção Tags e aspectos opcionais, encontre o aspecto official-data-product-spec. Confirme se os valores correspondem ao cenário "Ouro interno" que você aplicou.

Agora você usou os metadados para diferenciar essas tabelas e deu ao seu agente de IA uma maneira de fazer o mesmo.

Testar o contexto de dados com a CLI do Gemini

Antes de criar um aplicativo da Web completo, teste sua lógica de governança localmente usando um ambiente do Protocolo de Contexto de Modelo (MCP, na sigla em inglês). Nessa configuração, a CLI do Gemini atua como o cliente (a interface com que você conversa) e a extensão do Knowledge Catalog atua como o servidor local.

Instalar a extensão do Knowledge Catalog

No Cloud Shell, instale a extensão do Knowledge Catalog.

export DATAPLEX_PROJECT="${PROJECT_ID}"

gemini extensions install https://github.com/gemini-cli-extensions/dataplex

Definir regras

O arquivo de configuração GEMINI.md tem uma lógica que transforma regras declarativas, como "Preciso de dados seguros", em pesquisas precisas que retornam apenas tabelas com os rótulos de governança corretos.

No momento, o arquivo de configuração é apenas um modelo. É necessário adicionar seu ID de projeto Google Cloud específico às regras para que, ao executar a CLI, ela direcione corretamente os dados governados.

1. Adicione seu PROJECT_ID ao arquivo de configuração.

   envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md
   

2. Para verificar suas mudanças e entender como o contexto de dados funciona, dê uma olhada rápida no arquivo GEMINI.md:

   cat GEMINI.md
   

   O arquivo divide as regras em Fase 1 e Fase 2. Isso impõe uma ordem estrita de operações. Primeiro, o agente precisa procurar os rótulos de governança corretos (Fase 1) antes de poder acessar os dados (Fase 2). Essa lógica de "pesquisa primeiro" impede que o agente adivinhe nomes de tabelas ou crie respostas com base em fontes não verificadas.

   Verifique se a Fase 2 contém o ID do projeto Google Cloud real. Se isso não estiver correto, o agente não saberá onde procurar seus dados.

Iniciar a CLI do Gemini e testar cenários

Inicie uma nova sessão do Gemini. Como você está na pasta do projeto, a CLI detecta e carrega automaticamente o GEMINI.md local como o contexto do sistema.

gemini

Observação: vários arquivos de contexto podem ser carregados (por exemplo, GEMINI.md e outros). Isso é normal. A CLI carrega o GEMINI.md local para as regras específicas deste projeto, além das instruções padrão para a própria extensão do Knowledge Catalog.

Confirme a instalação

Confirme se a extensão do Knowledge Catalog está ativa. dataplex vai aparecer na lista de ferramentas do servidor MCP configurado.

/mcp desc

Faça um teste

Agora é hora de ver o contexto dos seus dados em ação. Cole esses comandos na CLI um por um.

Dica: a CLI pede permissão para usar as ferramentas dela. Selecione "2. Permitir ferramenta para esta sessão" para não precisar aprovar cada etapa.

Cenário 1: encontrar dados padrão "Ouro"

Confira se a CLI do Gemini consegue encontrar os dados mais confiáveis para uma reunião de diretoria importante.

We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?

A CLI precisa ignorar os dados brutos e encontrar fin_monthly_closing_internal. Para isso, ela compara sua solicitação de dados "finalizados" e "confidenciais" com as tags GOLD_CRITICAL e INTERNAL_ONLY que você aplicou anteriormente.

Cenário 2: divulgação pública

Imagine que você quer compartilhar dados externamente. Você quer garantir que a CLI não deixe escapar nenhum segredo interno.

I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?

Mesmo que a tabela interna tenha o máximo de detalhes, a CLI precisa ignorá-la. Ele vai direcionar você para fin_quarterly_public_report porque é a única tabela marcada como EXTERNAL_READY.

Cenário 3: necessidades operacionais em tempo real

Os cientistas de dados geralmente precisam das informações mais recentes. Veja se a CLI do Gemini entende a diferença entre um lote diário e uma transmissão ao vivo.

My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?

A CLI vai encontrar mkt_realtime_campaign_performance. Ele identifica a frequência de atualização do REALTIME_STREAMING nos metadados.

Cenário 4: exploração do sandbox

Às vezes, "bom o suficiente" é melhor do que "perfeito". Verifique se a CLI do Gemini consegue encontrar os dados brutos do sandbox para algum trabalho experimental de ML.

I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment.

A CLI vai encontrar tmp_data_dump_v2_final_real. Ele sabe que essa é a escolha certa porque corresponde ao nível BRONZE_ADHOC e está explicitamente marcado com is_certified: false.

Quando terminar o teste, saia da sessão da CLI:

/quit

Limpar

Siga estas etapas para evitar cobranças recorrentes:

1. Destrua os recursos do Terraform.

   cd ~/devrel-demos/data-analytics/governance-context/terraform
   terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
   

2. Desinstale a extensão do Knowledge Catalog e remova os arquivos de demonstração locais.

   gemini extensions uninstall dataplex
   cd ~
   rm -rf ~/devrel-demos
   

Conclusão

Você criou uma base de dados sólida, aplicou um contexto estrito usando metadados e verificou se tudo funciona localmente usando a CLI do Gemini.