Seu agente não sabe o que é um usuário ativo.

O número estava certo. A decisão, não.

A discussão costuma começar por uma pergunta que parece simples:

Quantos usuários ativos a empresa teve no mês passado?

A resposta geralmente já existe. Na verdade, existem várias.

Um time conta pessoas que executaram uma ação. Outro conta contas com qualquer atividade associada. Uma visão comercial consolida várias contas sob a mesma organização. Uma consulta operacional inclui usuários internos que agem em nome do cliente. Todas as queries rodam. Todos os números são defensáveis.

Só um deles serve para a decisão que a empresa precisa tomar.

Esse é o tipo de problema que desaparece em uma demo de IA. Conecte um agente ao banco, descreva as tabelas, peça um SQL e, em poucos segundos, ele devolve um número acompanhado de uma explicação convincente. A experiência parece inteligente porque a resposta é rápida, fluente e tecnicamente plausível.

Mas o agente não descobriu o significado de “usuário ativo”. Ele escolheu uma interpretação.

E quando a interpretação errada entra em produção, o impacto não fica restrito a um dashboard. Uma conta realmente ativa pode aparecer em uma lista de churn. A adoção de uma funcionalidade pode ser superestimada. Produto, Comercial e Financeiro podem operar com versões diferentes da mesma empresa. Um board pode comparar meses calculados com fronteiras de tempo incompatíveis. E, depois da primeira resposta contestada, a confiança no agente inteiro começa a cair.

Conectar um LLM ao banco resolve acesso. Não resolve significado.

O pior erro não é a query quebrar. É a query passar, o gráfico renderizar e ninguém perceber que a pergunta foi respondida com a definição errada.

A maioria das empresas não possui uma camada de dados.

Possui uma coleção de tabelas transacionais.

Existe uma diferença enorme entre as duas.

Um agente consegue consultar tabelas.

Mas só consegue responder corretamente quando existe uma camada de significado entre o banco de dados e a IA.

Semântica não é documentação. É infraestrutura.

O agente não consulta apenas dados. Ele escolhe definições.

Toda pergunta analítica esconde uma sequência de decisões.

Quem conta como usuário? Qual ação qualifica como atividade? A atividade pertence à pessoa que executou, à conta em que ela operou ou à organização que paga? A janela mensal segue UTC ou o calendário do negócio? Contas de teste entram? Registros sem identidade válida são incluídos, descartados ou medidos como problema de qualidade?

O schema transacional raramente responde a isso.

Ele foi desenhado para operar o produto: registrar ações, manter consistência de escrita, sustentar fluxos da aplicação e responder com baixa latência. Nomes de tabelas, chaves e relacionamentos carregam a história do sistema. Parte das regras vive no código. Parte vive em procedimentos internos. Parte existe apenas no conhecimento de quem trabalha com a plataforma há anos.

Isso não significa que a base esteja errada. Significa que dado operacional não é métrica pronta.

Quando um agente recebe acesso direto a essa estrutura, ele encontra colunas, não decisões de negócio. Se a empresa não publicou essas decisões em uma camada governada, o modelo precisa preencher as lacunas. Ele seleciona a coluna mais provável, deduz relacionamentos, assume um timezone, interpreta nulos e monta uma resposta.

A fluência vem do modelo. A verdade deveria vir da plataforma.

Existem duas camadas de confiança.

Projetos de dados para IA costumam misturar dois problemas diferentes.

A primeira camada é semântica. Ela define o que cada entidade, evento e métrica significa. Erros aqui produzem números plausíveis e silenciosamente errados.

A segunda é operacional. Ela define como o dado é extraído, armazenado, transformado, testado, reprocessado e publicado. Erros aqui podem produzir indisponibilidade, duplicidade, perda de registros ou uma camada de consumo parcialmente atualizada.

A ordem importa.

Muitos times começam por bucket, warehouse, orquestrador e dashboard. Só depois descobrem que não existe consenso sobre a métrica que toda essa infraestrutura está calculando.

O caminho mais eficiente inverte a sequência:

Decisão de negócio
→ definição da métrica
→ contrato executável
→ transformação testada
→ publicação governada
→ BI e agentes

A infraestrutura deve proteger um significado já declarado. Não tentar descobri-lo depois.

Três decisões silenciosas mudam o número.

Identidade não é uma coluna.

Considere uma plataforma B2B em que pessoas operam dentro de contas, contas pertencem a unidades de negócio e várias unidades fazem parte de uma organização.

Organização
├── Conta A → Unidade 1
└── Conta B → Unidade 2

Uma ação realizada na Conta B pode ativar a pessoa que executou, a própria conta, a Unidade 2 e a Organização. Ela não deveria ativar automaticamente a Conta A nem a Unidade 1.

Agora acrescente um operador que age em nome do cliente. Ele deve permanecer como executor real para fins de autoria e auditoria, mas sua atividade pode impedir que a conta atendida seja classificada como inativa.

Colapsar essas identidades torna impossível responder com segurança quem realizou a ação, qual conta recebeu valor, qual unidade adotou o produto e qual organização deveria entrar em uma análise comercial. Isso não é detalhe de modelagem. É a diferença entre inteligência de produto e uma lista de churn com clientes ativos dentro.

Timezone é regra de negócio.

Um evento registrado às 01:00 UTC pode pertencer ao dia anterior no calendário da operação.

Timestamps técnicos de ingestão e auditoria devem permanecer em UTC. Datas de negócio devem usar o timezone civil definido pela empresa, representado por um nome IANA, como America/Sao_Paulo, e não por um offset fixo.

Essa decisão altera fronteiras de dias, semanas e meses, justamente onde a gestão compara fechamento, retenção e adoção.

Dado inválido não pode virar comportamento inventado.

Bases reais acumulam eventos sem identidade resolvida, vínculos obsoletos, duplicidades e alterações tardias.

Apagar esconde o problema. Incluir em métricas comportamentais transforma inconsistência em atividade válida. O registro deve permanecer disponível para auditoria, receber um status explícito de qualidade, ficar fora da métrica que não pode representar e ter seu volume acompanhado como indicador técnico.

Um número ausente e sinalizado é operacionalmente superior a um número presente e inventado.

A semântica precisa sair da reunião e entrar no sistema.

Durante muito tempo, definições de métricas puderam viver em planilhas, documentos e conversas. O consumo era humano e mediado por analistas que conheciam as exceções da base.

Agentes removem essa mediação. Eles consultam mais rápido, em maior volume e sem o contexto tácito do time. A definição precisa virar um artefato legível por máquina, versionado, testado e associado à publicação.

metric: monthly_active_accounts
description: accounts with at least one qualifying activity
owner: product_analytics
status: directional
timezone: America/Sao_Paulo
window:
  type: rolling
  days: 30
identity:
  primary: account_id
qualifying_events:
  - workflow_completed
  - report_generated
exclusions:
  - unresolved_identity
  - internal_test_account
known_limitations:
  - event taxonomy pending product approval

O valor não está no YAML. Está no fato de a definição ter deixado de ser implícita.

A plataforma agora pode verificar owner, identidade, janela, timezone, eventos, exclusões, cardinalidade, limitações e status. Também pode falhar antes que uma mudança na fonte altere silenciosamente o resultado.

Contrato não é documentação. É input de publicação.

Um teste de cardinalidade quebrado deve impedir a promoção da nova camada de consumo da mesma forma que um teste de contrato impede um deploy. É o mesmo gate determinístico descrito em Engineering Platforms na era dos agentes, aplicado a outro domínio. Esse é o princípio: determinístico primeiro. IA depois.

A arquitetura mínima protege o significado.

Depois que identidade, eventos, janelas, exclusões e ownership estão definidos, a infraestrutura fica menor do que parece.

A fonte continua otimizada para o produto. A extração lê apenas a janela e as colunas necessárias, com acesso somente leitura, timeout e paginação estável. O S3 Raw preserva origem, identificadores de execução e manifests para auditoria e replay. Parquet reduz leitura desnecessária em consultas analíticas.

O Glue cataloga os objetos. O Athena permite consultá-los com SQL sem manter um cluster analítico permanentemente ligado. O dbt transforma regras em modelos versionados, dependências e testes.

Por fim, Semantic + Gold expõe entidades e métricas estáveis, minimizadas e prontas para consumo.

O agente não deveria ser o primeiro componente a interpretar o sistema transacional. Ele deveria ser uma interface sobre uma interpretação já governada.

A Gold é uma API de dados para humanos e agentes.

A Gold não é apenas “a última tabela do pipeline”. Ela funciona como uma API de dados.

Fonte → Raw → Staging → Intermediate → Semantic → Metrics → Gold

Raw preserva origem. Staging normaliza. Intermediate concentra joins e regras compartilhadas. Semantic publica significado. Metrics aplica fórmulas e elegibilidade. Gold entrega um contrato estável.

Consumidores deixam de reproduzir joins, escolher timestamps ou reinterpretar exclusões. Se a aplicação muda, a transformação absorve a diferença sem obrigar cada dashboard e agente a reaprender o domínio.

A Gold também reduz exposição: pode remover dados pessoais e payloads desnecessários, entregando somente atributos e agregações aprovados.

Começar local não é atalho. É controle de ciclo.

Validar a primeira vertical slice localmente, com fixtures representativas e uma engine leve, separa a discussão difícil da discussão cara.

Modelar identidade, eventos, janelas e casos-limite exige muitas iterações. Fazer cada ciclo depender de credencial, ambiente provisionado, rede e custo de scan cria fricção justamente quando a regra ainda muda.

No fluxo local-first, contratos e transformações rodam rapidamente, fixtures cobrem exceções sem copiar dados reais e testes entram em CI. A migração para a engine de nuvem preserva o modelo conceitual e concentra o trabalho em configuração, adapter e diferenças de dialeto.

Quando a solução chega à AWS, a equipe já sabe o que precisa proteger.

A fundação em nuvem deve ser pequena e verificável.

Antes de extrair dados, a fundação precisa existir como infraestrutura como código e ser comprovada no ambiente real.

raw/            dados extraídos por execução
manifests/      inventário do que cada execução produziu
audit/          eventos técnicos e decisões
state/          progresso confirmado
quarantine/     falhas sanitizadas

O bucket deve ser privado, versionado, criptografado, acessível apenas por transporte seguro e por uma identidade limitada aos prefixos necessários. Essa separação permite distinguir permissão para gravar dados, avançar estado, preservar evidência e tratar falhas sem expor payload sensível.

Infraestrutura descrita em código não é infraestrutura provisionada.

Terraform validado não comprova acesso ou funcionamento. O marco só termina quando a identidade correta consegue escrever um objeto temporário, lê-lo, validar metadata, testar restrições e removê-lo.

Ingestão confiável é ingestão que pode ser repetida.

A pergunta operacional mais importante não é:

“O job executou com sucesso?”

É outra:

“Podemos executar exatamente a mesma janela novamente, sem gerar inconsistências?”

Uma ingestão preparada para produção precisa seguir quatro princípios:

Esses quatro comportamentos mudam completamente a operação. Se uma execução falha pela metade, o pipeline não publica um estado inconsistente nem avança um progresso falso. Corrige-se a causa e a mesma janela pode ser reexecutada com segurança.

Isso reduz o custo operacional, elimina procedimentos manuais de recuperação e transforma falhas em eventos previsíveis, em vez de incidentes difíceis de reproduzir.

Dado velho e correto é melhor que dado novo e quebrado.

Dashboards e agentes não deveriam enxergar uma camada de consumo pela metade.

Imagine uma execução em que os modelos de atividade foram atualizados, mas a dimensão de identidade falhou. Ou em que parte das partições foi publicada antes de um teste detectar duplicidade. Um humano experiente talvez desconfie da queda brusca. Um agente tende a explicar o número disponível.

A publicação precisa ser tratada como promoção de versão.

A nova versão é construída isoladamente. Os testes rodam sobre o resultado completo. A promoção só acontece quando o gate passa. Se falhar, a versão anterior continua publicada, um alerta é emitido e o replay permanece disponível.

Isso troca um problema perigoso por um problema administrável.

Atraso é observável. Inconsistência parcial pode parecer verdade.

Direcional não é oficial.

Uma métrica pode ser útil antes de estar pronta para representar a posição oficial da companhia.

Talvez a taxonomia de eventos ainda dependa de aprovação de Produto. Talvez parte das identidades históricas não possa ser resolvida. Talvez um novo canal ainda não esteja instrumentado. Nada disso impede o indicador de orientar descoberta, desde que sua condição esteja explícita.

Por isso, o status precisa viajar com o número:

metric: monthly_active_accounts
status: directional
owner: product_analytics
timezone: America/Sao_Paulo
limitations:
  - event taxonomy pending approval
  - legacy channel not yet instrumented

Publicar limitações não enfraquece a métrica. Protege sua credibilidade.

Um indicador que declara o que não cobre sobrevive à primeira pergunta difícil. Um indicador que se apresenta como completo perde confiança no primeiro contraexemplo e pode levar consigo todos os outros números da plataforma.

Agentes precisam receber esse status também. Uma resposta madura não diz apenas “foram X contas”. Ela informa a definição usada, a janela, a atualização, o owner e se o indicador é oficial ou direcional.

Orquestração entra quando existe algo confiável para orquestrar.

Agendamento, retry automático, containers gerenciados e coordenação de etapas são problemas importantes. Também são relativamente substituíveis.

Sem idempotência, testes e publicação segura, um orquestrador apenas automatiza a produção de incidente.

Ele deve entrar quando o fluxo manual já é confiável e começa a representar risco operacional por depender de execução recorrente de uma pessoa. Nesse momento, serviços como EventBridge, Step Functions e ECS Fargate podem automatizar uma sequência que já possui contratos claros:

Agendar
→ extrair
→ registrar auditoria
→ transformar
→ testar
→ promover
→ alertar

A automação é a última camada de maturidade, não a primeira evidência de progresso.

O rollout deve avançar por evidência.

Cronogramas descrevem intenção. Marcos técnicos precisam descrever prova.

1. Escolher uma decisão real. Começar por uma pergunta que muda uma ação de Produto, Operação, Comercial ou gestão.
2. Publicar a definição. Identidade, eventos, janela, timezone, exclusões, owner, status e limitações.
3. Construir uma vertical slice local. Uma fatia pequena atravessa transformação, semântica, métrica, qualidade e Gold.
4. Transformar regras em gates. Unicidade, cardinalidade, identidade e elegibilidade bloqueiam publicação incorreta.
5. Provar a operação. Fundação mínima, replay idempotente e promoção que preserva a versão anterior quando falha.
6. Automatizar quando necessário. Só então entram agenda, retry, containers, SLA e observabilidade recorrente.

A semântica está validada quando alguém de fora do time consegue explicar a métrica sem abrir o schema. A ingestão está validada quando a mesma janela pode ser repetida. A publicação está validada quando um teste quebrado impede a promoção. A IA está pronta quando não precisa inventar nenhuma dessas decisões.

Quando essa arquitetura não é a escolha certa.

Arquitetura madura também sabe quando não se aplicar.

Se existe uma única fonte, baixo volume e pouca concorrência analítica, uma réplica de leitura ou um banco gerenciado como destino, combinado com dbt, contratos e testes, pode entregar valor mais rápido. O lakehouse não é objetivo. A semântica governada é.

Se a empresa possui muitas fontes heterogêneas, alta concorrência e vários times consumindo simultaneamente, um warehouse gerenciado pode reduzir custo operacional, mesmo com outra estrutura de cobrança.

Se a decisão exige latência de segundos, batch incremental sobre objetos não atende. Streaming é outra arquitetura, com complexidade e operação próprias, e deve ser justificado por uma decisão que realmente não pode esperar a próxima janela.

E se a empresa ainda não sabe qual decisão quer melhorar, nenhuma stack resolve. Começar por “vamos catalogar tudo” costuma produzir um excelente diagrama e nenhuma métrica em uso.

A pergunta vem antes da plataforma.

O agente amplifica a camada que existe embaixo dele.

Quando um agente responde quantos usuários ativos uma empresa teve, ele executa uma cadeia de decisões que alguém precisou tomar antes.

Se essas decisões existem como contratos, testes, lineage e camada semântica, o agente se torna uma interface poderosa sobre uma verdade governada. Ele consegue responder de forma consistente, citar a definição, explicar limitações e repetir o cálculo.

Se não existem, ele improvisa.

Não porque o modelo esteja agindo de má-fé. A pergunta exige uma resposta, e o sistema não forneceu a estrutura necessária. O agente escolhe a identidade mais provável, o evento mais parecido, o timestamp disponível e a regra de exclusão que parece razoável.

Depois devolve tudo com uma explicação impecável.

É por isso que projetos de IA sobre dados não começam no modelo. Começam na capacidade da empresa de declarar o que quer dizer.

Semântica virou infraestrutura.

Na era dos agentes, significado não pode depender de memória institucional.

Definição de métrica, identidade, taxonomia de eventos, timezone, qualidade, ownership e status precisam ser versionados, testados, observáveis e legíveis por máquina.

Antes de conectar um agente ao banco da sua empresa, responda:

• Existe uma definição publicada para cada métrica crítica?
• Toda métrica declara identidade, janela, timezone, exclusões, owner e status?
• Uma falha parcial preserva a última versão correta?
• O pipeline pode ser repetido sem duplicar nem perder dados?
• O agente consulta uma camada governada ou interpreta o schema transacional?

Quando a resposta é “não”, trocar de modelo não resolve. O próximo passo é construir a camada de verdade que o modelo deveria consumir.

Os próximos anos não serão definidos pelo modelo de IA que uma empresa escolheu. Serão definidos pela qualidade da plataforma de dados construída para sustentá-lo.

O modelo não é o gargalo. A semântica é a infraestrutura.

---

Na bs3, construímos essa fundação com quem precisa colocar IA em produção sobre dados confiáveis: contratos, camada semântica e publicação governada.

Iniciar diagnóstico