Un seul bot Feishu pour plusieurs Hermes : tutoriel pas à pas sur le routage des Profile dans v0.19

Avant Hermes Agent v0.19, si vous vouliez déployer des personnalités d’agent différentes dans différents groupes Feishu, la méthode la plus simple consistait à créer une application bot Feishu distincte pour chaque groupe, puis à lancer un Gateway Hermes dédié pour chacune. Résultat : plusieurs tokens, plusieurs processus, une configuration éparpillée.

La fonction multiplex_profiles + profile_routes de v0.19 permet de n’utiliser qu’une seule application bot Feishu et un seul processus Gateway pour dispatcher les messages d’après le groupe ou le fil de discussion vers les bons Profile. Chaque Profile conserve son propre modèle, ses propres skills, sa mémoire et ses clés, tout en partageant la même identité de bot.

Cet article s’appuie sur la release officielle Hermes v0.19.0 et sur la documentation existante pour fournir un exemple de configuration complet et directement utilisable.

Pour une vue d’ensemble des nouveautés, consultez notre article de présentation de Hermes v0.19.0 Quicksilver, ainsi que les notes de release officielles v0.19.0.

Prérequis

  • Hermes Agent >= v0.19.0
  • Une application bot Feishu (Lark) créée et approuvée
  • L’événement im.message.receive_v1 et les autres événements de messagerie activés dans l’abonnement aux événements du bot
  • Les valeurs app_id, app_secret, encrypt_key et verification_token récupérées depuis la console open Feishu

Si vous n’avez pas encore connecté de bot Feishu à Hermes, vous pouvez d’abord configurer les identifiants de base dans ~/.hermes/.env :

FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxx

L’adaptateur Feishu d’Hermes est un Gateway complet depuis la v0.6.0 : il prend en charge les messages de cartes, les discussions de groupe, les pièces jointes images/fichiers et les rappels interactifs, donc la connectivité de base ne devrait pas poser de problème.

Concepts clés : multiplex_profiles + profile_routes

Avant v0.19, le Gateway Hermes permettait déjà d’accéder à plusieurs plateformes en parallèle. La nouveauté de v0.19 est la possibilité de router, au sein de la même plateforme et avec le même token de bot, les messages vers différents Profile selon leur origine.

Les deux options de configuration essentielles sont :

  • gateway.multiplex_profiles: true — active le mode de multiplexage des Profile
  • gateway.profile_routes — liste des règles de correspondance par origine

Attention : en mode multiplex, les plateformes liées à un port (webhook, api_server, feishu, etc.) ne peuvent être configurées que dans le Profile default. Les autres Profile reçoivent les messages via les règles de routage. L’article décrit exactement ce cas : le Profile default héberge l’entrée Feishu, puis profile_routes distribue les messages vers les Profile work, personal, etc.

Exemple de configuration pour Feishu

Imaginons trois groupes Feishu :

Nom du groupe Usage Profile souhaité
Groupe d’astreinte technique Gérer les alertes, consulter les logs, exécuter des commandes de sécurité ops
Groupe produit Rédiger des PRD, analyser la concurrence product
Groupe assistant personnel Planning personnel, recherches personal

Dans ~/.hermes/config.yaml, écrivez ceci :

profiles:
  default:
    # L’entrée Feishu doit être placée dans le default profile
    gateway:
      platforms:
        - platform: feishu
          app_id: "cli_xxxxxxxxxxxxxxxx"
          app_secret: "{{env.FEISHU_APP_SECRET}}"
          encrypt_key: "{{env.FEISHU_ENCRYPT_KEY}}"
          verification_token: "{{env.FEISHU_VERIFICATION_TOKEN}}"
          allowed_users:
            - "ou_xxxxxxxx"
            - "ou_yyyyyyyy"

  ops:
    model: "claude-sonnet-5"
    system_prompt: "Tu es l’assistant d’astreinte technique, spécialisé dans l’analyse de logs, l’exploitation de conteneurs et la réponse aux incidents de sécurité."
    skills:
      - kubernetes
      - sentry
    approvals:
      smart_approvals: true
    deny_rules:
      - pattern: "kubectl delete.*prod"
        reason: "Les suppressions en production sont interdites en exécution automatique."

  product:
    model: "gpt-5.6-sol"
    system_prompt: "Tu es l’assistant produit, spécialisé dans la rédaction de PRD, l’analyse concurrentielle et le tri des retours utilisateurs."
    skills:
      - notion
      - web_search

  personal:
    model: "grok-4.5"
    system_prompt: "Tu es un assistant personnel efficace, avec un ton décontracté."

gateway:
  multiplex_profiles: true
  profile_routes:
    - name: feishu-ops
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      profile: ops

    - name: feishu-product
      platform: feishu
      chat_id: "oc_yyyyyyyyyyyyyyyy"
      profile: product

    - name: feishu-personal
      platform: feishu
      chat_id: "oc_zzzzzzzzzzzzzzzz"
      profile: personal

    # Fallback : tous les messages privés d’un utilisateur donné vont vers personal
    - name: feishu-dm
      platform: feishu
      user_id: "ou_xxxxxxxx"
      profile: personal

Après avoir enregistré le fichier :

hermes config validate
hermes gateway restart

Détails des champs de routage Feishu

Dans v0.19, profile_routes prend en charge les champs suivants pour Feishu/Lark, classés par spécificité :

Champ Signification Exemple Poids de spécificité
platform Type de plateforme, obligatoire feishu Base
chat_id Identifiant de groupe ou de session Feishu (commence par oc_) oc_xxxxxxxxxxxxxxxx Élevé
thread_id Identifiant d’un fil de discussion ou d’un post Feishu omt_xxxxxxxxxxxxxxxx Très élevé
user_id Identifiant utilisateur Feishu (commence par ou_) ou_xxxxxxxx Moyen-élevé
tenant_id Identifiant d’entreprise ou de tenant (scénarios multi-tenant) xxx Moyen
profile Nom du Profile cible ops —
name Libellé de la règle de routage feishu-ops —

Règles de correspondance :

  1. Tous les champs déclarés doivent être satisfaits simultanément (relation ET).
  2. Les champs non déclarés sont ignorés et ne participent pas à la correspondance.
  3. La spécificité prime : thread_id > chat_id > user_id > tenant_id > platform seul.
  4. À spécificité égale, la première règle déclarée l’emporte.

Vous pouvez donc router un groupe entier par chat_id, puis affiner le routage d’un fil de discussion précis dans ce groupe grâce à thread_id.

Comment récupérer les chat_id, thread_id et user_id Feishu

Le moyen le plus simple : laissez d’abord Hermes fonctionner avec le Profile default, envoyez un message, puis consultez le session_key ou le payload de l’événement dans les logs. Par défaut, les logs affichent quelque chose comme :

[feishu] incoming message chat_id=oc_xxxxxxxxxxxxxxxx thread_id=omt_yyyyyyyy user_id=ou_zzzzzzzz

Vous pouvez aussi ajouter temporairement un skill echo dans le Profile default pour qu’il réponde :

chat_id: oc_xxxxxxxxxxxxxxxx
thread_id: omt_yyyyyyyy
user_id: ou_zzzzzzzz

Une fois les identifiants récupérés, copiez-les dans profile_routes et redémarrez le Gateway.

Piège courant : ne pas configurer la plateforme feishu dans plusieurs Profile

En mode multiplex, si vous ajoutez dans le Profile ops :

profiles:
  ops:
    gateway:
      platforms:
        - platform: feishu
          ...

Le démarrage échouera avec une erreur. En effet, feishu est une plateforme liée à un port, et son point d’entrée doit appartenir au Profile default. Les Profile secondaires obtiennent leur capacité Feishu uniquement via le routage de profile_routes.

Si vous avez besoin d’une isolation stricte au niveau processus (par exemple, ops ne doit absolument pas partager de processus avec personal), n’utilisez pas le multiplex. Lancez plutôt un Gateway indépendant pour chaque Profile avec hermes -p ops gateway start.

Commandes de débogage et de validation

# Vérifier si le multiplex est activé
hermes config get gateway.multiplex_profiles

# Voir les profile_routes actifs
hermes config get gateway.profile_routes

# Valider la syntaxe de la configuration
hermes config validate

# Démarrer / redémarrer le Gateway
hermes gateway start
hermes gateway restart

# Voir l’état du Gateway et les Profile servis en mode multiplex
hermes status

# Consulter les logs Feishu en temps réel (dans un autre terminal)
hermes gateway --log-level debug

Après avoir envoyé un message de test, vérifiez que les logs contiennent :

[multiplex] routed feishu chat_id=oc_xxx to profile=ops

Si ce n’est pas le cas, la règle ne correspond pas : vérifiez que le chat_id est correct et qu’il ne contient pas d’espaces superflus.

Avancé : isolation par fil de discussion (thread_id)

Les fils de discussion dans un groupe Feishu fonctionnent comme des sous-canaux. Vous pouvez router différents fils d’un même groupe vers des Profile différents :

gateway:
  multiplex_profiles: true
  profile_routes:
    - name: feishu-ops-main
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      profile: ops

    - name: feishu-ops-oncall
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      thread_id: "omt_yyyyyyyyyyyyyyyy"
      profile: ops-oncall

Comme thread_id est plus spécifique, les messages postés dans ce fil iront vers ops-oncall, tandis que les autres messages du même groupe iront vers ops.

Avancé : scénario multi-tenant (tenant_id)

Si vous installez la même application bot dans plusieurs entreprises Feishu (scénario ISV), vous pouvez router les messages par tenant_id :

gateway:
  profile_routes:
    - name: tenant-a
      platform: feishu
      tenant_id: "tenant_a_id"
      profile: customer-a

    - name: tenant-b
      platform: feishu
      tenant_id: "tenant_b_id"
      profile: customer-b

Combiné aux scopes de secrets par Profile d’Hermes, chaque tenant peut disposer d’une configuration de clés et de modèles totalement isolée.

Recommandations de sécurité

  1. Toujours définir allowed_users : par défaut, le bot Feishu ne répond qu’aux utilisateurs figurant sur la liste blanche, ce qui évite les abus si quelqu’un l’ajoute à un groupe inconnu.
  2. Segmenter les permissions entre Profile : le Profile ops peut accéder aux outils d’exploitation, mais le Profile product ne doit pas avoir de droits d’exécution en production.
  3. Utiliser deny_rules comme filet de sécurité : même si un message est mal routé, les règles d’interdiction peuvent bloquer l’exécution automatique de commandes dangereuses. Référez-vous à notre précédent tutoriel Hermes v0.19 : les trois barrières de validation des approbations intelligentes.
  4. Vérifier l’exactitude des chat_id : les identifiants oc_ Feishu se confondent facilement avec les ou_. Une erreur peut faire tomber les messages dans le Profile default ou provoquer un échec de correspondance.

Récapitulatif

Grâce à profile_routes dans Hermes v0.19, un bot Feishu passe du modèle « un bot = un agent » au modèle « un bot = plusieurs agents ». La configuration se résume à trois étapes :

  1. Déclarer l’unique entrée feishu dans le Profile default.
  2. Activer gateway.multiplex_profiles: true.
  3. Utiliser gateway.profile_routes pour dispatcher vers les Profile selon chat_id, thread_id, user_id ou tenant_id.

Ainsi, le même bot Feishu peut servir d’assistant d’astreinte dans le groupe technique, de rédacteur de PRD dans le groupe produit, et d’assistant personnel en message privé — le tout sans avoir à maintenir plusieurs bots ni plusieurs processus Gateway.

# Vérification et démarrage final
hermes config validate
hermes gateway restart
hermes status