Como ligar o Hermes Agent ao Telegram e gerir tarefas a partir do telemóvel

Pode enviar mensagens ao Hermes Agent ou ditar-lhe tarefas no Telegram a partir do telemóvel quando estiver longe do computador e receber o resultado na mesma conversa. Os resultados das tarefas agendadas chegam à conversa que designar como a sua conversa principal, uma única vez.

Se ainda não tem o Hermes, comece pelo guia sobre o que é este agente e como o instalar e depois volte para ligar o Telegram.

Estão disponíveis instruções adicionais na documentação da Ailoot.

O que precisa para ligar o Hermes Agent ao Telegram?#

O comando hermes doctor verifica a instalação do Hermes e a ligação ao modelo. Vamos criar o bot na aplicação Telegram e precisará de um computador para executar comandos no terminal.

Como criar um bot através do BotFather?#

Todos os bots do Telegram têm um token — uma chave secreta para controlar o bot. É emitido pelo bot oficial do Telegram, o @BotFather.

1. Abra o @BotFather

   Pesquise por @BotFather no Telegram ou abra t.me/BotFather. O BotFather verdadeiro tem um visto azul de verificação. Inicie a conversa tocando em “Start”.

2. Envie o comando /newbot

   O BotFather pedir-lhe-á dois nomes. O primeiro é o nome de apresentação; pode ser qualquer um, por exemplo, “O Meu Agente”. O segundo é o nome de utilizador: tem de ser único e terminar em bot, por exemplo, moy_agent_bot.

3. Obtenha o token

   O BotFather enviar-lhe-á uma mensagem de felicitações e uma sequência longa no formato 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Este é o token do bot. Copie a sequência completa.

Também existe uma forma rápida que dispensa uma conversa manual com o BotFather. No painel Web do Hermes (hermes dashboard) e na aplicação para computador, na página “Messaging → Telegram”, existe um botão “Create with QR”: leia o código com o telemóvel e o Hermes cria um bot, deteta o seu ID, guarda o token nas definições e reinicia o gateway. Os passos abaixo descrevem o método manual; se escolheu o QR, avance diretamente para a verificação da ligação.

Como encontrar o seu ID do Telegram e para que precisa dele?#

Uma conta do Telegram tem dois identificadores: um nome de utilizador público com @ e um ID numérico interno. O Hermes usa o número.

O método rápido «Criar com QR» descrito acima deteta automaticamente o seu ID. Anote-o junto ao token.

Como fornecer o token ao Hermes Agent e iniciar o gateway?#

1. Execute o assistente de configuração

   hermes gateway setup
   

   Execute o comando na máquina onde o Hermes está instalado. O assistente apresentará uma lista de aplicações de mensagens.

2. Selecione Telegram e introduza os seus dados

   O assistente pedir-lhe-á o token do bot e os IDs autorizados (pode introduzir vários, separados por vírgulas) e guardará tudo nas próprias definições.

3. Inicie o gateway

   hermes gateway
   

   O gateway iniciará e ligar-se-á ao Telegram. Após alguns segundos, envie qualquer mensagem ao bot pela aplicação: se o Hermes responder, a ligação está pronta.

O método manual, em vez de usar o assistente, é assim: abra o ficheiro ~/.hermes/.env e adicione duas linhas, substituindo os valores pelo token do BotFather e pelo seu ID numérico:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

A segunda linha autoriza essas pessoas nas conversas privadas e nos grupos; uma autorização separada do chat de grupo também pode conceder acesso. Separe várias pessoas com vírgulas. Depois de guardar o ficheiro, inicie o gateway com o mesmo comando hermes gateway.

Se o bot continuar sem responder, mesmo numa conversa privada, verifique os registos do gateway no mesmo terminal e confirme primeiro o token e o seu ID na lista de acesso; os restantes erros estão descritos na tabela no fim do artigo.

O que pode fazer o bot do Telegram no seu telemóvel?#

Há cinco funcionalidades de que mais precisará no telemóvel.

Mensagens de texto e de voz. Escreva uma tarefa ou dite uma mensagem de voz — com o reconhecimento de voz configurado, o Hermes transcreve-a e compreende-a. Com um fornecedor local, não são necessárias chaves; tudo é processado na máquina onde o agente é executado.

Ficheiros e imagens. Pode reencaminhar um documento, uma folha de cálculo ou uma captura de ecrã para o bot — o agente recebe-o como anexo. Também pode enviar ficheiros gerados: peça um relatório e ele enviá-lo-á como ficheiro na conversa.

Confirmações para ações perigosas. Quando o agente está prestes a fazer algo arriscado, como apagar ficheiros, pergunta primeiro na conversa: responda “yes” ou “y” para o fazer; responda “no” ou “n” para cancelar.

Botões em vez de escrever uma resposta. Quando o agente precisa de esclarecimentos, envia uma pergunta com botões de opções inline — toque numa opção e o agente continua a trabalhar. O comando /model sem argumentos apresenta um menu de seleção de modelos com botões do mesmo tipo.

Notificações silenciosas. Por predefinição, o telemóvel só toca para respostas finais, pedidos de confirmação e confirmações de comandos. As notificações de serviço, como “a chamar uma ferramenta” e “a comprimir o contexto”, chegam silenciosamente, para o telemóvel não tocar a cada passo. Se quiser notificações sonoras em todos os passos, altere o modo nas definições.

Como receber na conversa os resultados de tarefas em segundo plano?#

Conversa principal para tarefas agendadas. O Hermes suporta tarefas agendadas: “todas as manhãs às 7:43, prepara-me um resumo”. Envia os resultados para a conversa principal, que designa uma única vez enviando o comando /sethome diretamente na conversa com o bot. Enquanto o gateway estiver em execução, os resumos chegam automaticamente.

Tarefas em segundo plano. Pode enviar uma tarefa longa para ser executada em segundo plano e continuar com o seu dia: o bot enviará uma mensagem quando estiver pronta. Uma tarefa iniciada a partir de um tópico devolve a resposta a esse mesmo tópico, para que nada se perca.

Limitação importante: o bot só responde enquanto o gateway estiver em execução. Se desligar ou suspender o computador onde o Hermes está a correr, o bot não responderá até a máquina voltar a estar em funcionamento. Para manter o bot sempre online, transfira o agente para um servidor: temos um guia separado sobre como manter o Hermes Agent em funcionamento permanente. Por predefinição, o gateway consulta o Telegram à procura de mensagens novas; para plataformas cloud que entram em suspensão sem tráfego recebido, a documentação oferece um modo webhook, que inverte o sentido da ligação para que o próprio Telegram envie pedidos ao bot.

Como impedir que estranhos acedam ao bot?#

O seu bot pode ser encontrado na pesquisa do Telegram pelo nome de utilizador, pelo que a proteção depende de duas coisas: a lista de acesso e manter o token secreto.

Configure primeiro o acesso por remetente com TELEGRAM_ALLOWED_USERS. Nos grupos, examine também TELEGRAM_GROUP_ALLOWED_CHATS: incluir aí um chat permite o acesso a qualquer membro, mesmo sem o seu ID na lista pessoal. Uma lista pessoal vazia não prova, por isso, que todos os grupos estejam fechados.

Depois, há o token. Não pode aparecer em capturas de ecrã, mensagens reencaminhadas ou repositórios. Se o token for divulgado, revogue-o com o comando /revoke no BotFather. Em seguida, introduza o novo token nas definições e reinicie o gateway.

Uma nota sobre grupos: autorizar o remetente e autorizar o chat são coisas diferentes. Um membro de um grupo permitido por TELEGRAM_GROUP_ALLOWED_CHATS pode usar o bot mesmo sem ID em TELEGRAM_ALLOWED_USERS. Se o acesso tiver de ser individual, não autorize o grupo inteiro; configure e verifique as restrições de remetentes na versão instalada. Se quiser que o bot só responda num grupo quando for chamado, existe a definição telegram.require_mention — nesse caso, responde a uma menção com @, a uma resposta à sua mensagem, a um comando como /command@yourbot e a correspondências com os seus padrões em telegram.mention_patterns, ignorando as mensagens normais do grupo.

Porque é que o bot não responde num grupo e como resolver?#

Os novos bots do Telegram têm o modo de privacidade ativado por predefinição; a documentação do Hermes descreve-o como a causa mais comum de confusão com bots em grupos. Neste modo, o bot recebe apenas mensagens que começam com um comando /, respostas às suas próprias mensagens e notificações de serviço. Simplesmente não recebe as mensagens normais do grupo — o Telegram não lhas envia e nenhuma definição do agente resolverá isso.

Como resolver:

1. Abra o @BotFather e envie /mybots.
2. Selecione o seu bot.
3. Abra “Bot Settings” → “Group Privacy” → “Turn off”.
4. Remova o bot do grupo e volte a adicioná-lo.

É fácil esquecer o quarto passo e, nesse caso, o bot “continua sem responder”. O Telegram memoriza a definição de privacidade existente quando o bot entrou no grupo e não a atualiza até o bot ser removido do grupo e adicionado novamente.

Se não quiser desativar a privacidade globalmente, há uma segunda opção: torne o bot administrador do grupo. Os bots administradores recebem todas as mensagens, independentemente do modo de privacidade.

Erros de ligação frequentes e o que fazer#

Que outras perguntas fazem sobre o Hermes Agent no Telegram?#

Quando estiver pronto, fique a conhecer a Ailoot.