Usar a CLI do Antigravity para testar o contexto de dados

A otimização de metadados no Knowledge Catalog (antigo Dataplex Universal Catalog) permite fornecer contexto de dados estruturados para que os agentes de IA possam embasar as respostas em fontes confiáveis e certificadas. Neste tutorial, você vai anexar aspectos personalizados a tabelas de amostra do BigQuery e usar a CLI Antigravity para testar como um agente de IA aplica suas regras de governança.

Objetivos

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

Antes de começar

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

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

Preparar o ambiente

Neste tutorial, usamos o Shell doGoogle Cloud , um ambiente de linha de comando executado na nuvem. A CLI do Antigravity (agy) já vem pré-instalada no Shell do Google Cloud .

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

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

    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 do 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 repositório de demonstrações do DevRel doGoogle Cloud .

    Baixe o código e os scripts de infraestrutura do 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 do mundo real raramente são limpos. 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 vão de relatórios oficiais a dados de teste brutos. Se o agente escolher a tabela com o nome mais parecido, ele poderá retornar respostas convincentes, mas erradas, com base em fontes não verificadas.

Para simular esse cenário, você precisa de uma combinação de data marts "oficiais" e tabelas de "sandbox" não confiáveis. Use 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 com dados de amostra:

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

Agora você tem um data lake totalmente preenchido, mas sem governança. Para um agente de IA, todas as tabelas são 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ê vai registrar esse modelo usando a CLI gcloud para ver como ele é definido.

Inspecionar o esquema do modelo de aspecto

Mostre o conteúdo de aspect_template.json para ver 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 o nível de importância (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 seguinte comando gcloud para registrar esse modelo no registro do Catálogo de Conhecimento:

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 às tabelas do data lake

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

Para diferenciá-las, você aplica aspectos, que anexam rótulos de metadados certificados a essas tabelas. Em uma empresa real, você automatizaria isso com pipelines de CI/CD. Neste tutorial, você vai simular 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 que definem 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 ver 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 o nível GOLD_CRITICAL. Isso dá 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 console do Google Cloud

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

  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 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" que você aplicou.

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, verifique sua lógica de governança de dados localmente com a CLI do Antigravity. Para 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 de 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 qualquer instrução SQL. Essa lógica de priorização de pesquisa 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

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 vai 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 ver o contexto de dados em ação. Cole esses comandos na sessão da CLI do Antigravity, um por um.

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

Veja se a CLI do Antigravity consegue 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 deve pular os dados brutos e encontrar fin_monthly_closing_internal. Para isso, ele faz a correspondência entre sua solicitação de dados "finalizados" e "confidenciais" e 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 vaze 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 mais detalhes, a CLI precisa ignorá-la. Ele deve apontar 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. Veja 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 vai encontrar mkt_realtime_campaign_performance. Ele identifica a frequência de atualização do REALTIME_STREAMING nos metadados.

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

Às vezes, "bom o suficiente" é melhor do que "perfeito". Verifique se a CLI do Antigravity consegue encontrar os dados brutos do sandbox para um 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. Se você estiver na sessão da CLI do Antigravity, saia pressionando Ctrl+C duas vezes ou digitando /quit.

  2. Execute o script de limpeza para destruir as tabelas do BigQuery, os conjuntos de dados e os tipos de aspecto 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