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 para testes.
  • Projetar e registrar modelos de metadados personalizados (tipos de aspecto) no Knowledge Catalog para distinguir produtos de dados oficiais de tabelas de sandbox brutas.
  • Verificar as regras de governança de dados 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

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. Noconsol do Google Cloud, clique em Ativar o Cloud Shell na barra de ferramentas no canto superior direito. Google Cloud 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 osserviç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 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

Criar um data lake de exemplo

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

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.

Criar o modelo de governança de dados (tipo de aspecto)

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 conferir como ele é definido.

Inspecionar o esquema 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

Execute o seguinte comando gcloud 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"

Aplicar a governança de dados

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 a um agente de IA. Elas 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ê simula essa automação com scripts.

Gerar payloads de governança de dados

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

Aplicar aspectos usando a CLI

  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 metadados

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

  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 de serviço

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 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 CLI do Antigravity e testar cenários

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

Confirme a instalação

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

Faça um teste

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

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

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: divulgação pública

Finja 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: necessidades operacionais 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: exploração de sandbox

Às vezes, "bom o suficiente" é melhor do que "perfeito". Confira se a CLI do Antigravity pode encontrar os dados brutos de 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 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 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

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

A seguir