Manual de usuario de SoftAgent

Confirmar que el entorno cumple los requisitos y prepararse para la instalación.

1. Confirme que el PC de destino ejecute Windows 10/11 x64.
2. Confirme que tiene privilegios de cuenta de administrador (el instalador activará un mensaje de elevación UAC).
3. Confirme que el cortafuegos permite el tráfico UDP entrante en el puerto 6500 (puerto de escucha de SoftAgent).
4. El paquete del instalador es autónomo — no es necesario instalar ningún runtime de .NET en la máquina de destino.

• Puede ejecutar programas como administrador (elevación UAC aceptada).
• El puerto UDP 6500 no está ocupado por otro programa.

• Varios PCs controlados pueden usar el mismo instalador — configure el puerto y la dirección de reporte de forma independiente en cada uno.
• Para proyectos de exposición, se recomienda configurar todos los PCs controlados con inicio de sesión automático con una cuenta de administrador para que la tarea de inicio automático se active de forma fiable.

Completar la instalación y confirmar que SoftAgent funciona normalmente en la bandeja del sistema.

1. Haga doble clic en SoftAgent-Setup-version.exe y haga clic en Sí en el mensaje UAC para permitir privilegios de administrador.
2. Siga el asistente del instalador para completar la instalación (predeterminado: C:\Program Files\SoftAgent\).
3. En la página de finalización, opcionalmente marque 'Iniciar SoftAgent ahora', o inícielo manualmente después.
4. Después del arranque, SoftAgent aparece en la bandeja del sistema (no se abre ninguna ventana principal).
5. Haga clic derecho en el ícono de la bandeja y seleccione 'Abrir configuración' — confirme que aparece la ventana principal con 4 pestañas (Propiedades / Programas / Watchdog / Configuración).

• El ícono de SoftAgent aparece en la bandeja del sistema.
• El Administrador de tareas muestra los procesos SoftAgent.App y SoftAgent.Watchdog en ejecución.
• El clic derecho en la bandeja muestra: Abrir configuración / Estado / Pausar Watchdog / Abrir directorio de registros / Acerca de / Salir.

SoftAgent usa una arquitectura de doble proceso: el proceso de la aplicación maneja la funcionalidad, y el Watchdog monitorea y reinicia automáticamente la aplicación si falla — se guardan mutuamente.

Completar la configuración básica y confirmar que el agente funciona mediante ping UDP.

1. Haga doble clic en el ícono de la bandeja para abrir la ventana principal, cambie a la pestaña Configuración.
2. Confirme que el puerto de escucha sea 6500 (o cambie según sea necesario), y marque 'Inicio automático' para registrar la tarea programada.
3. Para integración con SoftControl, ingrese la IP:puerto de la máquina SoftControl en el campo 'Dirección de reporte'.
4. Haga clic en 'Guardar y aplicar' para guardar la configuración.
5. Abra PowerShell y envíe un ping para verificar:
6. $u = New-Object System.Net.Sockets.UdpClient
7. $b = [Text.Encoding]::UTF8.GetBytes('ping')
8. $u.Send($b, $b.Length, '127.0.0.1', 6500)
9. $r = $u.Receive([ref](New-Object System.Net.IPEndPoint([Net.IPAddress]::Any, 0)))
10. [Text.Encoding]::UTF8.GetString($r)
11. Recibir ok:pong confirma que el agente funciona normalmente.

• Enviar ping recibe la respuesta ok:pong.
• La casilla de inicio automático en la pestaña Configuración está guardada.
• Ejecutar schtasks /Query /TN SoftAgent muestra la tarea programada registrada.

• Cambiar el puerto pero olvidar hacer clic en 'Guardar y aplicar', por lo que el cambio no surte efecto.
• Ingresar el puerto de la consola de administración HTTP en lugar del puerto de escucha UDP.

Dominar el formato de comandos y los niveles de riesgo para el uso seguro de SoftAgent.

1. Formato de comando: verbo o verbo:arg (el argumento sigue los primeros dos puntos), p. ej. volume:80 o ping.
2. Respuesta exitosa: ok:<código>, p. ej. ok:pong o ok:volume.
3. Respuesta fallida: err:<código>, p. ej. err:wol.invalidMac.
4. Tres niveles de riesgo: Seguro (sin interrupción, repetible) / Disruptivo (interrumpe la sesión/proceso pero sin pérdida de datos) / Destructivo (apagado/reinicio/cierre de sesión, etc.).
5. Los comandos destructivos muestran un cuadro de diálogo de confirmación en la interfaz. Cuando se activan remotamente, el llamador es responsable de confirmar la intención.

• Enviar ping recibe ok:pong, confirmando que la conexión y el formato de comando son correctos.
• Enviar describe recibe una lista de capacidades JSON con todos los comandos compatibles y sus niveles de riesgo.

El comando describe devuelve la lista completa de capacidades de esta instancia de SoftAgent, incluyendo el nombre, descripción, nivel de riesgo y si se requiere confirmación de cada comando — útil para el descubrimiento de capacidades al integrarse con SoftControl o sistemas de IA.

Dominar los comandos seguros para el control diario de volumen y monitoreo de estado.

1. Sondeo de conectividad: ping (responde ok:pong, confirma que el agente está en línea).
2. Obtener lista de capacidades: describe (devuelve JSON listando todos los comandos con descripciones y niveles de riesgo).
3. Descubrimiento de dispositivos: discover (devuelve un JSON de snapshot de latido con hostname, IP, MAC, volumen, estado del watchdog).
4. Subir volumen un paso: volup (predeterminado +5% por llamada).
5. Bajar volumen un paso: voldown (predeterminado -5% por llamada).
6. Alternar silencio: mute (alternar entre silenciado y sin silencio).
7. Obtener dirección MAC de la NIC principal: getmac (devuelve formato con guiones en mayúsculas, p. ej. AA-BB-CC-DD-EE-FF).
8. Enviar paquete mágico Wake-on-LAN: wol:AA-BB-CC-DD-EE-FF (despertar la máquina con la MAC especificada).
9. Simulación de teclado: key:^s (Ctrl+S), key:{F5} (tecla F5), key:Hola (escribir caracteres).

• El comando ping devuelve ok:pong.
• volup/voldown cambia el volumen de la máquina controlada.
• El comando wol despierta la máquina de destino (requiere WoL habilitado en el destino).

• Use discover para obtener rápidamente el estado actual de una máquina controlada (IP, volumen, estado del watchdog) — útil para verificaciones de salud en lote de SoftControl.
• key: usa la sintaxis SendKeys de Microsoft: ^ es Ctrl, % es Alt, + es Shift, teclas especiales entre llaves como {ENTER}.

Dominar los comandos de bloqueo de pantalla, inicio/parada de procesos y cancelación de apagado.

1. Bloquear pantalla: lock (bloquea la estación de trabajo actual — re-iniciar sesión para restaurar).
2. Cancelar un apagado/reinicio retrasado pendiente: cancelshutdown (usar durante la cuenta regresiva de apagado).
3. Iniciar un elemento del watchdog por ID: run:id (p. ej. run:db-player inicia el elemento llamado db-player).
4. Detener un elemento del watchdog por ID: stop:id (detiene y pausa el watchdog — el proceso no se reiniciará automáticamente).
5. Iniciar un programa gestionado por índice: startpro:0 (inicia el programa en el índice 0 en la lista de programas gestionados).
6. Detener un programa gestionado por índice: killpro:0.
7. Detener todos los programas gestionados: killall.

• Después de lock, la máquina controlada muestra la pantalla de bloqueo.
• Después de run:id, el elemento del watchdog correspondiente se inicia — el estado cambia de Detenido a En ejecución en la pestaña Watchdog.
• cancelshutdown enviado durante una cuenta regresiva de apagado cancela el apagado.

• Use run/stop con el ID del watchdog (un identificador estable) en lugar de startpro/killpro con índice (el índice cambia cuando se eliminan o reordenan elementos).
• Los IDs del watchdog se configuran en la pestaña Watchdog de SoftAgent. Actualice los comandos de SoftControl si cambia el nombre de un ID.

Ejecutar de forma segura operaciones destructivas como apagado, reinicio y cierre de sesión.

1. Apagado retrasado (recomendado): shutdown:60 (apagar después de 60 segundos, cancelshutdown puede cancelar durante la cuenta regresiva).
2. Apagado inmediato (usar con precaución): shutdown (sin retraso, no se puede cancelar).
3. Reinicio retrasado (recomendado): reboot:60 (reiniciar después de 60 segundos).
4. Reiniciar en BIOS/UEFI: reboot:firmware (requiere soporte de firmware UEFI).
5. Cerrar sesión del usuario actual: logoff (confirme que no hay datos sin guardar antes de ejecutar).
6. Habilitar/Deshabilitar UAC: uac:off / uac:on (cambio de registro, requiere reinicio para tomar efecto, requiere administrador).
7. Habilitar/Deshabilitar gestos de borde de la pantalla táctil: edgeswipe:off / edgeswipe:on.
8. Habilitar/Deshabilitar la reparación automática de inicio de Windows: autorepair:off / autorepair:on.

• Después de shutdown:60, el sistema muestra una notificación de cuenta regresiva 'apagando en 60 segundos'.
• cancelshutdown enviado durante la cuenta regresiva cancela el apagado.

• Enviar shutdown sin retraso, haciendo imposible cancelar — la máquina controlada se apaga de inmediato.
• Después de uac:off, no reiniciar y asumir que UAC ya está deshabilitado (requiere reinicio para tomar efecto).

Los comandos de apagado requieren privilegios de administrador. Si los permisos son insuficientes, se devuelve un código de error claro como err:power.denied — sin fallo silencioso.

Completar la configuración básica para que SoftAgent pueda ser correctamente descubierto y controlado por SoftControl.

1. Abra la ventana principal de SoftAgent y cambie a la pestaña Configuración.
2. Puerto de escucha (predeterminado 6500): SoftControl y otros controladores envían comandos UDP a este puerto.
3. Dirección de reporte (formato IP:puerto): SoftAgent envía JSON de latido periódico a esta dirección; ingrese la IP y el puerto de escucha de SoftControl.
4. Intervalo de latido (segundos): predeterminado 10 segundos; los latidos contienen hostname, IP, MAC, volumen, estado del watchdog, etc.
5. Retraso de inicio automático (segundos): retraso después del inicio de sesión antes de que SoftAgent se inicie (útil para esperar que la red esté lista).
6. Haga clic en 'Guardar y aplicar' después de los cambios — los cambios de puerto muestran un aviso persistente de 'Reinicio requerido'; otros cambios surten efecto de inmediato.

• La configuración surte efecto de inmediato después de guardar (los cambios de puerto requieren reinicio).
• Si se configura una dirección de reporte, SoftControl debería comenzar a recibir JSON de latido periódico de este SoftAgent.

• Para varios PCs controlados, se recomienda usar el mismo puerto (6500) en todos para simplificar la entrada de comandos en lote en SoftControl.
• Dejar la dirección de reporte vacía significa que SoftAgent no enviará latidos proactivamente pero seguirá respondiendo a los comandos UDP.

Modificar la configuración de IP de la máquina controlada a través de la interfaz de SoftAgent sin RDP.

1. Abra la ventana principal, cambie a la pestaña Propiedades y seleccione la tarjeta de red de destino en el menú desplegable del panel de red.
2. Después de seleccionar una NIC, la IP actual, la máscara de subred, la puerta de enlace, el DNS y la dirección MAC se rellenan automáticamente.
3. Cambie el modo 'IP estática / DHCP': los campos son editables en modo estático; de solo lectura en modo DHCP.
4. Rellene la IP de destino, la máscara de subred, la puerta de enlace y el DNS (modo estático).
5. Haga clic en 'Cambiar configuración de IP' y confirme en el cuadro de diálogo de confirmación.
6. El cambio de IP es una operación destructiva — la conexión actual cae después del cambio. Reconéctese con la nueva IP.

• Después del cambio, la máquina controlada puede hacerse ping correctamente en la nueva dirección IP.
• El JSON de latido de SoftAgent muestra la dirección IP actualizada.

Cambiar la IP es destructivo. Antes de continuar, confirme que la nueva IP es accesible en la LAN para evitar perder el acceso remoto a la máquina controlada.

Configurar el inicio automático para que SoftAgent se reanude automáticamente después de que el PC controlado se reinicie.

1. En la pestaña Configuración de la ventana principal, marque 'Inicio automático'.
2. Haga clic en 'Guardar y aplicar'.
3. Verifique con: schtasks /Query /TN SoftAgent en PowerShell — confirme que la tarea programada está registrada.
4. Disparador de tarea: ONLOGON (se activa después del inicio de sesión del usuario) con nivel de privilegio HIGHEST.
5. Para establecer un retraso de inicio (esperar red o servicios dependientes), establezca los segundos en el campo 'Retraso de inicio automático'.
6. Para deshabilitar el inicio automático, desmarque 'Inicio automático' y guarde.

• schtasks /Query /TN SoftAgent muestra que la tarea existe y está habilitada.
• Después de reiniciar el PC controlado, SoftAgent aparece automáticamente en la bandeja del sistema después del inicio de sesión.

Completar la configuración de comandos de SoftAgent en SoftControl para el control por botones de las máquinas controladas.

1. Entre en el panel de administración de SoftControl y abra Gestión de comandos.
2. Cree un nuevo comando, seleccione el protocolo UDP.
3. Establezca la dirección de destino en la IP del PC controlado (p. ej. 192.168.1.101).
4. Establezca el puerto en el puerto de escucha de SoftAgent (predeterminado 6500).
5. Establezca el texto del comando en el comando específico, p. ej.: volup (subir volumen), mute (alternar silencio), lock (bloquear pantalla), shutdown:60 (apagar en 60 s).
6. Guarde y pruebe el comando individualmente — confirme que la máquina controlada responde correctamente.
7. Vincule el comando verificado a un botón en la interfaz de usuario de SoftControl.

• Después de que SoftControl envía el comando UDP, el SoftAgent de la máquina controlada ejecuta la acción.
• Los registros de SoftControl muestran que el comando fue enviado correctamente (respuesta OK).

• Cree un conjunto de comandos para cada máquina controlada, usando el nombre del dispositivo como prefijo (p. ej. 'Sala-PC-01_Apagado') para facilitar el mantenimiento.
• Para operaciones en lote como cerrar la exposición, use los grupos de comandos de SoftControl — agregue comandos de apagado para múltiples máquinas a un grupo y actívelo una vez.

Configurar el reporte de latidos para monitorear el estado en línea de las máquinas controladas desde SoftControl.

1. En la configuración de SoftAgent, configure la dirección de reporte en la IP:puerto de SoftControl (interfaz UDP externa de SoftControl, predeterminado 8818).
2. SoftAgent envía inmediatamente un latido al arrancar, luego continúa al intervalo configurado (predeterminado 10 segundos).
3. El JSON de latido incluye: agentId (identificador único del dispositivo), hostname, ip/mac (información de red), volume/muted (estado de audio), guards (estados de los procesos del watchdog), uptimeSeconds.
4. Para consultar activamente el estado actual de una máquina controlada, envíe discover desde SoftControl — SoftAgent devuelve un snapshot de latido.
5. El campo guards en los latidos indica si los procesos del watchdog están funcionando normalmente, revelando fallos o estados de abandono.

• SoftControl recibe JSON de latido periódico de SoftAgent.
• Enviar discover recibe una respuesta JSON con hostname, IP, volumen y otra información.

Configurar el watchdog de reinicio automático tras fallos para aplicaciones de exposición.

1. Abra la ventana principal de SoftAgent y cambie a la pestaña Watchdog.
2. Haga clic en 'Examinar...' para seleccionar el .exe a vigilar, opcionalmente establezca un nombre e ID del watchdog (identificador estable usado para los comandos run/stop).
3. Haga clic en 'Agregar' para añadirlo a la lista del watchdog. El interruptor individual controla si el watchdog de este elemento está habilitado.
4. El interruptor maestro del watchdog está en la parte superior de la pestaña — deshabilitarlo pausa todo el watchdog (sincronizado con el menú 'Pausar Watchdog' de la bandeja).
5. Las insignias de estado muestran el estado de cada elemento: En ejecución / Detenido / Fallido / Abandonado (watchdog abandonado después de demasiados fallos en la ventana de tiempo).
6. Después de un fallo, SoftAgent reinicia con retroceso exponencial (inicial 5 segundos, doblando cada vez; abandonado después de superar el límite en la ventana de tiempo).

• El programa vigilado muestra el estado 'En ejecución' en la lista del watchdog.
• Matar manualmente el proceso vigilado y SoftAgent lo reinicia automáticamente después de un retraso.
• El campo guards del JSON de latido refleja los últimos estados del watchdog.

No cambie el ID del watchdog arbitrariamente — los comandos run/stop de SoftControl dependen de él. Si cambia el nombre de un ID, actualice los comandos de SoftControl correspondientes.

Restaurar el canal de control de comandos UDP.

1. Confirme que SoftAgent sea visible en la bandeja del sistema (el proceso está en ejecución).
2. Confirme que el puerto de envío coincida con el puerto de escucha configurado de SoftAgent (predeterminado 6500).
3. Compruebe si el Firewall de Windows permite el tráfico UDP entrante en el puerto 6500.
4. Pruebe ping desde localhost (127.0.0.1) primero para descartar problemas de red, luego pruebe remotamente.
5. Compruebe los archivos de registro en %ProgramData%\SoftAgent\logs\ para registros de recepción de comandos.

• Enviar ping a 127.0.0.1 recibe ok:pong, confirmando que SoftAgent y el puerto UDP están funcionando.
• Enviar ping desde una máquina remota también recibe una respuesta, confirmando que el camino de red está despejado.

Asegurarse de que SoftAgent se ejecute con privilegios de administrador para admitir todos los comandos a nivel del sistema.

1. Confirme que SoftAgent se ejecuta con derechos de administrador: el inicio automático usa el privilegio HIGHEST de la tarea programada; para inicio manual, haga clic derecho en el exe y 'Ejecutar como administrador'.
2. Si los comandos se activan a través de SoftControl, SoftControl en sí no necesita derechos de administrador — los privilegios los determina SoftAgent en el lado controlado.
3. Compruebe la columna 'Elevado' para SoftAgent.App.exe en la pestaña Detalles del Administrador de tareas — debería mostrar 'Sí'.
4. Si no se ejecuta como administrador, cierre SoftAgent y reinícielo como administrador.

• La pestaña Detalles del Administrador de tareas muestra 'Sí' en la columna Elevado para SoftAgent.App.exe.
• Los comandos volup/voldown responden normalmente (no se requiere administrador — útil para verificación básica).
• El comando lock bloquea la pantalla de la máquina controlada (nivel Disruptivo — confirma que el privilegio es correcto).

Diagnosticar y corregir fallos de inicio automático.

1. Ejecute schtasks /Query /TN SoftAgent en PowerShell para confirmar que la tarea programada existe.
2. Si la tarea no existe, abra la pestaña Configuración de SoftAgent, vuelva a marcar 'Inicio automático' y guarde.
3. Confirme que el PC usa inicio de sesión automático (común en exposiciones) en lugar de esperar el inicio de sesión manual — el disparador de la tarea es ONLOGON, requiriendo que un usuario inicie sesión.
4. Si está configurado para inicio de sesión automático, confirme que la cuenta de inicio de sesión automático tiene permisos para ejecutar la tarea (requiere cuenta de administrador).
5. Compruebe los registros recientes en %ProgramData%\SoftAgent\logs\ para razones de fallo de inicio.

• La salida de schtasks /Query /TN SoftAgent contiene el disparador ONLOGON y el privilegio HIGHEST.
• Después de reiniciar el PC controlado e iniciar sesión, SoftAgent aparece automáticamente en la bandeja del sistema.

Entender por qué el watchdog abandonó y restaurar el monitoreo de la aplicación objetivo.

1. En la pestaña Watchdog de la ventana principal de SoftAgent, compruebe la insignia de estado — confirma el estado 'Abandonado'.
2. Compruebe los archivos de registro en %ProgramData%\SoftAgent\logs\ para la razón específica del fallo (errores antes de cada fallo).
3. Corrija la causa raíz de los fallos de la aplicación vigilada (error de configuración, dependencia faltante, conflicto de puerto, etc.).
4. Después de corregir, cambie el interruptor individual del elemento del watchdog de apagado a encendido en la pestaña Watchdog (o envíe run:id desde SoftControl) para volver a activar el watchdog.
5. Confirme que el estado del elemento del watchdog cambia a 'En ejecución' y permanece estable con el tiempo.

• Después de corregir la aplicación vigilada, el estado del watchdog cambia de 'Abandonado' a 'En ejecución'.
• El JSON de latido muestra el estado del elemento del watchdog correspondiente actualizado a en ejecución.

El estado Abandonado es un comportamiento intencional para evitar tormentas de reinicio infinitas que impacten los recursos del sistema. La solución real es corregir la causa raíz del fallo — no volver a activar el watchdog manualmente de forma repetida.