18. Agente on-premise

Una aplicación de escritorio que conecta tus bases de datos en red privada con Metaustral y ejecuta flujos de datos locales como Data Orchestrator. Disponible en todos los planes.

18.1 Descripción general

El Agente Metaustral es una aplicación de escritorio que corre en cualquier máquina dentro de tu red privada. Tiene dos capacidades principales:

Sincronización de metadatos (Transfer Connections) — se conecta a bases de datos on-premise, descubre metadatos de esquema (tablas, vistas, columnas, tipos de datos) y los envía automáticamente a tu catálogo Metaustral en un horario definido.
Data Orchestrator — ejecuta flujos de datos y transformaciones localmente dentro de tu red privada, sin enviar tus datos a la nube.

Disponible en todos los planes — incluyendo Free Cada base de datos sincronizada por el agente cuenta como una conexión de base de datos en el límite de tu plan. Free: 1 conexión; Starter: 5; Pro: 25; Business: ilimitadas.

Pantalla principal del Agente Metaustral — muestra la conexión activa al workspace (tenant y plan) y todas las Transfer Connections configuradas con su última ejecución, próxima ejecución programada y controles de corrida.

18.2 Transfer Connections — Sincronización automática de metadatos

Una Transfer Connection es un enlace configurado entre una base de datos local y tu workspace de Metaustral. Una vez configurada, el agente sincroniza los metadatos según el horario que definas — sin intervención manual.

Descarga y lanza el agente

Descarga la última versión desde github.com/Metaustral/metaustral-agent/releases. Haz doble clic en la app descargada para iniciarla — no requiere instalación.

Conecta con tu workspace de Metaustral

En el agente, ve a Settings → Cloud Link. Ingresa la URL de tu workspace de Metaustral, tu email y una API key generada desde Workspace → Agente on-premise → API Keys.

Agrega una conexión de base de datos

Ve a Management → Connections → New connection en el agente. Selecciona el tipo de base de datos (SQL Server, MySQL, PostgreSQL, SQLite, etc.) e ingresa tus credenciales locales. El agente prueba la conexión antes de guardar.

Crea una Transfer Connection

Ve a Transfer Connections → New. Selecciona la conexión de base de datos, elige un horario de sincronización (p. ej. cada hora, diariamente) y guarda. La primera sincronización se ejecuta inmediatamente y las siguientes siguen el horario.

Visualiza los metadatos en Metaustral

Cada ejecución aparece en Workspace → Agente on-premise → Sync History con su estado (Success / Partial / Failed) y una vista detallada con los activos creados, actualizados u omitidos. Las tablas y vistas sincronizadas aparecen en tu catálogo inmediatamente.

18.3 Data Orchestrator

Más allá de la sincronización de metadatos, el Agente Metaustral funciona como un Data Orchestrator completo: puede ejecutar flujos de transformación de datos y jobs programados íntegramente dentro de tu red privada. Esto es útil para:

Ejecutar pipelines ETL/ELT que acceden a datos sensibles que no deben salir de la red.
Programar transformaciones de datos que dependen de fuentes on-premise.
Construir pipelines de automatización que combinan bases de datos locales con fuentes de datos en la nube.
Ejecutar validaciones de calidad de datos en infraestructura privada.

Proyectos

Un Proyecto es una carpeta local en tu máquina que el agente indexa y gestiona. Cada proyecto está vinculado a un ambiente Python (un virtualenv aislado con sus propios paquetes) para que distintos proyectos puedan tener dependencias diferentes sin conflictos. Los proyectos también pueden referenciar conexiones SQL creadas en la pestaña Management, facilitando la consulta directa de bases de datos on-premise desde notebooks o scripts.

Desde la pestaña Explorer dentro de un proyecto puedes navegar todos los archivos .py, .ipynb y .sql de la carpeta. Cada archivo puede abrirse en su editor o ejecutarse de forma independiente con un solo clic. Para ejecutar un archivo de forma recurrente y programada debe agregarse a un Job.

Pestaña Projects — explorador de archivos mostrando archivos .py e .ipynb en la carpeta del proyecto. Los archivos pueden ejecutarse solos o arrastrarse al canvas de un Job. Las pestañas Python Environment y Jobs gestionan el virtualenv del proyecto y los flujos programados.

Jobs — Canvas visual y programación

Un Job es un flujo creado dentro de un proyecto que define qué scripts y notebooks ejecutar, en qué orden y cuándo. Los Jobs se construyen en un canvas visual: arrastra cualquier archivo del proyecto como nodo, conecta los nodos en secuencia (o en paralelo) y configura parámetros, reintentos, timeouts y políticas de fallo por nodo. Los Jobs pueden programarse para correr diariamente, semanalmente o mensualmente.

Los tipos de nodo soportados son Python Script, Notebook, SQL y Wait. Cada nodo puede recibir parámetros de entrada que se pasan en tiempo de ejecución — útil para rangos de fechas, umbrales o valores específicos del entorno.

Canvas de Job — nodos representando notebooks y scripts conectados en orden de ejecución. El panel derecho muestra la configuración del nodo seleccionado: archivo, parámetros de entrada, reintentos, timeout y política de fallo. Usa el botón Schedule para configurar una recurrencia diaria, semanal o mensual.

Historial de corridas y seguimiento de errores

Cada ejecución de un Job queda registrada con un historial completo: tipo de disparador (manual, programado), hora de inicio, duración total y estado por nodo. Si un nodo falla, la vista de detalle lo resalta en rojo sobre el canvas y muestra la salida de error exacta — facilitando identificar qué paso falló y por qué sin necesidad de revisar archivos de log.

Desde la vista de detalle también puedes volver a ejecutar el job con los mismos parámetros, o abrir el archivo que falló directamente en su editor para corregirlo.

Metaustral Agent — Job execution detail with error

Detalle de ejecución de Job — grafo de nodos con badges de éxito/fallo por nodo, metadatos de ejecución (estado, disparador, hora de inicio, duración) y el panel derecho mostrando la salida de error exacta del nodo fallido. El botón "Run again" vuelve a disparar el job completo.

18.4 Arquitectura

graph TB subgraph cloud["☁ Cloud — Metaustral"] API[Metaustral API] CAT[(Catalog)] API --> CAT end subgraph private["🔒 Private Network"] AGENT[Metaustral Agent\nDesktop App] TC[Transfer Connection\nScheduled Sync] ORCH[Data Orchestrator\nLocal Workflows] DB[(On-Premise DB\nSQL Server / MySQL / PG / SQLite…)] AGENT --> TC AGENT --> ORCH TC -->|INFORMATION_SCHEMA| DB ORCH -->|Read / Write| DB end TC -->|Metadata only — HTTPS outbound| API ORCH -->|Status & logs| API style cloud fill:#182830,stroke:#3D6478,color:#f1f5f9 style private fill:#0f1e1a,stroke:#10b981,color:#f1f5f9 style AGENT fill:#065f46,stroke:#10b981,color:#f1f5f9 style TC fill:#064e3b,stroke:#10b981,color:#f1f5f9 style ORCH fill:#064e3b,stroke:#10b981,color:#f1f5f9 style DB fill:#1e293b,stroke:#3D6478,color:#f1f5f9 style API fill:#1E3038,stroke:#9CC4D1,color:#f1f5f9 style CAT fill:#1e293b,stroke:#3D6478,color:#f1f5f9

El agente corre dentro de la red privada. Las Transfer Connections envían solo metadatos al exterior. El Data Orchestrator mantiene todos los datos locales.

18.5 Seguridad

Solo tráfico saliente: el agente inicia solicitudes HTTPS salientes a la API de Metaustral. No es necesario abrir puertos de firewall entrantes.
Solo metadatos en sync: las Transfer Connections leen únicamente definiciones de esquema — nunca datos reales de filas.
Datos permanecen locales: el Data Orchestrator ejecuta workflows dentro de la red privada; los datos no salen a menos que configures explícitamente un destino externo.
Aislamiento de credenciales: las credenciales de base de datos se almacenan localmente en el agente y nunca se transmiten a Metaustral.
Transporte cifrado: toda la comunicación entre el agente y Metaustral usa TLS 1.2+.

18.6 Descarga

Descarga la última versión del Agente Metaustral para tu sistema operativo desde la página de releases de GitHub:

github.com/Metaustral/metaustral-agent/releases →