Como escrever uma tarefa que o Hermes Agent executa até o fim

Fala aí, beleza? Quando um agente empaca no meio da tarefa, na maior parte das vezes o culpado não é o modelo, é o pedido que tu escreveu

O Hermes Agent é um agente open source da Nous Research, com código no repositório NousResearch/hermes-agent sob licença MIT, e a versão mais recente publicada nas releases é a v0.20.0 (tag v2026.8.3), de 03/08/2026

Ele tem mecanismo de sobra pra ir até o fim: objetivo persistente julgado por um modelo juiz, verificação no encerramento, ferramenta pra perguntar quando falta informação

Só que nada disso funciona se o teu texto não disser o que é "pronto"

Então a ideia deste post é uma só: pegar uma intenção solta ("arruma isso aí") e transformar em tarefa executável, com critério de pronto, limites e um plano B pra quando faltar informação…

O que você precisa antes de escrever a tarefa

Nada de PC da Nasa aqui, o setup é curto

Hermes CLI instalado:

Se você quer só o CLI, sem o app desktop, a instalação sai por script e a configuração de modelo e provedor vem logo depois

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup

O hermes setup é o passo que define modelo e provedor, então não pule ele achando que o script já resolveu tudo

Se você ainda está na dúvida entre Hermes Agent e n8n pro teu dia a dia, resolve isso antes, porque o resto do post assume que a escolha já foi feita =)

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O config.yaml em ~/.hermes/

Quase todo ajuste que aparece daqui pra frente (orçamento de iterações, tempo de espera de pergunta, verificação no encerramento) mora no ~/.hermes/config.yaml

Vale abrir esse arquivo antes de escrever a tarefa, porque escrever bem e deixar o limite errado dá no mesmo: trava do mesmo jeito

O AGENTS.md no topo do diretório de trabalho:

Esse é o arquivo de contexto de projeto do Hermes

Instrução que se repete (padrão de código, como rodar teste, o que nunca mexer) não é pra ficar no prompt, é pra morar no AGENTS.md, que o Hermes carrega automaticamente no início da sessão

E se liga nisso, que é o detalhe que salva quem trabalha em monorepo: dentro de um repositório git, o Hermes carrega uma cadeia mesclada de AGENTS.md, indo da raiz do git até o diretório de trabalho

Os arquivos mais profundos entram depois no prompt, ou seja, têm precedência

Já os AGENTS.md de subpastas são descobertos sob demanda durante as chamadas de ferramenta e injetados no resultado, não carregados no system prompt

Na prática: regra geral vai na raiz, regra específica de um pacote vai na pasta do pacote 🙂

Como escrever a tarefa passo a passo

1. Front-load do contexto: joga tudo que importa na primeira mensagem, caminho de arquivo, mensagem de erro, traceback colado e comportamento esperado

A documentação oficial é bem direta nisso: prompt vago gera resultado vago

O exemplo da própria doc compara "fix the code" com um pedido de verdade:

fix the TypeError in api/handlers.py on line 47: the process_request()
function receives None from parse_body()

Quanto mais contexto na primeira mensagem, menos iterações de esclarecimento, e o agente consegue parsear traceback colado direto, não precisa você resumir o erro na mão

O erro comum deste passo: mandar a intenção e segurar o traceback pra "não poluir" a mensagem. É o contrário, colar o traceback é o que economiza rodada

2. Declare o critério de pronto com /goal: o /goal transforma o pedido em objetivo persistente, julgado por um modelo juiz depois de cada turno, que decide entre concluído e continuar

A doc de objetivos avisa: objetivo vago gera julgamento vago, porque o juiz só consegue checar aquilo que foi declarado

Um objetivo durável nomeia cinco coisas: o que é "pronto", como provar, o que não pode quebrar, o que está no escopo e quando parar

E o contrato é preenchido por prefixos de campo reconhecidos no texto do /goal:

verify:
verified by:
constraints:
preserve:
boundaries:
scope:
stop when:
blocked:

O erro comum deste passo: escrever o objetivo em prosa bonita sem nenhum prefixo. Aí não existe contrato, existe desejo

3. Quebre em subgoals: cada subgoal vira um item numerado na lista do objetivo e o prompt do juiz é reescrito

O efeito é que o objetivo só é dado como concluído quando o objetivo original E todos os subgoals forem atendidos

Ou seja, subgoal não é decoração de organização, é critério de aceite entrando no veredito

A lógica de recortar entrega é a mesma de dividir uma tarefa grande em entregas que fecham sozinhas: se você não consegue descrever o que prova aquele pedaço, ele ainda não é um subgoal

4. Ajuste o orçamento antes de mandar rodar: o max_turns limita quantos turnos de continuação um objetivo pode disparar antes do Hermes pausar sozinho, e o padrão é 20

No caminho você vai ver as mensagens do produto:

↻ Continuing toward goal (1/20)
✓ Goal achieved
⏸ Goal paused

Pausou? Você retoma com /goal resume

Tem também o orçamento de iterações por turno, o max_iterations, padrão 500

Quando ele estoura, o CLI é honesto e avisa:

⚠ Iteration budget reached (500/500): response may be incomplete

A doc sugere baixar esse valor (por exemplo, 10) em casos simples de pergunta e resposta

E atenção com delegação: subagente tem orçamento próprio e independente do pai, delegation.max_iterations com padrão 50 por subagente, então o total somado pode passar do teto do agente pai

O erro comum deste passo: ver "resposta pode estar incompleta" e tratar como resposta final

5. Diga o que fazer quando faltar informação: o Hermes tem a ferramenta clarify, que ele usa pra perguntar qual abordagem você prefere ou pra checar antes de uma decisão não trivial

No Telegram a pergunta vira teclado inline, e no gateway em geral vira prompt numerado ou botões nativos da plataforma que suportar

O tempo de espera é configurável no agent.clarify_timeout (padrão 600 segundos)

Se ninguém responder nesse tempo, o agente não trava: ele desbloqueia com uma mensagem sentinela e se adapta

É ótimo e é perigoso ao mesmo tempo, porque "se adaptar" significa ele escolher sozinho

Então a regra prática é: decisão que você não quer que seja tomada sem você vira constraints: ou boundaries: no objetivo, não vira pergunta

Ressalva importante: clarify é ferramenta autônoma e subagente delegado não pode chamar ela, ou seja, subagente não pergunta ao usuário

6. Exija prova, não relatório: com a verificação ligada, o Hermes recusa aceitar uma resposta final em um turno que editou código sem evidência fresca de verificação

Ele injeta um follow-up sintético pedindo que verifique ou explique por que não consegue

Evidência fresca aqui é coisa concreta: teste passando, build, lint

O controle é o verify_on_stop, que aceita três valores:

verify_on_stop: true    # sempre
verify_on_stop: false   # nunca
verify_on_stop: "auto"  # ligada em CLI, TUI e desktop; desligada em Telegram e Discord

O número de cutucadas consecutivas por turno é limitado pelo max_verify_nudges, padrão 3

O erro comum deste passo: achar que a checagem vale pra tudo. Edição só de doc, markdown ou skill nunca dispara a verificação

7. Peça um script, não uma sequência de comandos: a doc recomenda pedir um script único em vez de mandar o agente rodar comando de terminal um a um

O exemplo dela é claríssimo:

Write a Python script to rename all .jpeg files to .jpg and run it

Sai mais barato e mais rápido do que renomear arquivo por arquivo

O erro comum deste passo: pedir "renomeia esses arquivos" e ver o agente queimar iteração à toa em tarefa mecânica

Os padrões que valem a pena conhecer:

O modelo juiz do objetivo, por sinal, roda pelo cliente auxiliar configurado em auxiliary.goal_judge no config.yaml

Por que pedidos vagos travam o agente no meio

Agora o diagnóstico, sintoma por sintoma

Sintoma: o agente devolve uma resposta genérica

Causa: o pedido não tinha arquivo, linha nem erro, então não existe alvo, existe tema

Solução: reescreve com caminho, linha, função e comportamento esperado, no modelo do "fix the TypeError in api/handlers.py on line 47"

Como prevenir na escrita: se a tua frase caberia em qualquer projeto do mundo, ela está vaga demais

Sintoma: o objetivo não é dado como concluído (ou é dado quando você não esperava)

Causa: objetivo vago, e o juiz só consegue checar aquilo que foi declarado

O system prompt dele é deliberadamente conservador, o que torna falso positivo mais raro que falso negativo, então o normal é ele segurar o "pronto", não regalar

Solução: declara verify: ou verified by: com uma prova concreta, e usa stop when: pra dizer quando parar

Como prevenir na escrita: pergunta a si mesmo "o que eu abriria pra saber que acabou?" e escreve exatamente isso

Sintoma: aparece N/20, ou o aviso de resposta incompleta

Causa: bateu o max_turns do objetivo, ou o max_iterations do turno

Solução: /goal resume pra continuar o objetivo pausado, e ajuste de orçamento no config.yaml conforme o tipo de tarefa (baixo pra pergunta simples, folgado pra tarefa longa)

Como prevenir na escrita: tarefa que precisa de 20 turnos pra ser julgada geralmente eram três tarefas, não uma

Sintoma: ele parou pra perguntar, ou pior, decidiu sozinho

Causa: caiu no clarify, e depois do clarify_timeout (padrão 600s) ele desbloqueia com a mensagem sentinela e se adapta

Solução: antecipa a decisão no próprio texto da tarefa, com constraints: e preserve:

Como prevenir na escrita: lembra que subagente delegado não pergunta, então tarefa que vai ser delegada precisa vir 100% decidida

Antes e depois: pedidos reais reescritos

Bora ver na prática, porque teoria de prompt sem exemplo é conversa fiada

Caso 1: bug com traceback

Antes:

fix the code

Depois:

fix the TypeError in api/handlers.py on line 47: the process_request()
function receives None from parse_body()

[traceback colado aqui, inteiro]

O ganho não é estético: com arquivo, linha, função e traceback, some a rodada de esclarecimento que ia acontecer antes de qualquer linha ser tocada

Caso 2: tarefa em lote de arquivos

Antes: mandar o agente rodar comando de terminal arquivo por arquivo

Depois:

Write a Python script to rename all .jpeg files to .jpg and run it

Mais barato e mais rápido, e ainda te sobra um artefato que dá pra rodar de novo amanhã

Caso 3: objetivo durável com /goal

Antes:

/goal deixa a suíte de testes verde

Depois:

/goal deixa a suíte de testes verde
verify: a suíte roda inteira sem falha
constraints: não alterar teste pra passar
preserve: comportamento público da API
scope: apenas o pacote de handlers
stop when: suíte verde e nenhum teste marcado como skip novo

Mesma intenção, mundos diferentes: o segundo dá ao juiz algo pra checar

Quando a instrução deve sair do prompt

Essa é a parte que quase todo mundo pula

Se é FATO (ambiente, preferência, onde ficam os projetos), isso é memória

Se é instrução que se repete a cada sessão do projeto, isso é AGENTS.md, que o Hermes lê automaticamente

E se é PROCEDIMENTO (fluxo de vários passos, receita reutilizável), isso é skill

A doc separa bem: memória guarda o "o quê", skill guarda o "como"

E skill no Hermes não é textão solto, é documento de procedimento em que cada passo ordenado tem critério de conclusão verificável, com uma Verification Checklist no fim

Repara que é exatamente a mesma régua do objetivo: passo checável + prova. Se você já escreve tarefa assim, virar skill é quase copiar e colar 😀

Conclusão

A régua cabe em uma frase: tarefa que o agente fecha até o fim é aquela que diz o que é pronto, como provar, o que não pode quebrar e quando parar

O próximo passo é bem prático: pega o teu próximo pedido, joga o contexto todo na primeira mensagem e transforma ele em /goal com verify:, constraints:, scope: e stop when:

O que se repetir, tira do prompt e coloca no AGENTS.md

E pra acompanhar o andamento sem ficar adivinhando, tem a ferramenta todo (planejamento e acompanhamento de tarefa, sempre carregada) e o quadro Kanban, com uma coluna por status: triage, todo, ready, running, blocked e done (mais archived quando o toggle está ligado)

O dispatcher promove a tarefa de todo pra ready quando todas as dependências estão concluídas, então dependência bem declarada também é escrita de tarefa, e não detalhe de ferramenta

Escreve o contrato, não o desejo… até o próximo post!