Criar produtos de dados com habilidades de agentes

Visão geral

Este guia descreve como usar habilidades de agentes especializados do Cortex Framework, fornecidas diretamente pelo Cortex Framework no repositório do GitHub, com um assistente de programação de IA (como Gemini pareado com o framework de desenvolvimento de agentes Antigravity) para criar produtos de dados personalizados que seguem as práticas recomendadas do Cortex Framework.

O Cortex Framework oferece habilidades de agentes especializados para estender os recursos, permitindo que o assistente de IA oriente você no processo de criação de produtos de dados que seguem as práticas recomendadas do Cortex Framework. Com esses recursos, é possível usar a linguagem natural para solicitar um novo produto de dados com base em requisitos comerciais específicos. Por exemplo, você pode pedir um produto de dados de consumo de contas a pagar para ter insights sobre o total devido, valores vencidos e rotatividade. O resultado é um produto de dados do Cortex Framework totalmente integrado, criado com base nos requisitos e dados específicos do cliente, que está pronto para execução.

Habilidades do agente

As habilidades de agentes são um formato leve e aberto para estender os recursos de agentes de IA com conhecimento e fluxos de trabalho especializados. Basicamente, uma habilidade é uma pasta que contém um arquivo SKILL.md (que inclui metadados e instruções) junto com scripts, referências e recursos opcionais que instruem um agente a realizar uma tarefa específica. As habilidades empacotam conhecimento e contexto processuais em pastas portáteis que os agentes carregam sob demanda, fornecendo experiência no domínio e fluxos de trabalho repetíveis. As habilidades do Cortex Framework são armazenadas no diretório .agent.

Habilidades de agentes do Cortex Framework

O criador de produtos de dados de agentes automatiza o ciclo de vida de desenvolvimento de ponta a ponta de produtos de dados no Cortex Framework. Ao instruir o assistente de IA a executar fluxos de trabalho de desenvolvimento estruturados, você elimina a necessidade de criar estruturas de arquivos manualmente, navegar por esquemas complexos do SAP, configurar camadas de base, gerenciar namespaces personalizados e escrever código SQLX do Dataform.

O assistente de IA gerencia as seguintes tarefas principais:

  • Planejamento e mapeamento de requisitos: traduz requisitos comerciais concretos em um plano de modelagem e desenvolvimento de dados acionável.
  • Pesquisa de esquema em tempo real: executa scripts que consultam tabelas replicadas do dicionário de dados do SAP (DDIC) para fornecer informações de contexto específicas do cliente, como campos Z personalizados.
  • Estrutura de boilerplate: gera automaticamente todos os arquivos de configuração, metadados e artefatos de código SQLX ou JavaScript necessários.
  • Portões de qualidade de dados: valida produtos de dados executando builds locais, compilando código SQL, executando testes de unidade e integração e verificando a conformidade com os padrões de nomenclatura.
  • Criação de documentação: cria recursos de documentação automaticamente, incluindo a visualização dos diagramas de relacionamento de entidades (ER) e das chaves primárias do módulo de produto de dados.

O desenvolvimento de produtos de dados com essas habilidades de agentes é um processo iterativo. Você pode começar com suas metas iniciais, analisar o plano de implementação proposto pelo agente, incluindo diagramas e esquemas de ER, e pedir ao assistente de IA para refinar a lógica de forma conversacional à medida que avança. Embora o agente acelere o desenvolvimento, você mantém o controle total para analisar e aprovar todo o código gerado antes de fazer o commit no repositório. Além disso, como esses scripts de agentes são executados localmente usando suas credenciais autenticadas, eles respeitam inerentemente os limites de acesso do Google Cloud e do BigQuery.

Pré-requisitos

Antes de usar as habilidades de agentes, verifique se o ambiente de desenvolvimento atende aos seguintes requisitos para ativar consultas de esquema em tempo real, compilação de dados e validação automatizada:

  1. Google Cloud SDK (gcloud) : instale e autentique a CLI (gcloud) com sua conta de usuário. Para mais informações, consulte a documentação de implantação.

  2. Application Default Credentials (ADC): configure o ADC local e os destinos do projeto para que as ferramentas de compilação local e os pacotes pytest possam se comunicar com o BigQuery. Para mais informações, consulte Preparar o projeto padrão Google Cloud

  3. Tabelas replicadas do dicionário de dados do SAP (DDIC): para permitir que o agente realize verificações de esquema sem distinção entre maiúsculas e minúsculas e verifique com precisão os comprimentos dos campos, replique as seguintes tabelas de metadados do SAP no conjunto de dados bruto de destino do BigQuery:

    • DD03L (campos da tabela)
    • DD04T (textos de elementos de dados)
    • DD08L (relações entre tabelas)
    • DD01L (domínios)
    • DD07L (valores de domínio: opcional)
    • DD07T (textos de valores de domínio: opcional)

  4. Ambiente Python local: instale dependências locais e execute a ferramenta de sincronização usando uv para garantir que as bibliotecas de validação e os testes de unidade funcionem corretamente. Para mais informações, consulte a documentação.

Configuração do ambiente de desenvolvimento integrado

Antes de começar, consulte a documentação do assistente de programação de IA preferido para instruções de instalação e configuração (por exemplo, Antigravity).

  1. Reúna os artefatos de instalação necessários e clone o repositório. Para mais informações, consulte Artefatos de instalação.

  2. Abra a pegada do código-fonte do Google Cloud Cortex Framework clonado no assistente de programação de IA designado.

O Google Cloud Cortex Framework expõe os recursos de agentes por meio de um conjunto de habilidades especializadas localizadas no diretório .agents/skills/ do repositório. É possível usar essas habilidades em vários ambientes de desenvolvimento:

  • Framework Antigravity: o Antigravity descobre, indexa e ativa automaticamente todas as habilidades do espaço de trabalho na inicialização. Não é preciso fazer nenhuma configuração adicional. Para verificar, pergunte ao assistente:

    Quais habilidades você tem disponíveis?

  • VS Code com o Gemini Code Assist:

    1. Instale a extensão do Gemini Code Assist no VS Code Marketplace.
    2. Abra a pasta cortex-framework-core como um espaço de trabalho. O assistente verifica e carrega automaticamente as habilidades do diretório .agents/skills/.

  • Outras ferramentas de CLI de IA: consulte o diretório de habilidades nativamente nos comandos de instrução. Por exemplo:

    Leia a habilidade create-data-product no diretório .agents/skills/ e crie a estrutura...

Criar um produto de dados personalizado

As etapas a seguir descrevem o fluxo de trabalho estruturado do desenvolvedor para usar habilidades de agentes na criação de um produto de dados personalizado.

Etapa 1: fornecer requisitos e contexto

Usando a interface de chat do assistente de programação de IA, forneça um comando que descreva seus requisitos de dados específicos. Exemplo:

Crie um produto de dados do Cortex Framework para insights de contas a pagar direcionado ao SAP S/4HANA e ECC. Use o namespace: custom_finance. O principal requisito comercial é acompanhar o total devido e os valores vencidos dos nossos fornecedores e calcular a taxa de rotatividade de contas a pagar por código da empresa.

Também é possível referenciar requisitos ou documentos de especificação atuais diretamente no comando. Esses documentos (que podem estar em Markdown ou outros formatos estruturados) fornecem ao agente um contexto essencial, como:

  • Contexto e domínio comercial: objetivos detalhados, histórias de usuários e consumidores-alvo.
  • Especificações de dados de entrada: lista de tabelas de origem (por exemplo, LFA1, BSIK, BSEG, Z...), detalhes de controle de versão (ECC versus S/4HANA), regras de exclusão, campos personalizados e muito mais.
  • Lógica de transformação e regras de negócios: restrições de mapeamento principais, filtragem de clientes (mandt), exclusões temporárias (loekz), processamento de mapeamentos de indicadores de bloqueio de pagamento (zlspr) e regras de reconciliação (por exemplo, exclusão de transações de fornecedores entre empresas para evitar taxas de rotatividade distorcidas).
  • Integridade de dados e declarações de teste: cenários de verificação (por exemplo, verificar a exclusividade do grão e garantir que a soma dos valores de faturas em aberto na saída final corresponda exatamente às tabelas de origem brutas).

Etapa 2: analisar o plano de implementação

Depois de descrever os requisitos, o agente usa várias habilidades, como a habilidade query-sap-ddic, para consultar as tabelas de metadados DDIC brutas do BigQuery. Isso permite que o agente identifique e valide as tabelas de origem necessárias, garantindo que os tipos de campo e os relacionamentos sejam precisos. O agente também pode invocar outras habilidades para garantir que seus requisitos estejam perfeitamente alinhados às práticas recomendadas do Cortex Framework.

Antes de iniciar a implementação, o agente fornece um breve plano de implementação para sua análise. Esse plano inclui as tabelas de origem identificadas, os mapeamentos e a estrutura arquitetônica proposta do produto de dados. Analise esse plano e solicite ajustes antes de confirmar.

Etapa 3: gerar o produto de dados

Depois de confirmar o plano de implementação, o agente usa a habilidade create-data-product para criar a estrutura de diretório. Isso isola seus novos desenvolvimentos personalizados das atualizações da plataforma principal no namespace personalizado designado:

src/data_modules/<custom_namespace>/products/<dataproductname>/
├── manifest.yaml
├── table_settings.default.yaml
├── README.md
├── definitions/
│   └── [ecc|s4]/
│       └── <product_name>.js
└── annotations/
    └── [ecc|s4]/
        └── <product_name>.yaml

Para mais informações sobre a estrutura de pastas e os arquivos individuais, consulte a documentação do Guia de extensibilidade.

Durante essa fase, também é possível pedir ao agente para visualizar automaticamente os relacionamentos usando a habilidade generate-er-diagram ou para criar declarações usando a habilidade create-python-tests.

Etapa 4: executar portões de qualidade e verificar dados

Dependendo das permissões concedidas, o agente vai executar automaticamente os seguintes portões de validação obrigatórios ou pedir que você os execute. Durante todo esse processo, o agente gera relatórios de status detalhados para que você possa analisar os resultados:

  1. Validação de build: executa uv run cortex-build --config config/config.yaml para garantir que todos os modelos SQL gerados sejam compilados com sucesso, produzindo um resumo do build.
  2. Execução do Pytest: executa o pacote completo de testes de unidade do Python, gerando um relatório de execução de testes que verifica a lógica de negócios e as declarações principais.
  3. Linter e auditorias: aproveita a habilidade validate-data-product para realizar verificações rigorosas de paridade de campo e verificar a conformidade com a convenção de nomenclatura, concluindo com um relatório de preparação detalhado.

Etapa 5: implantar e executar

Depois de analisar os relatórios de validação e aprovar o código gerado, você estará pronto para implantar os recursos do produto de dados.

  • Implantar recursos: envie as definições de produtos de dados compilados para o espaço de trabalho do Dataform configurado executando o script de implantação localmente (por exemplo, uv run cortex-deploy --config config/config.yaml).
  • Materializar dados: conclua o fluxo de trabalho final pós-implantação para executar os pipelines do Dataform gerados, materializando suas novas tabelas e visualizações diretamente no BigQuery.
  • Fornecer insights: depois de materializado, o produto de dados personalizado estará totalmente pronto para ser conectado a apps analíticos downstream, como o Gemini Enterprise, para fornecer respostas inteligentes e acionáveis às suas perguntas comerciais originais.

Atualizar um produto de dados atual

Depois que o produto de dados personalizado for criado, não será necessário começar do zero para fazer modificações. É possível aproveitar a habilidade update-data-product para adicionar novos campos de forma iterativa, ajustar a lógica de negócios ou integrar tabelas de origem totalmente novas. Exemplo:

Atualize meu produto de dados AP custom_finance. Adicione o campo de condições de pagamento (ZTERM) da tabela de origem LFA1 e garanta que ele esteja mapeado corretamente para a visualização de saída final. Execute a validação do build quando terminar.

O agente vai localizar a configuração, consultar o DDIC do BigQuery para os requisitos exatos do campo, atualizar o código do Dataform e executar as verificações de build necessárias para verificar a mudança.

Práticas recomendadas e limitações

  • Falhas na consulta de esquema: se o agente não conseguir buscar esquemas de metadados do SAP, verifique se as Application Default Credentials (ADC) locais estão ativas e se têm o papel do IAM de Leitor de dados do BigQuery para o conjunto de dados bruto de destino.
  • Limites de contexto: se você estiver criando um produto de dados excepcionalmente grande que envolva dezenas de tabelas, o agente poderá perder o contexto. Aumente sua taxa de sucesso fornecendo instruções atômicas menores (por exemplo, instrua o agente a criar as dimensões de nível de cabeçalho primeiro e, em seguida, adicione fatos de nível de item em um comando de acompanhamento separado).