Modelo Django que representa una instancia del Local Agent conectada a la organización. Registra su identidad, estado de conexión, rol en la flota (primary/secondary) y telemetría operativa.
Campos
Identificación
Campo
Tipo
Descripción
agent_id
UUID, PK
Identificador único del Agent generado en el binario.
organization
FK(Organization)
Organización propietaria del Agent.
hostname
str(128)
Nombre del equipo donde corre (ej: OFICINA-PC).
Estado de conexión
Campo
Tipo
Descripción
status
str(20)
“online” u “offline”.
last_seen
DateTime
ISO 8601 del último heartbeat recibido.
connected_at
DateTime
ISO 8601 de la conexión actual.
disconnected_at
DateTime, nullable
ISO 8601 del último desconexión (NULL si online).
Flota y redundancia
Campo
Tipo
Descripción
role
str(20)
“primary” o “secondary” — si es una flota de 2+ agentes.
sentinel_active
bool
¿Hay un monitor Sentinel conectado a este Agent?
disconnects_7d
int, default=0
Contador de desconexiones largas (gap ≥10 min) en los últimos 7 días.
Versión del Agent
Campo
Tipo
Descripción
agent_version
str(20)
Versión del binario (ej: “2.18.0”).
IP de la LAN (v2.16.1+)
Campo
Tipo
Descripción
ip_address
str(45), nullable
IP interna (IPv4/IPv6) del Agent. Reportada por /api/agent/agent_status y validada server-side. NULL si no disponible.
Portabilidad del equipo (v2.15+)
Campo
Tipo
Descripción
has_battery
bool, nullable
¿El equipo corre en un portátil? Reportado por /api/agent/agent_status. Usado por el Sentinel para avisos de batería baja. NULL si Agent < 2.15.
Telemetría del proceso (v2.18.0 · v1.65.0 · task #209)
Campo
Tipo
Descripción
health
JSONField, nullable
Nuevo en v1.65.0: snapshot del bloque health del último heartbeat (cada 30s). Contiene métricas del propio proceso del Agent: cpu_percent (float 0–100), mem_mb (int), db_mb (float), pending_rows (int), last_sync_age_s (int). NULL si Agent < 2.18.0 o sin heartbeat reciente. Persistido saneado por el consumer (solo claves conocidas, rechaza payloads arbitrarios).
Métodos públicos
mark_online()
Marca el Agent como online, actualiza last_seen y connected_at.
mark_offline()
Marca el Agent como offline, actualiza disconnected_at.
note_reconnect_gap(duration_seconds)
Registra una desconexión de larga duración (≥10 min) para el cálculo de disconnects_7d.
disconnects_7d (propiedad)
Retorna el número de desconexiones largas en los últimos 7 días (agregación de note_reconnect_gap).
Casos de uso
Fleet Manager (web)
Lista todos los agentes con status, agent_version, role, sentinel_active, last_seen y health.
Columna “Footprint”: renderiza CPU/RAM si health existe.
Observatory (web)
Ficha del agente: muestra CPU, RAM, DB Size, Pending Sync si health disponible.
API /api/agent/fleet
Retorna array de AgentInstanceOut (serialización de este modelo).
Dashboard home (línea marginal)
Busca primer agente con health y renderiza telemetría (refresco 30s).
Retrocompatibilidad
Agents < 2.15: no reportan ip_address, has_battery → campos NULL.
Agents < 2.18.0: no reportan health → campo NULL (modelo aún persiste sin error).
Clientes sin permiso fleet:view: no ven estos datos (403 en /api/agent/fleet).
Consideraciones de seguridad
El campo health es saneado por el consumer antes de persistir — rechaza dicts arbitrarios de payloads externos.
Los campos ip_address y hostname no contienen credenciales (la IP es interna y el hostname es público).
Solo se expone en endpoints que requieren permiso fleet:view o acceso a la organización.
Véase también
[[entity—terminal—endpoint—fleet]] — endpoint que expone instancias de este modelo
[[feature—terminal—agent-health-heartbeat]] — feature que introduce el campo health
[[concept—saas—multi-tenancy]] — aislamiento por organización
[[entity—terminal—endpoint—agent-status]] — endpoint del Agent local que reporta ip_address, has_battery, health