Tous les articles

Hermes Agent : clé Carpe Diem et plugins du catalogue

·Par Carpe Diem Team — Lumen Labs·5 min de lecture
tutorielguidetechnicalai
Lampe à huile, carnet fermé et clé en laiton sur un bureau de bois sombre.

Hermes Agent, de Nous Research, est un agent dans le terminal : il appelle des outils (fichiers, commandes, web), garde une mémoire, et parle à une API compatible OpenAI. On peut par exemple lui confier un dépôt : il lit le code, lance les tests, et chaque tour est facturé comme un appel /chat/completions sur Carpe Diem. Le 3 novembre 2026, avec Hermes 0.22.2 et deepseek-v4-1-flash, hermes chat --oneshot a répondu pong en 4 secondes.

Lampe à huile, carnet fermé et clé en laiton sur un bureau de bois sombre.

Illustration générée avec seedream-v5-lite sur Carpe Diem.

Ce qu'il vous faut

  • Un compte Carpe Diem avec des crédits ou un solde prepaid, et une clé cdm_ (Credits & keys).
  • Hermes Agent 0.22.2 (l'installateur est à l'étape 2).

Si vous voulez seulement un script Python sans agent, le tutoriel SDK OpenAI Python suffit. Ici, on lance l'agent.

Étape 1 : créer une clé cdm_

Ouvrez Credits & keys et l'onglet API Keys. Les clés commencent par cdm_ et ne s'affichent qu'une seule fois : copiez-la avant de fermer la page. Choisissez Credits ou Prepaid, un nom optionnel, puis Create a key. Les deux modes débitent le même catalogue ; le détail des paiements est dans le guide, §4.1.

Onglet API Keys : nom optionnel, choix Credits ou Prepaid, bouton Create a key.

Étape 2 : installer Hermes

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

Notre essai s'est fait avec Hermes Agent v0.22.2 ; hermes --version vous dit où vous en êtes. Les fournisseurs personnalisés sont décrits dans la section Custom endpoint de la documentation Hermes.

Étape 3 : pointer Hermes sur Carpe Diem

Hermes range ses réglages dans ~/.hermes/ : config.yaml pour la configuration, .env pour les secrets (configuration Hermes). Les quatre commandes ci-dessous écrivent le fournisseur custom, l'URL Carpe Diem, le modèle par défaut, et une référence à la variable d'environnement qui portera la clé.

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}'

La clé elle-même va dans ~/.hermes/.env, jamais dans le yaml :

OPENAI_API_KEY=cdm_your_key_here

custom est le fournisseur générique de Hermes pour une API compatible OpenAI. L'URL doit se terminer par /v1 : c'est la base URL de Carpe Diem, et Hermes y ajoute lui-même /chat/completions. Copiez l'identifiant du modèle depuis /models.

Un piège à connaître : hermes config set model.default a bien écrit le yaml, mais un chat lancé sans -m a quand même envoyé un nom de modèle vide. Passez donc toujours -m explicitement. Après les config set, le yaml (sans la clé en clair) ressemblait à ceci :

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

Étape 4 : lancer le premier appel

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

--oneshot répond puis quitte, --safe-mode limite les outils que l'agent peut utiliser, et --max-turns 1 coupe après un seul tour. C'est la forme la plus prudente pour vérifier que la clé et l'URL sont bonnes. Sans --oneshot, hermes chat ouvre une session interactive.

Voici la sortie obtenue :

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)

La requête est partie vers https://carpe-diem.xyz/api/operator/v1/chat/completions. Le résumé affiche 0 tool calls : l'agent a répondu sans utiliser d'outil. Hermes n'affiche pas l'en-tête X-Carpe-Cost-Usdc-Micro : le coût se lit dans le tableau de consommation ou, pour un script, dans le tuto SDK.

Étape 5 : ajouter un plugin

Le catalogue s'installe par nom, sur un commit épinglé. Avec --no-enable, l'install clone sans activer ; hermes plugins enable l'active ensuite.

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

Le plugin est passé de not enabled à enabled. Hermes a demandé un hermes gateway restart. Identité du paquet :

mcp-serve 1.0.0 6389dd08

Si ça ne marche pas

401 Unauthorized / AUTH_REQUIRED. Avec OPENAI_API_KEY=cdm_invalid, Hermes a affiché custom rejected your API key. La clé est incomplète ou mal copiée, ou bien .env n'a pas été lu : vérifiez le fichier et relancez la commande.

400 INVALID_MODEL. Sans -m, le corps de la requête contenait "model": "" et l'API répond Invalid model name. Ajoutez -m deepseek-v4-1-flash.

400 MODEL_ERROR. Avec deepseek-v4-1-flash-typo, l'API a répondu This model is no longer available upstream. Un identifiant mal orthographié renvoie MODEL_ERROR : comparez-le avec celui de /models.

Gateway sans jeton. hermes gateway a affiché Hermes Gateway Starting puis Press Ctrl+C to stop. Sans TELEGRAM_BOT_TOKEN ni DISCORD_BOT_TOKEN, aucune messagerie n'est connectée.

Plugin installé mais inactif. Si vous avez installé avec --no-enable, le plugin reste not enabled jusqu'à hermes plugins enable <nom> puis hermes gateway restart.

Aller plus loin

Pour parler à l'agent depuis Telegram ou Discord, la passerelle est un processus à part. Nous n'avons pas collé de jeton de bot, donc aucun message n'a été échangé. Pour la configurer, suivez les guides Telegram et Discord, puis dans ~/.hermes/.env :

TELEGRAM_BOT_TOKEN=...
TELEGRAM_ALLOWED_USERS=...

Puis hermes gateway. Sans jeton, le bandeau Hermes Gateway Starting apparaît et aucune messagerie n'est connectée.

Une fois le pong obtenu, retirez --safe-mode et --max-turns 1 quand vous voulez que l'agent utilise ses outils, et changez de modèle en modifiant seulement -m. Pour un chat web plutôt qu'un agent dans le terminal, voyez le tuto Vercel AI SDK. Pour comparer des modèles sans rien installer, le Create Hub suffit.

Méthode : essai du 3 novembre 2026 avec Hermes 0.22.2. Le pong a tourné en --safe-mode sur un tour. Le plugin mcp-serve a été installé puis activé. La passerelle a démarré sans jeton de bot. Le coût n'a pas été relevé dans l'interface de Hermes.

Créez votre clé sur Credits & keys, pointez base_url et -m, puis lancez le pong.