1. Introdução
Os modelos de IA generativa são ótimos para raciocinar, mas não têm contexto institucional. Se um executivo perguntar a um agente de IA "Qual é nossa receita do primeiro trimestre?", o agente poderá encontrar dezenas de tabelas chamadas "receita" no data lake. Alguns são relatórios financeiros rigorosos, outros são estimativas de marketing em tempo real e muitos são sandboxes provavelmente obsoletos.
Sem um embasamento explícito, um agente de IA seleciona uma tabela com base na semelhança de nomes, o que leva a respostas convincentes, mas erradas, derivadas de dados não verificados.
Este codelab faz parte de uma série de duas partes que mostra como criar um agente de IA que segue as regras de governança.
Nesta primeira parte, você vai criar uma base de dados. Você vai configurar um data lake realista e "bagunçado" no BigQuery, aplicar tags de metadados rígidas (aspectos do Knowledge Catalog) para diferenciar dados válidos de ruídos e usar a CLI do Antigravity (AGY) para testar localmente se o agente segue estritamente suas regras de governança de dados.
Leia a segunda parte desta série, que aborda como implantar o protótipo do agente local em um aplicativo da web seguro e de nível empresarial usando o Protocolo de Contexto de Modelo (MCP) e o Cloud Run. 👉 Leia a Parte 2
O que você vai aprender
- Implantar um data lake realista de várias camadas usando um script de configuração.
- 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 localmente usando a CLI do AGY antes de escrever qualquer código do aplicativo.
O que é necessário
- Ter um projeto do Google Cloud com o faturamento ativado.
- Acesso ao Google Cloud Shell (a CLI do AGY já vem pré-instalada no Cloud Shell).
- Noções básicas e familiaridade com o BigQuery e o Knowledge Catalog.
Principais conceitos
- Knowledge Catalog: o serviço gerenciado unificado de gerenciamento de metadados. Nós o usamos para enriquecer metadados técnicos (esquemas) com contexto de negócios (governança).
- Tipo de aspecto: um modelo de metadados estruturados. Ao contrário das tags de texto livre, os aspectos aplicam uma tipagem forte (tipos enumerados, booleanos), o que os torna confiáveis para avaliação por máquinas.
2. Configuração e requisitos
Iniciar o Cloud Shell
Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.
No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:
O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:
Essa máquina virtual contém todas as ferramentas para desenvolvedores necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.
Inicializar o ambiente
Abra o Cloud Shell e defina as variáveis do projeto para garantir que todos os comandos sejam direcionados à infraestrutura correta.
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
Ativar APIs
Ative os serviços necessários do Google Cloud para executar a instrução a seguir.
gcloud services enable \
bigquery.googleapis.com \
dataplex.googleapis.com
Clonar o repositório
Acesse o código de infraestrutura e os scripts de automação no repositório do GitHub. Para economizar espaço em disco no Cloud Shell, vamos baixar apenas a pasta específica necessária para este laboratório.
# 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 we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context
Criar o data lake "bagunçado"
Os ambientes de dados do mundo real raramente são limpos. Para simular a realidade, precisamos de uma combinação de data marts "oficiais" e tabelas de "sandbox" não confiáveis.
Vamos usar 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 vai criar três conjuntos de dados do BigQuery (
finance_mart,marketing_prod,analyst_sandbox) e preencher as tabelas com dados de amostra.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
Ponto de verificação: agora você tem um data lake totalmente preenchido, mas sem governança. Para uma IA, todas as tabelas são iguais.
3. Como criar o modelo de governança de dados (tipo de aspecto)
Agora, vamos definir algumas regras de governança de dados. No Knowledge Catalog, isso é feito criando um tipo de aspecto, que é um modelo de metadados reutilizável e fortemente tipado.
Vamos registrar esse modelo usando a CLI gcloud para que você possa ver como ele é definido.
Inspecionar o esquema de aspecto
Exiba o conteúdo de aspect_template.json para ver a definição do esquema.
cat aspect_template.json
Ele vai mostrar 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 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 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 governance agents." \
--display-name="Official Data Product Spec" \
--metadata-template-file-name="aspect_template.json"
4. Aplicar governança
Essa é a etapa crítica de engenharia. No momento, as tabelas finance_mart.fin_monthly_closing_internal e analyst_sandbox.tmp_data_dump_v2_final_real são idênticas a um LLM. Eles são apenas objetos com colunas.
Como engenheiro de governança, você precisa anexar um aspecto (um rótulo de metadados certificado) a essas tabelas para diferenciá-las. Em uma empresa real, você automatizaria isso usando pipelines de CI/CD. Vamos simular essa automação com scripts.
Gerar payloads de governança
As chaves de aspecto do Knowledge Catalog precisam ser globalmente exclusivas (prefixadas com o ID do projeto). O script ./generate_payloads.sh vai gerar dinamicamente os arquivos de metadados YAML.
chmod +x ./generate_payloads.sh
./generate_payloads.sh
Saída:
Isso cria uma pasta "./aspect_payloads" com quatro arquivos YAML, que definem os cenários de governança (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).
Aplicar aspectos com a CLI
Antes de executar o script, vamos analisar o que estamos aplicando para desmistificar o processo. Execute o comando a seguir para conferir a estrutura do payload de finanças internas:
cat aspect_payloads/fin_internal.yaml
O conteúdo a seguir vai aparecer.
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 esse YAML define explicitamente o contexto de negócios, como definir a flag is_certified: true e atribuir o nível GOLD_CRITICAL. Fornecer ao LLM regras claras e estruturadas para avaliação, em vez de simplesmente adivinhar com base nos nomes das tabelas.
Agora, execute o script do aplicativo. Isso itera pelas tabelas do BigQuery e executa o comando gcloud dataplex entries update para anexar esses metadados rígidos.
chmod +x ./apply_governance.sh
./apply_governance.sh
Verificação (opcional)
Antes de continuar, verifique se os metadados foram aplicados corretamente no console.
- Abra a página Knowledge Catalog no console do Google Cloud. Se você não encontrar "Knowledge Catalog" no menu de navegação à esquerda, use a barra de pesquisa na parte de cima da janela do console do Google Cloud, digite "Knowledge Catalog" e selecione o resultado em "Principais resultados" ou "Produtos e páginas".
- Pesquisar por
fin_monthly_closing_internal. A tabela do BigQuery vai aparecer nos resultados. Clique no nome da tabela para acessar a página de detalhes.
- Na página de detalhes da tabela, procure a seção Tags e aspectos opcionais na parte de baixo.
- Você vai encontrar o aspecto
official-data-product-spec. Confirme se os valores correspondem ao cenário "Gold Internal" que aplicamos.
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.
5. Configurar e criar um protótipo do agente
Antes de criar um aplicativo (o que faremos na Parte 2), vamos verificar nossa lógica de governança de dados localmente. Precisamos instalar o plug-in do Knowledge Catalog e configurar a habilidade do agente.
Instalar a extensão
No Cloud Shell, instale o plug-in do Knowledge Catalog. Ele vai pedir uma confirmação e os detalhes da configuraçã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 (por exemplo, "Preciso de dados seguros") em pesquisas técnicas estritas.
Inspecione o arquivo para entender o algoritmo que estamos ensinando à IA:
cat .agents/skills/knowledge_catalog_governance/SKILL.md
Observe que ele instrui explicitamente o modelo a seguir um loop estrito de Fase 1 (Verificação de Metadados) e Fase 2 (Execução de Consulta). O modelo precisa descobrir e verificar os metadados antes de criar qualquer SQL.
Iniciar o agente e testar cenários
Inicie a sessão da CLI do AGY. Ele vai descobrir e carregar automaticamente a habilidade do diretório .agents/skills.
agy
Observação: talvez você veja vários arquivos de contexto sendo carregados. Isso é normal. A CLI carrega a habilidade local para as regras específicas desse projeto, além das instruções padrão para o próprio plug-in do Knowledge Catalog.
Confirme a instalação
Digite /mcp para confirmar que o plug-in do Knowledge Catalog está ativo. O knowledge-catalog vai aparecer como um plug-in ativo com as ferramentas disponíveis.
/mcp
Resposta esperada:
MCP Servers
...
> ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
Cenários de teste (prototipagem)
Cole os comandos a seguir na sessão do agente em execução, um por um, para verificar se ele segue as regras.
- Cenário A (certificar os dados do CFO):
"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?"
Esperado: o agente descobre automaticamente seu projeto e região ativos usando as ferramentas dele, consulta fin_monthly_closing_internal porque ele corresponde semanticamente a GOLD_CRITICAL (preciso) e INTERNAL_ONLY (reunião do conselho) no aspecto e o recomenda.
- Cenário B (divulgação pública):
"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?"
Esperado: o agente precisa ignorar a tabela interna mensal e selecionar estritamente fin_quarterly_public_report, porque é o único recurso marcado como EXTERNAL_READY.
- Cenário C (necessidades operacionais):
"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?"
Esperado: o agente seleciona mkt_realtime_campaign_performance porque identifica a frequência de atualização de REALTIME_STREAMING, priorizando isso em relação ao nível GOLD_CRITICAL dos dados financeiros.
- Cenário D (experimentos em sandbox):
"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."
Esperado: o agente seleciona tmp_data_dump_v2_final_real porque ele corresponde semanticamente a BRONZE_ADHOC (dados brutos) e is_certified: false (ambiente de sandbox) no aspecto.
(Para sair da sessão do AGY, digite /exit ou /quit)
6. Parabéns! A seguir
Você criou uma base de dados controlada e provou que uma IA pode seguir estritamente suas regras de metadados usando um protótipo de CLI local.
Agora, você chegou a um checkpoint. Escolha a próxima etapa:
Opção A: quero continuar para a Parte 2 agora mesmo!
Se você quiser transformar esse protótipo local em um aplicativo da web seguro e de nível de produção usando o Protocolo de Contexto de Modelo (MCP) e o Cloud Run:
👉 Link para a Parte 2 do codelab
Opção B: vou fazer a Parte 2 depois ou só queria concluir a Parte 1.
Se você quiser parar por hoje e evitar custos de nuvem, limpe seus recursos.
Não se preocupe! Na Parte 2, vamos fornecer um "script de aceleração" que vai recriar completamente o ambiente da Parte 1 em apenas 2 minutos para que você possa continuar exatamente de onde parou.
👉 Prossiga para a seção de limpeza.
7. Limpeza (somente para a opção B)
Se você vai parar por aqui, destrua os recursos para evitar cobranças.
Destruir o data lake
Se você estiver na sessão da CLI do AGY, saia dela pressionando Ctrl+C duas vezes ou digitando /quit. Em seguida, execute os seguintes comandos:
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
Desinstalar o plug-in da CLI do AGY e remover arquivos locais
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos