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).

Na Haruo, usamos o Hermes Agent em produção para automatizar fluxos que vão desde triagem de leads até geração de relatórios executivos. Neste artigo, vou mostrar na prática como construir AI Agents reais usando Hermes — o mesmo framework open-source que a Nous Research mantém e que nós usamos no dia a dia.

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,
    }),
  ],
});

Na Haruo, usamos esse padrão para um sistema de triagem de leads: um agente recebe o contato inicial, extrai informações, e delega para agentes especializados em qualificação, agenda, ou suporte.

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();

Casos de uso reais que implementamos:

• Relatórios automáticos: Um agente que busca dados do PostgreSQL, gera um resumo executivo com IA, e envia por email todo dia às 8h.
• Monitoramento de concorrentes: Um agente que visita sites, extrai mudanças nos preços, e alerta o time comercial.
• Curadoria de conteúdo: Um agente que varre feeds RSS, seleciona artigos relevantes, e posta no LinkedIn da empresa.

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 automaticamente o histórico por conversa, mantém contexto, e invoca tools quando necessário. Na Haruo, usamos bots assim para:

• Chatbot de RH: Funcionários perguntam sobre saldo de férias, ponto, benefícios.
• Assistente de vendas: O time comercial pergunta sobre estoque, prazos, condições.
• Automação de suporte: Clientes abrem chamados direto pelo Telegram.

Dicas de produção

Depois de rodar Hermes em produção por alguns meses, algumas lições:

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 é uma ferramenta poderosa que coloca AI Agents ao alcance de qualquer equipe de desenvolvimento. Diferente de frameworks super-engineerados, ele foca no que importa: tools que fazem coisas reais, delegacão inteligente entre agentes, e integração prática com canais que seus usuários já usam.

Na Haruo, ele é parte essencial do nosso stack de automação. Já usamos para reduzir em 70% o tempo de resposta de suporte, automatizar relatórios que antes tomavam 2h/dia de analistas, e criar assistentes virtuais que realmente resolvem problemas.

Quer implementar AI Agents no seu negócio? Fale com a gente.

---

Sobre a Haruo: Haruo é uma software house full-stack especializada em produtos web, APIs e automação com IA. haruo.dev

---

Quer implementar AI Agents no seu negócio? Fale com a Haruo →