Integrar Hermes Agent com APIs externas

Uma inteligência artificial isolada do resto do mundo digital tem o seu valor limitado. Imagina dar ao teu assistente a capacidade de consultar o tempo em tempo real, verificar a cotação de moedas, atualizar o teu CRM ou disparar notificações para um canal do Slack. Tudo isto é possível quando integramos o Hermes Agent com APIs REST externas.

O que é uma API REST e por que deves integrá-la com o Hermes Agent?

Uma API REST (Representational State Transfer) é a ponte que permite a diferentes aplicações comunicarem entre si. Através de pedidos HTTP (como GET, POST, PUT e DELETE), um sistema pode solicitar dados ou executar ações noutro serviço web, recebendo quase sempre uma resposta em formato JSON.

Ao capacitar o Hermes Agent para interagir com APIs REST, transformas um modelo de linguagem estático num agente autónomo dinâmico. O Hermes passa a conseguir:

Aceder a dados em tempo real: Notícias, dados financeiros, métricas de servidores ou estado de encomendas.
Executar ações no mundo real: Criar tarefas no Trello/Notion, enviar e-mails ou publicar mensagens em redes sociais.
Conectar ferramentas internas: Interagir com bases de dados privadas e microserviços da tua empresa.

Como funcionam as Skills de API no Hermes Agent

No ecossistema do Hermes Agent, a lógica de integração é estruturada através de Skills. Uma Skill é um ficheiro Markdown (SKILL.md) com metadados em YAML que ensina o agente quando e como executar determinada tarefa, incluindo chamadas a serviços externos e o devido processamento da resposta JSON.

Vamos construir uma Skill prática do início ao fim para perceberes exatamente como tudo funciona na prática.

Passo a Passo: Criar uma Skill para Consumir uma API REST

Neste exemplo, vamos criar uma Skill chamada previsao-tempo que consulta a API pública e gratuita da Open-Meteo para obter a temperatura e condições meteorológicas de qualquer cidade.

Passo 1: Escrever a definição da Skill (SKILL.md)

Cria um ficheiro chamado SKILL.md e adiciona a estrutura oficial do Hermes Agent, definindo os metadados, o momento de uso e os passos detalhados de execução:

---
name: previsao-tempo
description: Obtém a previsão do tempo atual para qualquer localização utilizando a API REST da Open-Meteo.
author: MarcTechJA
version: "1.0"
platforms:
  - macos
  - linux
  - windows
metadata:
  hermes:
    tags: [api, utilitarios, meteorologia]
---

# Previsão do Tempo

Obtém dados meteorológicos em tempo real consultando a API pública Open-Meteo e formatando a resposta para o utilizador.

## When to Use
Utiliza esta skill sempre que o utilizador perguntar sobre o tempo, temperatura, vento ou condições atmosféricas para uma cidade ou região específica.

## Instruções
1. Identifica a cidade solicitada pelo utilizador e obtém as suas coordenadas (latitude e longitude).
2. Executa um pedido GET à API REST da Open-Meteo:
   `https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current_weather=true`
3. Analisa e processa a resposta em formato JSON retornada pelo serviço.
4. Extrai a temperatura atual (`temperature`) e a velocidade do vento (`windspeed`).
5. Responde ao utilizador em português de forma clara, amigável e resumida.

## Critérios de conclusão
- O pedido à API REST foi efetuado com sucesso.
- O formato JSON foi interpretado corretamente.
- A resposta final foi apresentada ao utilizador com os dados atualizados.

O que o código faz: O cabeçalho em YAML regista a Skill no Hermes Agent com o nome previsao-tempo. As secções subsequentes explicam ao agente a intenção da tarefa, o ponto de terminação HTTP que deve consultar e a forma correta de extrair as propriedades do JSON retornado.

Passo 2: Guardar o ficheiro no diretório de Skills

Para que o Hermes Agent reconheça a nova integração, guarda o ficheiro no diretório pessoal de skills do teu sistema operativo. No macOS e Linux, a pasta padrão situa-se em ~/.hermes/skills/previsao-tempo/SKILL.md.

Podes verificar se a Skill foi detetada corretamente executando o seguinte comando no teu terminal:

hermes skills list

O que o comando faz: Lista todas as automações e skills disponíveis no teu ambiente local, confirmando se o Hermes Agent carregou a tua nova Skill sem erros de sintaxe.

Passo 3: Executar o Hermes Agent com a nova Skill

Agora podes iniciar uma conversa com o Hermes Agent instruindo-o a utilizar a Skill que acabaste de configurar:

hermes chat -s previsao-tempo

O que o comando faz: Abre a interface interativa do Hermes carregando o contexto da Skill previsao-tempo. Ao perguntares "Qual é o tempo hoje em Lisboa?", o agente fará o pedido à API, processará o JSON recebido e entregará a resposta pronta no teu ecrã.

Tratamento de Autenticação (API Keys) e Segurança

A maioria das APIs REST empresariais (como OpenAI, Stripe, GitHub ou CRMs) exige autenticação via token ou API Key. Para manteres o teu ambiente seguro, nunca deves colocar chaves privadas diretamente no texto da Skill.

Segue estas recomendações essenciais:

Variáveis de Ambiente: Guarda as tuas chaves em variáveis de sistema (ex: export MINHA_API_KEY="seu_token_aqui").
Referência nas Instruções: Na tua Skill, indica ao Hermes para ler a chave a partir do ambiente do sistema antes de realizar o pedido HTTP com os cabeçalhos Authorization: Bearer $MINHA_API_KEY.
Tratamento de Erros: Inclui sempre instruções na Skill para lidar com códigos de erro HTTP comuns, como 401 Unauthorized (chave inválida) ou 404 Not Found (recurso não encontrado).

Conclusão

Integrar o Hermes Agent com APIs REST abre um universo infinito de possibilidades para automatizar tarefas diárias, integrar sistemas complexos e construir fluxos de trabalho inteligentes sem necessidade de programar código pesado do zero. Com apenas um ficheiro de Skill bem estruturado, a tua IA passa a interagir diretamente com o ecossistema web.

Quer seja para ler relatórios, enviar notificações ou sincronizar bases de dados, dominar a criação de Skills é o passo fundamental para tirares o máximo proveito desta ferramenta extraordinária.

Queres dominar o Hermes Agent e criar automações avançadas?

Se queres aprender a construir equipas de agentes, automatizar tarefas empresariais, conectar bases de dados e fazer o deploy do Hermes Agent em servidores de produção, descobre o Guia Completo do Hermes Agent de MarcTechJA.

Um e-book prático com 42 capítulos detalhados que te vai guiar do nível iniciante ao avançado na criação de soluções de Inteligência Artificial autónomas.

👉 Garante aqui o teu exemplar do Guia Completo do Hermes Agent