Como construir AI Agents com Hermes — um guia prático

Tempo estimado de leitura: 8 minutos

---

Se você acompanha o mundo de tecnologia, já deve ter visto o hype em torno de “AI Agents” — sistemas autônomos que usam modelos de linguagem (LLMs) para tomar decisões e executar tarefas. O problema? A maioria dos tutoriais por aí ou é superficial demais (“olha, chamei a API da OpenAI!”) ou complexa demais (vamos montar um framework do zero).

Uso o Hermes Agent no meu próprio assistente pessoal: o que roda na minha máquina, com gateway de Telegram, quadro de tarefas e alguns cron jobs. Não é produto de ninguém e não atende cliente: é o meu dia a dia, que é justamente onde dá para experimentar sem quebrar a operação de outra pessoa. Neste artigo mostro como construir AI Agents com Hermes, o framework open-source que a Nous Research mantém.

O que é o Hermes Agent?

Hermes Agent é um framework Node.js/TypeScript minimalista para construir agentes autônomos. Diferente de soluções como LangChain ou CrewAI, o Hermes foca em simplicidade: você define ferramentas (tools) que o seu agente pode usar, dá um objetivo pra ele, e ele decide como executar.

O diferencial? Ele foi desenhado para ambientes de produção — não apenas protótipos. Suporte nativo a Telegram, cron jobs, delegacão de tarefas entre agentes e um sistema de logs que facilita debug quando algo dá errado.

Instalação e configuração básica

Vamos começar instalando o Hermes Agent em um projeto Node.js:

mkdir meu-agente
cd meu-agente
npm init -y
npm install hermes-agent @langchain/core dotenv

O Hermes usa LangChain por baixo dos panos para abstrair diferentes provedores de LLM. Você pode usar OpenAI, Anthropic, Ollama (local), ou até mesmo DeepSeek (que usamos bastante por ser mais barato).

Crie um arquivo .env com:

OPENAI_API_KEY=sua-chave-aqui

Ou, se preferir DeepSeek (recomendado para produção com baixo custo):

OPENAI_API_KEY=sua-chave-deepseek
OPENAI_API_BASE=https://api.deepseek.com/v1

Agora, o agente mais simples possível:

import { Hermes, HumanMessage, Tool } from 'hermes-agent';

const agent = new Hermes({
  model: 'gpt-4o',
  tools: [],
});

const resposta = await agent.call([
  new HumanMessage('Qual é a capital do Brasil?'),
]);

console.log(resposta.content);

Simples, né? Mas um agente sem ferramentas é só um chatbot caro. A mágica está nas tools.

Criando tools (ferramentas)

Tools são funções que o agente pode invocar automaticamente. Vamos criar uma tool que consulta o clima:

import { z } from 'zod';

const climaTool: Tool = {
  name: 'consultar_clima',
  description: 'Consulta a temperatura atual de uma cidade',
  parameters: z.object({
    cidade: z.string().describe('Nome da cidade'),
  }),
  handler: async ({ cidade }) => {
    // Aqui você chamaria uma API real de clima
    const temperaturas: Record<string, number> = {
      'são paulo': 28,
      'rio de janeiro': 32,
      'curitiba': 18,
    };
    return `A temperatura em ${cidade} é ${temperaturas[cidade.toLowerCase()] ?? 25}°C`;
  },
};

const agenteClima = new Hermes({
  model: 'gpt-4o',
  tools: [climaTool],
});

const resposta = await agenteClima.call([
  new HumanMessage('Como está o clima no Rio de Janeiro hoje?'),
]);

O agente decide sozinho quando chamar a tool. Se a pergunta não envolver clima, ele responde diretamente sem gastar tokens desnecessários. Se envolver, ele invoca a função, recebe o resultado, e monta uma resposta amigável.

Delegate task: um agente coordenando outros

Um dos recursos mais poderosos do Hermes é a capacidade de um agente delegar tarefas para outros agentes especializados. Isso permite criar sistemas modulares onde cada agente faz uma coisa e faz bem.

Imagine um sistema de suporte onde um agente orquestrador recebe a demanda e delega para o agente correto:

import { delegateTask } from 'hermes-agent';

const agenteFaturamento = new Hermes({
  model: 'gpt-4o',
  tools: [consultarFatura, emitirBoleto],
  systemPrompt: 'Você é um especialista em faturamento. Responda apenas sobre contas, boletos e pagamentos.',
});

const agenteSuporte = new Hermes({
  model: 'gpt-4o',
  tools: [consultarStatus],
  systemPrompt: 'Você é um especialista em suporte técnico. Ajude com problemas de funcionamento do sistema.',
});

const orquestrador = new Hermes({
  model: 'gpt-4o',
  systemPrompt: `Você é um atendente que direciona demandas.
  Use delegateTask para passar a conversa para o especialista correto.
  - Se for sobre faturamento, delegue para "faturamento"
  - Se for sobre suporte técnico, delegue para "suporte"`,
  tools: [
    delegateTask({
      name: 'faturamento',
      description: 'Delega para o setor de faturamento',
      agent: agenteFaturamento,
    }),
    delegateTask({
      name: 'suporte',
      description: 'Delega para o setor de suporte técnico',
      agent: agenteSuporte,
    }),
  ],
});

O padrão vale sempre que a primeira pergunta é “isso é de que assunto?”: um agente recebe a mensagem, extrai o que interessa, e delega para o agente que sabe daquele assunto. O ganho não é de inteligência, é de contexto: cada agente carrega só as ferramentas e as instruções do seu assunto, e um contexto menor erra menos.

Cron jobs: agentes que rodam sozinhos

Nem todo agente precisa ser acionado por um usuário. Com cron jobs, você cria agentes que executam tarefas periódicas automaticamente.

import { CronAgent } from 'hermes-agent';

const relatorioDiario = new CronAgent({
  name: 'relatorio-vendas',
  schedule: '0 8 * * 1-5', // Seg-Sex às 8h
  task: async () => {
    const dados = await buscarVendasDoDiaAnterior();
    const resumo = await agenteAnalista.call([
      new HumanMessage(
        `Resuma estas vendas em um parágrafo executivo: ${JSON.stringify(dados)}`
      ),
    ]);
    await enviarEmail('[email protected]', resumo.content);
  },
});

relatorioDiario.start();

O que o cron muda no desenho é uma coisa só, e ela é importante: não há ninguém esperando a resposta. Isso libera o agente para tarefas lentas (varrer, comparar, resumir) e obriga duas coisas que o agente sob demanda perdoa: um teto de tokens por execução, porque não há humano para interromper um agente perdido; e um destino para o erro, porque uma falha às 8h da manhã sem ninguém olhando é uma falha que você descobre em outubro.

Integração com Telegram

O Hermes tem integração nativa com Telegram. Em poucas linhas você tem um bot com IA:

import { TelegramHermes } from 'hermes-agent';

const bot = new TelegramHermes({
  model: 'gpt-4o',
  token: process.env.TELEGRAM_BOT_TOKEN!,
  tools: [consultarClima, consultarAgenda],
});

bot.start();

O bot gerencia sozinho o histórico por conversa, mantém contexto, e invoca tools quando precisa. É por esse canal que eu falo com o meu assistente pessoal. E o aprendizado que vale repassar é que a qualidade do bot depende menos do modelo do que do conjunto de tools que você registrou: um bot com três ferramentas certas resolve mais do que um com quinze, porque cada descrição a mais é uma chance a mais de o modelo escolher errado.

Dicas de quem deixou isso rodando

Depois de alguns meses com o Hermes ligado no meu próprio dia a dia, quatro lições que eu gostaria de ter lido antes:

1. Use streaming sempre: A experiência do usuário melhora drasticamente quando a resposta aparece em tempo real. O Hermes suporta streaming nativo.
2. Monitore os tokens: Defina maxTokens por chamada. Um agente perdido pode consumir centenas de milhares de tokens em segundos.
3. Tenha um fallback: Para tarefas críticas, configure um timeout. Se o LLM não responder em X segundos, dispare um alerta.
4. Logs estruturados: O Hermes emite logs no formato JSON. Use isso para debugar decisões erradas do agente — o log mostra exatamente qual tool foi chamada, com quais parâmetros, e o que retornou.

Conclusão

O Hermes Agent coloca AI Agents ao alcance de quem escreve Node. Diferente dos frameworks super-engenheirados, ele foca no que importa: tools que fazem coisa de verdade, delegação entre agentes e integração com canais que já existem.

Não tenho número de economia para te oferecer, e desconfie de quem tiver sem dizer de onde saiu. O que eu tenho é o que dá para verificar no texto acima: o desenho, as tools, o padrão de delegação, o cron e as quatro lições de operação. Se você for medir ganho, meça o seu, com o “antes” anotado antes de ligar o agente, que é a única parte que ninguém consegue reconstruir depois.

---

Douglas Haruo, engenheiro de software há 15 anos, cinco deles em risco e fraude numa fintech de pagamentos. haruo.dev