Usar a CLI do Antigravity para testar o contexto de dados

Os agentes de IA podem raciocinar, mas começam com conhecimento zero 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 confusos. 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ê configura aspectos que fornecem esse contexto e usa a CLI do Antigravity 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

• Implantar um data lake realista e de várias camadas no BigQuery para testes.
• Projetar e registrar modelos de metadados personalizados (tipos de aspectos) no Knowledge Catalog para distinguir produtos de dados oficiais de tabelas de sandbox brutas.
• Verificar as regras de governança de dados e a fundamentação do agente de IA usando a CLI do Antigravity (agy).

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

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

Preparar o ambiente

Este tutorial usa o Google Cloud Shell, um ambiente de linha de comando executado na nuvem. A CLI do Antigravity (agy) já está instalada no Google Cloud Shell.

1. No Google Cloud consol do Cloud, clique em Ativar o 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 Google Cloud projeto 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 necessários Google Cloud .

   gcloud services enable \
     artifactregistry.googleapis.com \
     bigquery.googleapis.com \
     dataplex.googleapis.com \
     aiplatform.googleapis.com \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     iam.googleapis.com
   

4. Clone o Google Cloud repositório de demonstrações do DevRel.

   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
   

Implantar um data lake de amostra no BigQuery

Os ambientes de dados reais raramente são limpos. Para simular a realidade, você precisa de uma combinação de data marts "oficiais" e tabelas de "sandbox" não confiáveis.

Você usa um script de configuração para implantar os conjuntos de dados e as tabelas do BigQuery.

Torne o script de configuração executável e execute-o. Isso cria três conjuntos de dados do BigQuery (finance_mart, marketing_prod, analyst_sandbox) e preenche as tabelas deles com dados de amostra:

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

Agora você tem um data lake totalmente preenchido, mas não governado. Para um agente de IA, todas as tabelas são exatamente iguais.

Definir um tipo de aspecto personalizado no Knowledge Catalog

Agora, você define as regras da governança de dados. Para fazer isso no Knowledge Catalog, crie um tipo de aspecto, que é um modelo de metadados reutilizável e fortemente tipado.

Nesta seção, você registra esse modelo usando a CLI gcloud para ver como ele é definido.

Inspecionar o esquema do modelo de aspecto

Gere o conteúdo de aspect_template.json para conferir a definição do esquema:

cat aspect_template.json

Ele mostra a seguinte estrutura JSON:

{
  "name": "OfficialDataProductSpec",
  "type": "record",
  "recordFields": [
    {
      "name": "product_tier",
      "type": "enum",
      "enumValues": [
        { "name": "GOLD_CRITICAL", "index": 1 },
        { "name": "SILVER_STANDARD", "index": 2 },
        { "name": "BRONZE_ADHOC", "index": 3 }
      ],
      ...
    },
    {
      "name": "is_certified",
      "type": "bool",
      "...": "..."
    }
  ]
}

Observe como esse esquema aplica tipos de dados estritos, como enum para a camada de criticidade (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) e um bool para is_certified. Isso garante que os metadados permaneçam estruturados e legíveis por máquina.

Registrar o tipo de aspecto no Knowledge Catalog

Execute o comando gcloud a seguir para registrar esse modelo no registro do Knowledge Catalog:

gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --description="Defines the comprehensive profile of a data product for data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

Anexar aspectos de governança a tabelas de data lake

Essa é a etapa de engenharia crítica. No momento, a tabela finance_mart.fin_monthly_closing_internal e analyst_sandbox.tmp_data_dump_v2_final_real parecem idênticas para um agente de IA. Elas são apenas objetos com colunas.

Para diferenciá-las, aplique aspectos que anexem rótulos de metadados certificados a essas tabelas. Em uma empresa real, você automatizaria isso com pipelines de CI/CD. Neste tutorial, você simula essa automação com scripts.

Gerar os payloads de metadados de aspecto

As chaves de aspecto do Knowledge Catalog precisam ser globalmente exclusivas (prefixadas com o ID do projeto). O script ./generate_payloads.sh gera dinamicamente os arquivos de metadados YAML:

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

Isso cria um diretório aspect_payloads/ que contém quatro arquivos YAML definindo diferentes cenários de governança de dados (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Anexar aspectos a tabelas do BigQuery

1. Antes de executar o script, confira os dados que você está anexando às tabelas. Execute o comando a seguir para conferir os metadados dos seus dados financeiros internos:

   cat aspect_payloads/fin_internal.yaml
   

   O arquivo YAML define o contexto de negócios 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 define explicitamente o contexto de negócios, como definir is_certified: true e atribuir a camada GOLD_CRITICAL. Isso oferece ao agente de IA regras claras e estruturadas para avaliar em vez de adivinhar com base nos nomes das tabelas.

2. Execute o script do aplicativo. Esse script itera pelas tabelas do BigQuery e usa o comando gcloud dataplex entries update para anexar os payloads de metadados a cada tabela:

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

Verificar os aspectos aplicados no Google Cloud console

Antes de continuar, verifique se o script aplicou os aspectos corretamente no Google Cloud console:

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

Agora você confirmou que as tabelas do BigQuery tecnicamente idênticas (fin_monthly_closing_internal e tmp_data_dump_v2_final_real) são diferenciadas logicamente por metadados legíveis por máquina.

Testar o contexto de dados com a CLI do Antigravity

Antes de criar um aplicativo, você pode verificar a lógica de governança de dados localmente com a CLI do Antigravity. Para fazer isso, instale o plug-in do Knowledge Catalog e configure a habilidade do agente.

Instalar o plug-in do Knowledge Catalog

No Cloud Shell, instale o plug-in de serviço:

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Inspecionar a definição da habilidade do agente

A habilidade do agente é um arquivo de definição estático e reutilizável localizado em .agents/skills/knowledge-catalog-governance/SKILL.md. Ele contém a lógica que traduz regras humanas abstratas, como "Preciso de dados seguros", em pesquisas técnicas estruturadas.

Para verificar a configuração da habilidade e entender como o contexto de dados funciona, inspecione o arquivo SKILL.md:

cat .agents/skills/knowledge-catalog-governance/SKILL.md

Observe que ele instrui o modelo a seguir loops estritos da Fase 1 (verificação de metadados) e da Fase 2 (execução de consultas). O modelo precisa descobrir e verificar os metadados antes de criar instruções SQL. Essa lógica de pesquisa primeiro impede que o agente adivinhe nomes de tabelas ou alucine respostas de fontes não verificadas.

Iniciar a sessão da CLI do Antigravity

Inicie a sessão da CLI do Antigravity. Como você está na pasta do projeto, a CLI descobre e carrega automaticamente a habilidade do diretório .agents/skills:

agy

Observação: vários arquivos de contexto podem ser carregados. Isso é normal. A CLI carrega a habilidade local para as regras específicas do projeto, além das instruções padrão para o plug-in de serviço.

Verificar a instalação do plug-in na CLI

No prompt da CLI do Antigravity, confirme se o plug-in está ativo. Digite /mcp para listar as ferramentas e os plug-ins configurados:

/mcp

A saída precisa mostrar knowledge-catalog listado como um plug-in ativo com as ferramentas disponíveis:

MCP Servers ... >  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

Executar cenários de verificação de contexto de dados

Agora é hora de conferir o contexto de dados em ação. Cole esses prompts na sessão da CLI do Antigravity um por um.

**Dica**: se for solicitado a autorizar o uso da ferramenta, selecione "2. Sim, e sempre permitir 'knowledge-catalog/search_entries' nesta conversa" para testar sem precisar aprovar cada etapa.

Cenário 1: recuperar dados certificados de nível ouro

Confira se a CLI do Antigravity pode encontrar os dados mais confiáveis para uma reunião de diretoria de alto risco:

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. Ela faz isso combinando sua solicitação de dados "finalizados" e "confidenciais" com as tags GOLD_CRITICAL e INTERNAL_ONLY que você aplicou anteriormente.

Cenário 2: restringir a recuperação a dados aprovados externamente

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

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 mais detalhes, a CLI precisa ignorá-la. Ela precisa direcionar você para fin_quarterly_public_report, porque é a única tabela marcada como EXTERNAL_READY.

Cenário 3: recuperar dados de streaming em tempo real

Os cientistas de dados geralmente precisam das informações mais recentes. Confira se a CLI do Antigravity 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 precisa encontrar mkt_realtime_campaign_performance. Ela identifica a frequência de atualização REALTIME_STREAMING nos metadados.

Cenário 4: analisar dados de sandbox não certificados

Às vezes, "bom o suficiente" é melhor do que "perfeito". Confira se a CLI do Antigravity pode encontrar os dados de sandbox brutos 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 precisa encontrar tmp_data_dump_v2_final_real. Ela sabe que essa é a escolha certa porque corresponde à camada BRONZE_ADHOC e está marcada explicitamente com is_certified: false.

Quando terminar o teste, você poderá sair da sessão da CLI:

/quit

Limpar

Siga estas etapas para evitar cobranças recorrentes:

1. Se você estiver na sessão da CLI do Antigravity, saia da sessão pressionando Ctrl+C duas vezes ou digitando /quit.

2. Execute o script de limpeza para destruir as tabelas, os conjuntos de dados e os tipos de aspectos do Knowledge Catalog criados neste tutorial:

   chmod +x ./cleanup_data_lake.sh
   ./cleanup_data_lake.sh
   

3. Desinstale o plug-in de serviço e remova os arquivos de demonstração locais:

   agy plugin uninstall dataplex
   cd ~
   rm -rf ~/devrel-demos
   

A seguir

• Confira outros casos de uso do Knowledge Catalog.