Manual do Utilizador SoftAgent

Confirmar que o ambiente cumpre os requisitos e preparar para a instalação.

1. Confirme que o PC de destino está a executar Windows 10/11 x64.
2. Confirme que tem privilégios de conta de administrador (o instalador irá acionar um pedido de elevação UAC).
3. Confirme que a firewall permite tráfego UDP de entrada na porta 6500 (porta de escuta do SoftAgent).
4. O pacote do instalador é autossuficiente — não é necessário pré-instalar nenhum runtime .NET na máquina de destino.

• Pode executar programas como administrador (elevação UAC aceite).
• A porta UDP 6500 não está ocupada por outro programa.

• Múltiplos PCs controlados podem usar o mesmo instalador — configure porta e endereço de reporte independentemente em cada um.
• Para projetos de exposição, recomenda-se configurar todos os PCs controlados para login automático com uma conta de administrador para que a tarefa de início automático seja acionada de forma fiável.

Completar a instalação e confirmar que SoftAgent está a executar normalmente na bandeja do sistema.

1. Clique duas vezes em SoftAgent-Setup-versão.exe e clique em Sim no pedido UAC para permitir privilégios de administrador.
2. Siga o assistente do instalador para completar a instalação (predefinição: C:\Program Files\SoftAgent\).
3. Na página de conclusão, opcionalmente marque 'Iniciar SoftAgent agora', ou inicie manualmente depois.
4. Após o arranque, SoftAgent aparece na bandeja do sistema (sem janela principal aberta).
5. Clique com o botão direito no ícone da bandeja e selecione 'Abrir Configuração' — confirme que a janela principal aparece com 4 separadores (Propriedades / Programas / Watchdog / Definições).

• O ícone SoftAgent aparece na bandeja do sistema.
• O Gestor de Tarefas mostra os processos SoftAgent.App e SoftAgent.Watchdog em execução.
• Clicar com o botão direito na bandeja mostra: Abrir Configuração / Estado / Pausar Watchdog / Abrir Diretório de Logs / Sobre / Sair.

SoftAgent usa uma arquitetura de processo duplo: o processo App trata da funcionalidade, e o Watchdog monitoriza e reinicia automaticamente a App em caso de falha — guardam-se mutuamente.

Completar a configuração básica e confirmar que o agente funciona via ping UDP.

1. Clique duas vezes no ícone da bandeja para abrir a janela principal, mude para o separador Definições.
2. Confirme que a porta de escuta é 6500 (ou altere conforme necessário) e marque 'Início automático' para registar a tarefa agendada.
3. Para integração com SoftControl, introduza o IP:porta da máquina SoftControl no campo 'Endereço de Reporte'.
4. Clique em 'Guardar e Aplicar' para guardar a configuração.
5. Abra o PowerShell e envie um 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. Receber ok:pong confirma que o agente está a funcionar normalmente.

• Enviar ping recebe resposta ok:pong.
• A caixa de seleção Início automático no separador Definições está guardada.
• Executar schtasks /Query /TN SoftAgent mostra a tarefa agendada registada.

• Alterar a porta mas esquecer de clicar em 'Guardar e Aplicar', por isso a alteração não tem efeito.
• Introduzir a porta da consola de gestão HTTP em vez da porta de escuta UDP.

Dominar o formato de comando e os níveis de risco para uso seguro do SoftAgent.

1. Formato de comando: verbo ou verbo:arg (o argumento segue os dois pontos iniciais), por exemplo volume:80 ou ping.
2. Resposta de sucesso: ok:<código>, por exemplo ok:pong ou ok:volume.
3. Resposta de falha: err:<código>, por exemplo err:wol.invalidMac.
4. Três níveis de risco: Seguro (sem perturbação, repetível) / Perturbador (interrompe sessão/processo mas sem perda de dados) / Destrutivo (desligamento/reinício/logoff etc.).
5. Comandos destrutivos mostram um diálogo de confirmação na UI. Quando acionados remotamente, o chamador é responsável por confirmar a intenção.

• Enviar ping recebe ok:pong, confirmando que a ligação e o formato do comando estão corretos.
• Enviar describe recebe uma lista de capacidades JSON com todos os comandos suportados e os seus níveis de risco.

O comando describe devolve a lista completa de capacidades desta instância SoftAgent, incluindo o nome, descrição, nível de risco e se é necessária confirmação de cada comando — útil para descoberta de capacidades ao integrar com SoftControl ou sistemas de IA.

Dominar os comandos Seguros para controlo de volume e monitorização de estado diários.

1. Sonda de conectividade: ping (responde ok:pong, confirma que o agente está online).
2. Obter lista de capacidades: describe (devolve JSON listando todos os comandos com descrições e níveis de risco).
3. Descoberta de dispositivos: discover (devolve um JSON de snapshot de heartbeat com hostname, IP, MAC, volume, estado do guarda).
4. Aumentar volume um passo: volup (predefinição +5% por chamada).
5. Diminuir volume um passo: voldown (predefinição -5% por chamada).
6. Alternar silêncio: mute (alternar entre silenciado e com som).
7. Obter endereço MAC da NIC principal: getmac (devolve formato maiúsculas separado por hífens, por exemplo AA-BB-CC-DD-EE-FF).
8. Enviar pacote mágico Wake-on-LAN: wol:AA-BB-CC-DD-EE-FF (acordar a máquina com o MAC especificado).
9. Simulação de teclado: key:^s (Ctrl+S), key:{F5} (tecla F5), key:Olá (digitar caracteres).

• O comando ping devolve ok:pong.
• volup/voldown altera o volume da máquina controlada.
• O comando wol acorda a máquina de destino (requer WoL ativado no destino).

• Use discover para obter rapidamente o estado atual de uma máquina controlada (IP, volume, estado do guarda) — útil para verificações de saúde em lote do SoftControl.
• key: usa a sintaxe Microsoft SendKeys: ^ é Ctrl, % é Alt, + é Shift, teclas especiais entre chavetas como {ENTER}.

Dominar bloqueio de ecrã, início/paragem de processos e comandos de cancelamento de desligamento.

1. Bloquear ecrã: lock (bloqueia o posto de trabalho atual — requer novo login para restaurar).
2. Cancelar um desligamento/reinício atrasado pendente: cancelshutdown (usar durante a contagem decrescente de desligamento).
3. Iniciar um item do watchdog por ID: run:id (por exemplo run:db-player inicia o item chamado db-player).
4. Parar um item do watchdog por ID: stop:id (para e pausa o watchdog — o processo não será reiniciado automaticamente).
5. Iniciar um programa gerido por índice: startpro:0 (inicia o programa no índice 0 na lista de programas geridos).
6. Parar um programa gerido por índice: killpro:0.
7. Parar todos os programas geridos: killall.

• Após lock, a máquina controlada mostra o ecrã de bloqueio.
• Após run:id, o item do watchdog correspondente inicia — o estado muda de Parado para Em Execução no separador Watchdog.
• cancelshutdown enviado durante uma contagem decrescente de desligamento cancela o desligamento.

• Use run/stop com ID do watchdog (um identificador estável) em vez de startpro/killpro com índice (o índice muda quando itens são eliminados ou reordenados).
• Os IDs do watchdog são configurados no separador Watchdog do SoftAgent. Atualize os comandos SoftControl se renomear um ID.

Executar com segurança operações destrutivas como desligamento, reinício e logoff.

1. Desligamento atrasado (recomendado): shutdown:60 (desligar após 60 segundos, cancelshutdown pode cancelar durante a contagem decrescente).
2. Desligamento imediato (usar com cautela): shutdown (sem atraso, não pode cancelar).
3. Reinício atrasado (recomendado): reboot:60 (reiniciar após 60 segundos).
4. Reiniciar para BIOS/UEFI: reboot:firmware (requer suporte de firmware UEFI).
5. Logoff do utilizador atual: logoff (confirme que não há dados não guardados antes de executar).
6. Ativar/Desativar UAC: uac:off / uac:on (alteração de registo, requer reinício para ter efeito, requer administrador).
7. Ativar/Desativar gestos de borda do ecrã tátil: edgeswipe:off / edgeswipe:on.
8. Ativar/Desativar reparação automática de arranque do Windows: autorepair:off / autorepair:on.

• Após shutdown:60, o sistema mostra uma notificação de contagem decrescente 'a desligar em 60 segundos'.
• cancelshutdown enviado durante a contagem decrescente cancela o desligamento.

• Enviar shutdown sem atraso, tornando impossível cancelar — a máquina controlada desliga imediatamente.
• Após uac:off, não reiniciar e assumir que o UAC já está desativado (requer reinício para ter efeito).

Os comandos de desligamento requerem privilégios de administrador. Se as permissões forem insuficientes, é devolvido um código de erro claro como err:power.denied — sem falha silenciosa.

Completar a configuração básica para que o SoftAgent possa ser corretamente descoberto e controlado pelo SoftControl.

1. Abra a janela principal do SoftAgent e mude para o separador Definições.
2. Porta de Escuta (predefinição 6500): SoftControl e outros controladores enviam comandos UDP para esta porta.
3. Endereço de Reporte (formato IP:porta): SoftAgent envia heartbeat JSON periódico para este endereço; introduza o IP e a porta de escuta do SoftControl.
4. Intervalo de Heartbeat (segundos): predefinição 10 segundos; os heartbeats contêm hostname, IP, MAC, volume, estado do guarda, etc.
5. Atraso de Início Automático (segundos): atraso após o login antes de SoftAgent iniciar (útil para aguardar a disponibilidade da rede).
6. Clique em 'Guardar e Aplicar' após alterações — alterações de porta mostram um aviso persistente 'Reinício Necessário'; outras alterações têm efeito imediato.

• A configuração tem efeito imediato após guardar (alterações de porta requerem reinício).
• Se um endereço de reporte estiver configurado, o SoftControl deverá começar a receber heartbeat JSON periódico deste SoftAgent.

• Para múltiplos PCs controlados, recomenda-se usar a mesma porta (6500) em todos para simplificar a introdução de comandos em lote no SoftControl.
• Deixar o endereço de reporte vazio significa que o SoftAgent não enviará heartbeats proativamente mas ainda responderá a comandos UDP.

Modificar a configuração de IP da máquina controlada através da interface do SoftAgent sem RDP.

1. Abra a janela principal, mude para o separador Propriedades e selecione a placa de rede de destino no menu suspenso do painel de rede.
2. Após selecionar uma NIC, IP atual, máscara de sub-rede, gateway, DNS e endereço MAC são preenchidos automaticamente.
3. Alterne o modo 'IP Estático / DHCP': os campos são editáveis no modo Estático; só de leitura no modo DHCP.
4. Preencha o IP de destino, máscara de sub-rede, gateway e DNS (modo Estático).
5. Clique em 'Alterar Definições de IP' e confirme no diálogo de confirmação.
6. A alteração de IP é uma operação destrutiva — a ligação atual cai após a alteração. Reconecte com o novo IP.

• Após a alteração, a máquina controlada pode ser pingada com sucesso no novo endereço IP.
• O heartbeat JSON do SoftAgent mostra o endereço IP atualizado.

Alterar IP é destrutivo. Antes de prosseguir, confirme que o novo IP é alcançável na LAN para evitar perder o acesso remoto à máquina controlada.

Configurar o início automático para que SoftAgent retome automaticamente a execução após reinício do PC controlado.

1. No separador Definições da janela principal, marque 'Início automático'.
2. Clique em 'Guardar e Aplicar'.
3. Verifique com: schtasks /Query /TN SoftAgent no PowerShell — confirme que a tarefa agendada está registada.
4. Acionador da tarefa: ONLOGON (aciona após login do utilizador) com nível de privilégio HIGHEST.
5. Para definir um atraso de arranque (aguardar rede ou serviços dependentes), defina segundos no campo 'Atraso de Início Automático'.
6. Para desativar o início automático, desmarque 'Início automático' e guarde.

• schtasks /Query /TN SoftAgent mostra que a tarefa existe e está ativada.
• Após reiniciar o PC controlado, SoftAgent aparece automaticamente na bandeja do sistema após o login.

Completar a configuração de comandos SoftAgent no SoftControl para controlo de máquinas controladas baseado em botões.

1. Entre no painel de administração do SoftControl e abra a Gestão de Comandos.
2. Crie um novo comando, selecione protocolo UDP.
3. Defina o endereço de destino para o IP do PC controlado (por exemplo 192.168.1.101).
4. Defina a porta para a porta de escuta do SoftAgent (predefinição 6500).
5. Defina o texto do comando para o comando específico, por exemplo: volup (aumentar volume), mute (alternar silêncio), lock (bloquear ecrã), shutdown:60 (desligar em 60s).
6. Guarde e teste o comando individualmente — confirme que a máquina controlada responde corretamente.
7. Vincule o comando verificado a um botão na interface front-end do SoftControl.

• Após o SoftControl enviar o comando UDP, o SoftAgent da máquina controlada executa a ação.
• Os logs do SoftControl mostram que o comando foi enviado com sucesso (resposta OK).

• Crie um conjunto de comandos para cada máquina controlada, usando o nome do dispositivo como prefixo (por exemplo 'Sala-PC-01_Desligar') para facilitar a manutenção.
• Para operações em lote como fechar a exposição, use os grupos de comandos do SoftControl — adicione comandos de desligamento para múltiplas máquinas a um grupo e acione uma vez.

Configurar o reporte de heartbeat para monitorizar o estado online das máquinas controladas a partir do SoftControl.

1. Nas definições do SoftAgent, configure o endereço de reporte para o IP:porta do SoftControl (interface UDP externa do SoftControl, predefinição 8818).
2. SoftAgent envia imediatamente um heartbeat no arranque e depois continua no intervalo configurado (predefinição 10 segundos).
3. O heartbeat JSON inclui: agentId (identificador único do dispositivo), hostname, ip/mac (informação de rede), volume/muted (estado de áudio), guards (estados dos processos watchdog), uptimeSeconds.
4. Para consultar ativamente o estado atual de uma máquina controlada, envie discover a partir do SoftControl — SoftAgent devolve um snapshot de heartbeat.
5. O campo guards nos heartbeats indica se os processos watchdog estão a funcionar normalmente, revelando falhas ou estados de abandono.

• SoftControl recebe heartbeat JSON periódico do SoftAgent.
• Enviar discover recebe uma resposta JSON com hostname, IP, volume e outras informações.

Configurar watchdog de reinício automático após falha para aplicações de exposição.

1. Abra a janela principal do SoftAgent e mude para o separador Watchdog.
2. Clique em 'Procurar...' para selecionar o .exe a guardar, defina opcionalmente um nome e ID do watchdog (identificador estável usado para comandos run/stop).
3. Clique em 'Adicionar' para colocá-lo na lista do watchdog. O controlo individual alterna se o watchdog deste item está ativado.
4. O controlo principal do watchdog está no topo do separador — desativar pausa todo o watchdog (sincronizado com o menu 'Pausar Watchdog' da bandeja).
5. Os emblemas de estado mostram o estado de cada item: Em Execução / Parado / Com Falha / Abandonado (watchdog abandonado após demasiadas falhas na janela de tempo).
6. Após uma falha, SoftAgent reinicia com backoff exponencial (inicial 5 segundos, duplicando cada vez; abandonado após limite excedido na janela de tempo).

• O programa guardado mostra estado 'Em Execução' na lista do watchdog.
• Matar manualmente o processo guardado e SoftAgent reinicia-o automaticamente após um atraso.
• O campo guards do heartbeat JSON reflete os estados mais recentes do watchdog.

Não altere o ID do watchdog arbitrariamente — os comandos run/stop do SoftControl dependem dele. Se renomear um ID, atualize os comandos SoftControl correspondentes.

Restaurar o canal de controlo por comando UDP.

1. Confirme que o SoftAgent está visível na bandeja do sistema (processo em execução).
2. Confirme que a porta de envio corresponde à porta de escuta configurada do SoftAgent (predefinição 6500).
3. Verifique se a Firewall do Windows permite tráfego UDP de entrada na porta 6500.
4. Tente ping a partir do localhost (127.0.0.1) primeiro para descartar problemas de rede, depois tente remotamente.
5. Verifique os ficheiros de log em %ProgramData%\SoftAgent\logs\ para registos de receção de comandos.

• Enviar ping para 127.0.0.1 recebe ok:pong, confirmando que SoftAgent e a porta UDP estão a funcionar.
• Enviar ping de uma máquina remota também recebe resposta, confirmando que o caminho de rede está limpo.

Garantir que SoftAgent executa com privilégios de administrador para suportar todos os comandos a nível de sistema.

1. Confirme que SoftAgent executa com direitos de administrador: o início automático usa privilégio HIGHEST da tarefa agendada; para início manual, clique com o botão direito no exe e 'Executar como administrador'.
2. Se os comandos forem acionados via SoftControl, o próprio SoftControl não precisa de direitos de administrador — os privilégios são determinados pelo SoftAgent no lado controlado.
3. Verifique a coluna 'Elevado' para SoftAgent.App.exe no separador Detalhes do Gestor de Tarefas — deve mostrar 'Sim'.
4. Se não estiver a executar como administrador, saia do SoftAgent e reinicie-o como administrador.

• O separador Detalhes do Gestor de Tarefas mostra 'Sim' na coluna Elevado para SoftAgent.App.exe.
• Os comandos volup/voldown respondem normalmente (não requerem administrador — útil para verificação básica).
• O comando lock bloqueia o ecrã da máquina controlada (nível Perturbador — confirma que o privilégio está correto).

Diagnosticar e corrigir falhas de início automático.

1. Execute schtasks /Query /TN SoftAgent no PowerShell para confirmar que a tarefa agendada existe.
2. Se a tarefa não existir, abra o separador Definições do SoftAgent, remarque 'Início automático' e guarde.
3. Confirme que o PC usa login automático (comum em exposições) em vez de aguardar login manual — o acionador da tarefa é ONLOGON, requerendo que um utilizador faça login.
4. Se configurado para login automático, confirme que a conta de login automático tem permissões para executar a tarefa (requer conta de administrador).
5. Verifique logs recentes em %ProgramData%\SoftAgent\logs\ para razões de falha de arranque.

• A saída de schtasks /Query /TN SoftAgent contém o acionador ONLOGON e privilégio HIGHEST.
• Após reiniciar o PC controlado e fazer login, SoftAgent aparece automaticamente na bandeja do sistema.

Compreender por que o watchdog abandonou e restaurar a monitorização da aplicação de destino.

1. No separador Watchdog da janela principal do SoftAgent, verifique o emblema de estado — confirma o estado 'Abandonado'.
2. Verifique os ficheiros de log em %ProgramData%\SoftAgent\logs\ para a razão específica da falha (erros antes de cada falha).
3. Corrija a causa raiz das falhas da aplicação guardada (erro de configuração, dependência em falta, conflito de porta, etc.).
4. Após corrigir, alterne o interruptor individual do item do watchdog para desligado e depois para ligado no separador Watchdog (ou envie run:id do SoftControl) para re-acionar o watchdog.
5. Confirme que o estado do item do watchdog muda para 'Em Execução' e permanece estável ao longo do tempo.

• Após corrigir a aplicação guardada, o estado do watchdog muda de 'Abandonado' para 'Em Execução'.
• O heartbeat JSON mostra o estado do item watchdog correspondente atualizado para em execução.

Abandonado é comportamento intencional para evitar que tempestades de reinício infinito impactem os recursos do sistema. A solução real é corrigir a causa raiz da falha — não re-acionar manualmente o watchdog repetidamente.