Crea productos de datos con habilidades de agentes

Descripción general

En esta guía, se describe cómo usar las habilidades de agentes especializadas de Cortex Framework, que proporciona directamente Cortex Framework en el repositorio de GitHub, con un asistente de codificación de IA (como Gemini junto con el framework de desarrollo de agentes Antigravity) para crear productos de datos personalizados que sigan las prácticas recomendadas de Cortex Framework.

Cortex Framework proporciona habilidades de agentes especializadas para ampliar sus capacidades, lo que permite que tu asistente de IA te guíe en el proceso de creación de productos de datos que sigan las prácticas recomendadas de Cortex Framework. Con estas capacidades, puedes usar el lenguaje natural para solicitar un nuevo producto de datos basado en requisitos comerciales específicos. Por ejemplo, puedes solicitar un producto de datos de consumo de cuentas por pagar para obtener estadísticas sobre el total adeudado, los importes vencidos y la rotación. El resultado es un producto de datos de Cortex Framework completamente integrado, creado en función de tus requisitos y datos específicos del cliente, que está listo para su ejecución.

Habilidades del agente

Las habilidades de los agentes son un formato abierto y ligero para ampliar las capacidades de los agentes de IA con conocimientos y flujos de trabajo especializados. En esencia, una habilidad es una carpeta que contiene un archivo SKILL.md (que incluye metadatos e instrucciones) junto con secuencias de comandos, referencias y recursos opcionales que le indican a un agente cómo realizar una tarea específica. Las habilidades empaquetan el conocimiento y el contexto de los procedimientos en carpetas portátiles que los agentes cargan a pedido, lo que proporciona experiencia en el dominio y flujos de trabajo repetibles. Las habilidades de Cortex Framework se almacenan en .agent directorio.

Habilidades de agentes de Cortex Framework

El compilador de productos de datos de agentes automatiza el ciclo de vida de desarrollo de extremo a extremo de los productos de datos dentro de Cortex Framework. Si le indicas a tu asistente de IA que ejecute flujos de trabajo de desarrollo estructurados, ya no tendrás que crear estructuras de archivos de forma manual, navegar por esquemas complejos de SAP, configurar capas de base, administrar espacios de nombres personalizados ni escribir código SQLX de Dataform de texto estándar.

El asistente de IA administra las siguientes tareas principales:

  • Planificación y asignación de requisitos: Traduce los requisitos comerciales concretos en un plan de modelado y desarrollo de datos procesable.
  • Búsqueda de esquemas en vivo: Ejecuta secuencias de comandos que consultan tablas replicadas del diccionario de datos de SAP (DDIC) para proporcionar información de contexto específica del cliente, como campos Z personalizados.
  • Andamiaje de texto estándar: Genera automáticamente todos los archivos de configuración, los metadatos y los artefactos de código SQLX o JavaScript necesarios.
  • Puertas de calidad de los datos: Valida los productos de datos mediante la ejecución de compilaciones locales, la compilación de código SQL, la ejecución de pruebas de unidades y de integración, y la verificación del cumplimiento de los estándares de nomenclatura.
  • Creación de documentación: Crea automáticamente recursos de documentación, incluida la visualización de los diagramas de relación de entidades (ER) y las claves primarias de tu módulo de producto de datos.

El desarrollo de productos de datos con estas habilidades de agentes es un proceso iterativo. Puedes comenzar con tus objetivos iniciales, revisar el plan de implementación propuesto por el agente, incluidos los diagramas y esquemas de ER, y pedirle al asistente de IA que refine la lógica de forma conversacional a medida que avanzas. Si bien el agente acelera el desarrollo, mantienes el control total para revisar y aprobar todo el código generado antes de confirmarlo en tu repositorio. Además, debido a que estas secuencias de comandos de agentes se ejecutan de forma local con tus credenciales autenticadas, respetan inherentemente los límites de acceso existentes de Google Cloud y BigQuery.

Requisitos previos

Antes de usar las habilidades de agentes, verifica que tu entorno de desarrollo cumpla con los siguientes requisitos para habilitar las consultas de esquemas en vivo, la compilación de datos y la validación automatizada:

  1. Google Cloud SDK (gcloud): Instala y autentica la CLI de (gcloud) con tu cuenta de usuario. Para obtener más información, consulta la documentación de implementación.

  2. Credenciales predeterminadas de la aplicación (ADC): Configura tus ADC locales y los destinos del proyecto para que las herramientas de compilación locales y los conjuntos de pruebas de pytest puedan comunicarse con BigQuery. Para obtener más información, consulta cómo preparar tu proyecto predeterminado Google Cloud

  3. Tablas replicadas del diccionario de datos de SAP (DDIC): Para permitir que el agente realice verificaciones de esquemas que no distinguen mayúsculas de minúsculas y verifique con precisión las longitudes de los campos, replica las siguientes tablas de metadatos de SAP en tu conjunto de datos de BigQuery de destino sin procesar:

    • DD03L (campos de tabla)
    • DD04T (textos de elementos de datos)
    • DD08L (relaciones de tablas)
    • DD01L (dominios)
    • DD07L (valores de dominio, opcional)
    • DD07T (textos de valores de dominio, opcional)

  4. Entorno de Python local: Instala dependencias locales y ejecuta la herramienta de sincronización con uv para garantizar que las bibliotecas de validación y las pruebas de unidades funcionen correctamente. Para obtener más información, consulta la documentación.

Configuración del IDE

Antes de comenzar, consulta la documentación de tu asistente de codificación de IA preferido para obtener instrucciones de instalación y configuración (por ejemplo, Antigravity).

  1. Recopila los artefactos de instalación necesarios y clona el repositorio. Para obtener más información, consulta Artefactos de instalación.

  2. Abre la huella del código fuente de Google Cloud Cortex Framework clonado en tu asistente de codificación de IA designado.

Google Cloud Cortex Framework expone sus capacidades de agentes a través de un conjunto de habilidades especializadas ubicadas en el directorio .agents/skills/ del repositorio. Puedes usar estas habilidades en varios entornos de desarrollo:

  • Framework de Antigravity: Antigravity descubre, indexa y activa automáticamente todas las habilidades del espacio de trabajo al inicio. No es necesario realizar ninguna configuración adicional. Para verificarlo, pregúntale al asistente lo siguiente:

    ¿Qué habilidades tienes disponibles?

  • VSCode con Gemini Code Assist:

    1. Instala la extensión de Gemini Code Assist desde VS Code Marketplace.
    2. Abre la carpeta cortex-framework-core como un espacio de trabajo. El asistente analiza y carga automáticamente las habilidades del directorio .agents/skills/.

  • Otras herramientas de CLI de IA: Haz referencia al directorio de habilidades de forma nativa en tus mensajes de instrucciones. Por ejemplo:

    Lee la habilidad create-data-product dentro del directorio .agents/skills/ y crea la estructura...

Crea un producto de datos personalizado

En los siguientes pasos, se describe el flujo de trabajo estructurado para desarrolladores para usar habilidades de agentes y crear un producto de datos personalizado.

Paso 1: Proporciona requisitos y contexto

Con la interfaz de chat de tu asistente de codificación de IA, proporciona un mensaje que describa tus requisitos de datos específicos. Por ejemplo:

Crea un producto de datos de Cortex Framework para estadísticas de cuentas por pagar orientado a SAP S/4HANA y ECC. Usa el espacio de nombres: custom_finance. El requisito comercial principal es hacer un seguimiento del total adeudado y los importes vencidos de nuestros proveedores, y calcular nuestra tasa de rotación de cuentas por pagar por código de empresa.

Ten en cuenta que también puedes hacer referencia a los requisitos existentes o a los documentos de especificación directamente en tu mensaje. Estos documentos (que pueden estar en Markdown o en otros formatos estructurados) le proporcionan al agente un contexto vital, como el siguiente:

  • Contexto y dominio comercial: Objetivos detallados, casos de éxito y consumidores objetivo
  • Especificaciones de datos de entrada: Lista de tablas de origen (p. ej., LFA1, BSIK, BSEG, Z...), detalles de control de versiones (ECC en comparación con S/4HANA), reglas de exclusión, campos personalizados y mucho más
  • Lógica de transformación y reglas comerciales: Restricciones de asignación principales, filtrado de clientes (mandt), eliminaciones temporales (loekz), manejo de asignaciones de indicadores de bloqueo de pagos (zlspr) y reglas de conciliación (por ejemplo, exclusión de transacciones de proveedores entre empresas para evitar tasas de rotación sesgadas)
  • Integridad de los datos y aserciones de prueba: Situaciones de verificación (por ejemplo, verificación de la singularidad de los granos y garantía de que la suma de los importes de las facturas abiertas en el resultado final coincida exactamente con las tablas de origen sin procesar)

Paso 2: Revisa el plan de implementación

Después de que describas los requisitos, el agente usa varias habilidades, como la habilidad query-sap-ddic para consultar tus tablas de metadatos de DDIC de BigQuery sin procesar. Esto le permite al agente identificar y validar las tablas de origen necesarias, lo que garantiza que los tipos de campos y las relaciones sean precisos. El agente también puede invocar otras habilidades para garantizar que tus requisitos se alineen perfectamente con las prácticas recomendadas de Cortex Framework.

Antes de comenzar la implementación, el agente proporciona un breve plan de implementación para que lo revises. Este plan incluye las tablas de origen identificadas, las asignaciones y la estructura arquitectónica propuesta del producto de datos. Revisa este plan y solicita los ajustes necesarios antes de confirmar.

Paso 3: Genera el producto de datos

Después de confirmar el plan de implementación, el agente utiliza la habilidad create-data-product para crear la estructura del directorio. Esto aísla tus nuevos desarrollos personalizados de las actualizaciones de la plataforma principal en tu espacio de nombres 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 obtener más información sobre la estructura de carpetas y los archivos individuales, consulta la documentación de la Guía de extensibilidad.

Durante esta fase, también puedes pedirle al agente que visualice automáticamente las relaciones con la habilidad generate-er-diagram o que cree aserciones con la habilidad create-python-tests.

Paso 4: Ejecuta las puertas de calidad y verifica los datos

Según los permisos otorgados, el agente ejecutará automáticamente las siguientes puertas de validación obligatorias o te pedirá que las ejecutes. Durante este proceso, el agente genera informes de estado detallados para que puedas revisar los resultados:

  1. Validación de compilación: Ejecuta uv run cortex-build --config config/config.yaml para garantizar que todos los modelos de SQL generados se compilen correctamente y producir un resumen de compilación.
  2. Ejecución de Pytest: Ejecuta el kit completo de pruebas de unidades de Python y genera un informe de ejecución de pruebas que verifica tu lógica empresarial y aserciones principales.
  3. Linter y auditorías: Aprovecha la habilidad validate-data-product para realizar verificaciones estrictas de paridad de campos y verificar el cumplimiento de la convención de nomenclatura, y concluye con un informe de preparación detallado.

Paso 5: Implementa y ejecuta

Después de revisar los informes de validación y aprobar el código generado, puedes implementar los recursos de tu producto de datos.

  • Implementa recursos: Envía las definiciones compiladas del producto de datos a tu espacio de trabajo de Dataform configurado ejecutando la secuencia de comandos de implementación de forma local (por ejemplo, uv run cortex-deploy --config config/config.yaml).
  • Materializa los datos: Completa el flujo de trabajo final posterior a la implementación para ejecutar las canalizaciones de Dataform generadas, materializar tus tablas y vistas nuevas directamente en BigQuery.
  • Entrega estadísticas: Una vez materializado, tu producto de datos personalizado está listo para conectarse a las apps de análisis descendentes, como Gemini Enterprise, para entregar respuestas inteligentes y prácticas a tus preguntas comerciales originales.

Actualiza un producto de datos existente

Una vez que se compila tu producto de datos personalizado, no es necesario que comiences desde cero para realizar modificaciones. Puedes aprovechar la habilidad update-data-product para agregar nuevos campos de forma iterativa, ajustar la lógica empresarial o integrar tablas de origen completamente nuevas. Por ejemplo:

Actualiza mi producto de datos de AP custom_finance. Agrega el campo de condiciones de pago (ZTERM) de la tabla de origen LFA1 y asegúrate de que esté asignado correctamente a la vista de salida final. Ejecuta la validación de compilación cuando termines.

El agente ubicará la configuración, consultará el DDIC de BigQuery para obtener los requisitos exactos del campo, actualizará tu código de Dataform y ejecutará las verificaciones de compilación necesarias para verificar el cambio.

Prácticas recomendadas y limitaciones

  • Errores de consulta de esquemas: Si el agente no puede recuperar los esquemas de metadatos de SAP, verifica que tus credenciales predeterminadas de la aplicación (ADC) locales estén activas y tengan el rol de IAM de visualizador de datos de BigQuery para el conjunto de datos sin procesar de destino.
  • Límites de contexto: Si compilas un producto de datos excepcionalmente grande que incluye docenas de tablas, es posible que el agente pierda el contexto. Amplía tu tasa de éxito proporcionando instrucciones atómicas más pequeñas (por ejemplo, indica al agente que compile primero las dimensiones a nivel del encabezado y, luego, agregue hechos a nivel del elemento en un mensaje de seguimiento independiente).