Data de publicação: 13/04/2026
🎯 Objetivo
Explicar o que é o WebAgent, quando ele é necessário no uso do WebApp, quais são seus requisitos de compatibilidade, como ocorre a instalação e quais cuidados de segurança e homologação devem ser observados no ambiente Protheus. (TDN)
🧩 Ambiente
A documentação técnica da TOTVS informa que a página foi atualizada em 08/04/2026 e apresenta a compatibilidade entre versões do WebAgent, Application Server, WebApp e Lib Protheus. Para WebAgent 1.0.24 ou inferior, o cenário indicado envolve Application Server 20.3.0.x ou superior, WebApp 9.0 ou superior e Lib Protheus 12.1.2210 ou superior. Já para WebAgent 1.1.0 ou superior, a referência passa para Application Server 24.3.0.0 ou superior, WebApp 10.2.0 ou superior e Lib Protheus 12.1.2410 ou superior. (TDN)
🔎 O que é o WebAgent
O WebAgent é um serviço opcional utilizado somente nas estações que precisam de recursos locais, como leitura e gravação de arquivos locais, integração com Microsoft Office e integração com DLLs no Windows, bibliotecas no Linux e dylibs no macOS. Para rotinas padrão do ERP, como cadastros e relatórios, a própria TOTVS informa que não existe impedimento para usar o sistema sem o WebAgent. (TDN)
Na prática, isso significa que o WebAgent não é um requisito universal para todo acesso via navegador. Ele entra em cena quando o processo depende de interação com recursos instalados na máquina do usuário. Essa interpretação decorre diretamente da lista de funcionalidades locais descritas na documentação. (TDN)
🔐 Segurança da solução
A TOTVS destaca que os navegadores operam em ambiente de sandbox, o que bloqueia acessos diretos à estação de trabalho. Para viabilizar esse acesso de forma controlada, o WebAgent utiliza conexão exclusivamente via WebSocket Secure (WSS), comunicação restrita ao endereço localhost e o mesmo protocolo de comunicação usado entre SmartClient Desktop e AppServer. (TDN)
A documentação também informa a implementação de JWT a partir do WebAgent 1.1.0, com validação cruzada de origem durante o handshake. Para esse processo funcionar corretamente, a TOTVS exige WebAgent 1.1.0 ou superior e WebApp 10.2.0 ou superior. (TDN)
✅ Vantagens do uso com WebApp
Segundo a TOTVS, entre as vantagens do uso do WebAgent em conjunto com o WebApp estão:
simplificação na montagem de ambientes;
instalação simples e rápida;
ambiente HTML sempre atualizado, preparado para frameworks modernos de mercado. (TDN)
⚠️ Cuidados em estações compartilhadas
A TOTVS orienta que não é seguro compartilhar a mesma sessão do WebAgent entre dois usuários do Windows. Em estações compartilhadas, manter uma instância aberta após logout pode comprometer funções que retornam dados do usuário, como a função GetCredential, pois ela pode devolver informações do usuário que iniciou o WebAgent, e não necessariamente do usuário atual da estação. (TDN)
Nesses cenários, a orientação é usar o parâmetro Launch, que inicia o WebAgent em porta efêmera, abre automaticamente o navegador para o usuário e encerra o processo alguns minutos após o fechamento do navegador. (TDN)
🛠️ Instalação e distribuição
Para administradores, os instaladores do WebAgent devem ser obtidos na Central de Downloads da TOTVS. A documentação apresenta dois modelos de distribuição do instalador:
Via AppServer.ini, liberado a partir do WebApp 9.0.3, seguindo o padrão já conhecido de configuração do Protheus.
Via arquivo JSON, liberado a partir do WebApp 9.0.0, permitindo compartilhar uma única configuração entre vários AppServers. (TDN)
A TOTVS também informa que, após ajustar essas configurações, é necessário reiniciar o AppServer. Além disso, a partir do WebAgent 1.0.15, o instalador para Windows também passou a ser distribuído em formato MSI, permitindo instalação remota via GPO. (TDN)
Configuração via AppServer.ini
Na configuração por AppServer.ini, o parâmetro VERSION define a versão dos instaladores disponíveis para download. A TOTVS ressalta que, sempre que os instaladores forem atualizados na pasta de download, essa versão também precisa ser ajustada no arquivo. O parâmetro também pode ser usado tanto para upgrade quanto para downgrade do WebAgent. (TDN)
Configuração via WebAgent.json
Na configuração por WebAgent.json, o arquivo pode ser referenciado pelo parâmetro agentJsonUpdate na seção [WEBAPP] do AppServer.ini. A documentação mostra que o JSON pode centralizar os caminhos dos instaladores para Windows x86, Windows x64, macOS universal e Linux x64, facilitando o compartilhamento entre múltiplos AppServers. (TDN)
Porta fixa para todos os usuários
A TOTVS também prevê configuração de porta específica para o WebAgent de todos os usuários por meio da seção [WEBAGENT], como no exemplo com a porta 21021. A documentação alerta que essa configuração impede que os usuários alterem a porta e também pode impedir o uso do ERP sem o WebAgent instalado e registrado na estação. (TDN)
🔏 Certificado SSL
Para uso do WSS, é necessário registrar o TOTVS Certificate no sistema operacional. A documentação faz um alerta importante: devem ser usados os certificados disponibilizados na pasta de instalação do WebAgent, e não os certificados da pasta de instalação do AppServer. (TDN)
⚙️ Habilitando o WebAgent na tela de parâmetros
Para habilitar o uso do WebAgent no WebApp, a TOTVS orienta acessar a Tela de Parâmetros, clicar no botão de configuração e escolher a porta de inicialização do WebAgent, cujo padrão é 21021. Depois disso, basta fechar a janela de configuração e confirmar os dados. Nesse momento, o navegador poderá exibir uma solicitação de autorização para abertura do WebAgent. Se a conexão falhar ou a autorização for ignorada, o sistema apresentará mensagem de erro. (TDN)
💻 Sistemas operacionais homologados
A documentação informa que o WebAgent não é homologado para navegadores utilizados por Metaframes, RDPs ou Web enablers, citando como exemplo Citrix, Windows Remote Desktop, Go Global e VMWare Horizon. (TDN)
Quanto a sistemas operacionais homologados, a página lista suporte para:
Windows 10 Pro/Enterprise
Windows 11 Pro/Enterprise (TDN)
✅ Resultado esperado
Com o ambiente corretamente configurado, o WebApp passa a utilizar o WebAgent apenas quando houver necessidade de integração com recursos locais da estação, mantendo o acesso via navegador com mais segurança, padronização e compatibilidade com os recursos avançados do Protheus. Essa conclusão decorre do conjunto de requisitos, fluxos de instalação e controles de segurança descritos pela TOTVS. (TDN)
❓ FAQ
1. O WebAgent é obrigatório para usar o WebApp?
Não. Ele é opcional e só é necessário nas estações que precisam acessar recursos locais, como arquivos, Microsoft Office ou bibliotecas do sistema operacional. (TDN)
2. Posso usar o WebAgent em estação compartilhada?
Pode, mas a TOTVS orienta não compartilhar a mesma sessão entre usuários do Windows. Para esse cenário, o recomendado é usar o modo Launch com porta efêmera. (TDN)
3. É possível distribuir o instalador automaticamente?
Sim. A documentação prevê distribuição via AppServer.ini ou via WebAgent.json, além de instalação remota por MSI/GPO em Windows a partir do WebAgent 1.0.15. (TDN)
4. Qual porta padrão do WebAgent?
A porta padrão indicada na tela de parâmetros é 21021. (TDN)
5. Preciso configurar certificado?
Sim. Para usar WebSocket Secure (WSS), é necessário registrar o certificado da TOTVS no sistema operacional, usando os arquivos da pasta de instalação do WebAgent. (TDN)
6. O WebAgent é homologado para Citrix e RDP?
Não. A documentação informa que ele não é homologado para Citrix, Windows Remote Desktop, Go Global e VMWare Horizon. (TDN)
👤 Autor
Fabrizio Augusto Ventavolo
Consultor Especialista TOTVS — Mastersiga Consultoria
“Conectamos tecnologia, processos e pessoas para acelerar resultados com excelência em sistemas TOTVS.”