Telemetría Volkom Mesh — Guía para usuarios

Esta guía explica, en lenguaje claro, cómo un agente le manda telemetría a Volkom Mesh. Hay dos canales independientes:

1. Ejecución (lo que el agente hizo): arranque, pasos, fin, errores, tiempos.
2. Negocio (los KPIs del cliente): plata, cantidades, porcentajes, tiempos que importan al negocio (ventas, facturas, clientes atendidos, etc.).

Los dos canales viven en la misma API y se guardan en una sola base de datos por tenant. Tanto el portal del cliente (volkommesh) como el panel de Volkom (adminvm) leen exactamente lo mismo de ahí.

Conceptos en 1 minuto#

La regla de oro: una corrida es una secuencia de eventos que comparten el mismo run_id. Empieza con un evento started, puede tener varios in_progress (los pasos), y cierra con completed o failed.

Canal 1 — Telemetría de EJECUCIÓN#

Cuenta la historia de lo que hizo el agente. Cada evento puede llevar tantos detalles como quieras — desde algo mínimo hasta una narrativa rica paso a paso.

Las dimensiones de un evento#

Todas son opcionales salvo las básicas. Llená lo que tenga sentido para tu agente:

Principio rector: el front es genérico. Muestra lo que mandes, sin código a medida. Si agregás un KPI o una categoría nueva, aparece sola — no hay que tocar la interfaz.

Cómo se ve una corrida típica#

▸ started                                        (arranca la corrida)
  · Buscó correos        cat: Correo         {emails: 11}
  · Descargó adjunto     cat: Correo
  ⚠ Reintento de parseo  cat: Procesamiento  level: warning
  · Consolidó datos      cat: Procesamiento  {clientes: 15}
  · Subió a Drive        cat: Cierre         link: https://drive…
■ completed                                      (cierra OK)

Canal 2 — Telemetría de NEGOCIO (KPIs)#

Aparte de qué hizo, el agente puede reportar cuánto valió para el negocio. Esto alimenta el dashboard ejecutivo (tarjetas, tendencias, comparativas).

Un KPI se define con 4 cosas#

Unidades disponibles (unit)#

Agregaciones disponibles (agg) — cómo se suma en el período elegido#

Por qué importa el agg: si reportás "ventas = 100" en 30 corridas y la unidad es sum, el período muestra 3.000. Si fuera last (ej. stock), mostraría solo el último: 100. Elegir mal el agg da números equivocados en el dashboard.

Las dos formas de mandar telemetría#

Forma A — Con el carcass (recomendado, agentes en Python)#

Si tu agente usa volkom-core, no tocás HTTP: heredás de BaseAgent y usás métodos. El carcass arma los eventos, los manda y maneja el ciclo de la corrida.

from volkom_core import BaseAgent, AgentResult, KPI

class SalesMonitor(BaseAgent):
    agent_name = "sales-monitor"
    agent_version = "1.0.0"
    description = "Monitorea ventas diarias."
    # KPIs de negocio que este agente reporta:
    business_kpis = [
        KPI("orders",  "Pedidos",      "count",     "sum"),
        KPI("revenue", "Facturación",  "money:USD", "sum"),
    ]

    def run(self) -> AgentResult:
        # --- Telemetría de EJECUCIÓN (pasos) ---
        self.event("Conectó a la tienda", category="Ingesta")
        self.event("Leyó pedidos", category="Ingesta", metrics={"pedidos": 42})
        self.warn("3 pedidos sin dirección", category="Validación",
                  metrics={"incompletos": 3})

        # --- Telemetría de NEGOCIO (KPIs) ---
        self.kpi("orders", 42)
        self.kpi("revenue", 9500)

        return AgentResult(records_processed=42)

El started, el completed/failed, los tiempos y el run_id los pone el carcass solo cuando corre el agente. Vos solo describís lo que pasa.

Métodos del carcass: - self.event(message, level=, category=, metrics=, links=, source=) — un evento rico. - self.step(msg) / self.info(msg) / self.warn(msg) / self.error(msg) — atajos por nivel. - self.kpi(key, value) — reporta un KPI de negocio (debe estar declarado en business_kpis). - self.emit_metric(key, value) — metadata libre en el evento de cierre (no es KPI graficable).

Forma B — HTTP directo (cualquier lenguaje)#

Si tu agente no es Python o querés controlar el HTTP, pegás a la API directamente. El detalle exacto de endpoints, headers y JSON está en la Referencia de la API (pensada para que la procese Claude Code o un dev).

En resumen, son 3 llamadas: 1. POST /api/v1/agents/register — declara el agente y sus KPIs (una vez). 2. POST /api/v1/telemetry — un evento de ejecución (uno por started/paso/cierre). 3. POST /api/v1/telemetry/business — los KPIs de una corrida.

Todas con el header Authorization: Bearer <token-del-agente>.

Errores comunes (y cómo evitarlos)#

• Todos los pasos comparten el run_id. Si cada evento usa un run_id distinto, el portal los ve como corridas separadas y "se pierde" la narrativa.
• Cerrá siempre la corrida con completed o failed. Una corrida sin cierre queda figurando como "en curso" para siempre.
• Declará los KPIs antes de usarlos (business_kpis / register). Si mandás un KPI sin declarar, el valor entra pero el dashboard no sabe su unidad/agg.
• Elegí bien el agg. sum para cosas que se acumulan, last para estados.
• El nivel hace al color. Usá warning/error para que los problemas se resalten en rojo/ámbar en la actividad.

¿Dónde veo la telemetría?#

• Portal del cliente (volkommesh): pantalla Actividad (corridas agrupadas, expandís y ves los pasos) + Dashboard de negocio (tarjetas con los KPIs).
• Panel de Volkom (adminvm): Runs por tenant (misma data, vista técnica)
• Audit Log (quién hizo qué en la plataforma).

Ambos leen la misma API y la misma base de datos. Lo que el agente manda una vez, se ve en los dos lados.