Todos os artigos

Hermes Agent com chave Carpe Diem e plugins do catálogo

·Por Carpe Diem Team — Lumen Labs·5 min de leitura
tutorielguidetechnicalai
Candeeiro a óleo, caderno fechado e uma chave de latão sobre uma secretária de madeira escura.

Hermes Agent, da Nous Research, é um agente no terminal: chama ferramentas (ficheiros, comandos, web), guarda uma memória e fala com uma API compatível com OpenAI. Pode confiar-lhe um repositório: lê o código, executa os testes, e cada turno é faturado como uma chamada /chat/completions no Carpe Diem. Em 3 de novembro de 2026, com Hermes 0.22.2 e deepseek-v4-1-flash, hermes chat --oneshot respondeu pong em 4 segundos.

Candeeiro a óleo, caderno fechado e uma chave de latão sobre uma secretária de madeira escura.

Ilustração gerada com seedream-v5-lite no Carpe Diem.

Do que precisa

  • Uma conta Carpe Diem com créditos ou um saldo Prepaid, e uma chave cdm_ (Credits & keys).
  • Hermes Agent 0.22.2 (o instalador está no passo 2).

Se só quiser um script Python sem agente, basta o tutorial do SDK OpenAI Python. Aqui lançamos o agente.

Passo 1: criar uma chave cdm_

Abra Credits & keys e o separador API Keys. As chaves começam por cdm_ e só aparecem uma vez: copie-a antes de fechar a página. Escolha Credits ou Prepaid, um nome opcional, depois Create a key. Os dois modos debitam o mesmo catálogo; o detalhe dos pagamentos está no guia, §4.1.

Separador API Keys: nome opcional, Credits ou Prepaid, botão Create a key.

Passo 2: instalar o Hermes

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

O nosso teste foi com Hermes Agent v0.22.2; hermes --version indica a versão que tem instalada. Os fornecedores personalizados estão descritos na secção Custom endpoint da documentação do Hermes.

Passo 3: apontar o Hermes para o Carpe Diem

O Hermes guarda as definições em ~/.hermes/: config.yaml para a configuração, .env para os segredos (configuração do Hermes). Os quatro comandos abaixo escrevem o fornecedor custom, o URL do Carpe Diem, o modelo predefinido e uma referência à variável de ambiente que terá a chave.

hermes config set model.provider custom
hermes config set model.base_url https://carpe-diem.xyz/api/operator/v1
hermes config set model.default deepseek-v4-1-flash
hermes config set model.api_key '${OPENAI_API_KEY}'

A chave em si vai para ~/.hermes/.env, nunca para o yaml:

OPENAI_API_KEY=cdm_your_key_here

custom é o fornecedor genérico do Hermes para uma API compatível com OpenAI. O URL deve terminar em /v1: é o URL de base do Carpe Diem, e o Hermes acrescenta /chat/completions por conta própria. Copie o identificador do modelo em /models.

Uma armadilha: hermes config set model.default escreveu o yaml, mas um chat iniciado sem -m enviou na mesma um nome de modelo vazio. Passe sempre -m de forma explícita. Depois dos config set, o yaml (sem a chave em texto simples) ficou assim:

model:
  default: deepseek-v4-1-flash
  provider: custom
  base_url: https://carpe-diem.xyz/api/operator/v1
  api_key: ${OPENAI_API_KEY}

Passo 4: lançar a primeira chamada

hermes chat --oneshot --max-turns 1 --safe-mode \
  --provider custom -m deepseek-v4-1-flash \
  -q "Reply with the exact word: pong"

--oneshot responde e depois sai, --safe-mode limita as ferramentas que o agente pode usar, e --max-turns 1 corta depois de um único turno. É a forma mais prudente de verificar que a chave e o URL estão corretos. Sem --oneshot, hermes chat abre uma sessão interativa.

Eis a saída obtida:

Query: Reply with the exact word: pong
Initializing agent...
────────────────────────────────────────
pong
────────────────────────────────────────

Resume this session with:
  hermes --resume 20261103_160550_5ad0d5

Session:        20261103_160550_5ad0d5
Duration:       4s
Messages:       2 (1 user, 0 tool calls)

O pedido foi para https://carpe-diem.xyz/api/operator/v1/chat/completions. O resumo mostra 0 tool calls: o agente respondeu sem usar nenhuma ferramenta. O Hermes não mostra o cabeçalho X-Carpe-Cost-Usdc-Micro: o custo consulta-se no painel de consumo ou, para um script, no tutorial do SDK.

Passo 5: acrescentar um plugin

O catálogo instala-se por nome, num commit fixado. Com --no-enable, a instalação clona sem ativar; hermes plugins enable ativa a seguir.

hermes plugins browse
hermes plugins install mcp-serve --no-enable --yes-deps
hermes plugins enable mcp-serve

O plugin passou de not enabled para enabled. O Hermes pediu um hermes gateway restart. Identidade do pacote:

mcp-serve 1.0.0 6389dd08

Se não funcionar

401 Unauthorized / AUTH_REQUIRED. Com OPENAI_API_KEY=cdm_invalid, o Hermes mostrou custom rejected your API key. A chave está incompleta ou mal copiada, ou o .env não foi lido: verifique o ficheiro e volte a executar o comando.

400 INVALID_MODEL. Sem -m, o corpo do pedido continha "model": "" e a API responde Invalid model name. Acrescente -m deepseek-v4-1-flash.

400 MODEL_ERROR. Com deepseek-v4-1-flash-typo, a API respondeu This model is no longer available upstream. Um identificador mal escrito devolve MODEL_ERROR: compare-o com o de /models.

Gateway sem token. hermes gateway mostrou Hermes Gateway Starting e depois Press Ctrl+C to stop. Sem TELEGRAM_BOT_TOKEN nem DISCORD_BOT_TOKEN, nenhuma mensageria fica ligada.

Plugin instalado mas inativo. Se instalou com --no-enable, o plugin fica not enabled até hermes plugins enable <nome> e depois hermes gateway restart.

Ir mais longe

Para falar com o agente a partir do Telegram ou do Discord, a passarela é um processo à parte. Não colámos um token de bot, por isso nenhuma mensagem foi trocada. Para a configurar, siga os guias Telegram e Discord, depois em ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=...
TELEGRAM_ALLOWED_USERS=...

Em seguida, hermes gateway. Sem token, aparece o banner Hermes Gateway Starting e nenhuma mensageria fica ligada.

Depois de obter o pong, retire --safe-mode e --max-turns 1 quando quiser que o agente use as ferramentas, e mude de modelo alterando só -m. Para um chat web em vez de um agente no terminal, veja o tutorial Vercel AI SDK. Para comparar modelos sem instalar nada, basta o Create Hub.

Procedimento: teste de 3 de novembro de 2026 com Hermes 0.22.2. O pong correu em --safe-mode num turno. O plugin mcp-serve foi instalado e depois ativado. A passarela arrancou sem token de bot. O custo não foi lido na interface do Hermes.

Crie a sua chave em Credits & keys, aponte base_url e -m, e lance o pong.