Connecter Hermes Agent à iMessage avec Photon

Hermes Agent peut recevoir et envoyer des messages iMessage grâce à Photon, une intégration gérée qui évite d'héberger toi-même un serveur Apple ou un webhook public. La connexion repose sur une passerelle gRPC persistante : Hermes garde un canal ouvert vers Photon, reçoit les messages et renvoie les réponses de l'agent.

Le montage est séduisant, mais il faut distinguer trois couches pour le rendre fiable : le compte Photon, la passerelle Hermes et les règles d'autorisation. Quand un message ne passe pas, chercher au hasard dans « iMessage » fait perdre du temps. Ce guide te donne l'installation propre et un diagnostic couche par couche.

Comment fonctionne Photon avec Hermes Agent

La documentation Photon officielle de Hermes décrit Photon comme une passerelle iMessage gérée. Tu n'as pas besoin d'exposer un port public, de créer un webhook ou de maintenir un Mac serveur pour cette intégration.

Hermes lance une connexion gRPC persistante vers le service. Photon transmet les messages entrants, Hermes exécute l'agent puis la réponse repart par le même canal.

Le flux ressemble à ceci :

1. un contact envoie un iMessage au numéro Photon

2. Photon associe le message à ton projet

3. la passerelle Hermes reçoit l'événement via gRPC

4. Hermes charge la conversation et exécute le modèle configuré

5. la réponse est envoyée au contact par Photon

Cette architecture retire la difficulté du réseau entrant, mais elle ne retire pas les dépendances. Une clé incorrecte, une passerelle arrêtée, une liste d'autorisation trop stricte ou un contact jamais initialisé peut toujours bloquer le flux.

Ligne partagée ou numéro dédié

Photon propose deux approches mentionnées dans la documentation Hermes.

La formule gratuite utilise des lignes partagées. Elle convient à un prototype personnel ou à un test contrôlé. Une limitation importante s'applique : une ligne partagée gratuite ne peut pas démarrer une conversation avec un numéro qui ne l'a jamais contactée. Le destinataire doit donc envoyer le premier message.

La formule Business fournit un numéro dédié. Elle est plus cohérente pour un service utilisé par plusieurs personnes, une identité stable ou un usage où l'agent doit initier certaines conversations.

Ne présente pas une ligne partagée comme un numéro professionnel permanent. Le choix dépend du besoin : valider le système avec peu de coût, ou fournir une expérience stable à des utilisateurs réels.

Prérequis avant l'installation

Avant de connecter Photon, vérifie que Hermes Agent fonctionne déjà localement. Une intégration de messagerie ne doit pas servir à diagnostiquer simultanément le modèle, la mémoire et la passerelle.

Tu dois disposer de :

• Hermes Agent installé depuis sa source officielle

• un modèle déjà configuré et capable de répondre dans le terminal

• un compte Photon et un projet actif

• les identifiants du projet Photon

• un environnement qui peut maintenir un processus Hermes actif

Fais d'abord une conversation locale avec Hermes. Si l'agent ne répond pas dans son interface de base, Photon ne réparera pas le problème.

Pense aussi à la sécurité. Les messages peuvent contenir des informations privées. Vérifie quel modèle traite les conversations, quelles données sont conservées et qui a accès au numéro.

Installer Photon avec la commande guidée

Hermes fournit un assistant de configuration via la passerelle. D'après la documentation actuelle, tu peux lancer :

hermes gateway setup

L'assistant présente les plateformes disponibles, récupère les paramètres nécessaires et prépare le canal Photon.

Une commande dédiée est aussi documentée :

hermes photon setup --phone TON_NUMERO

Remplace la valeur par le numéro attendu au format demandé par Photon. Utilise la commande et les options exactes affichées dans la version de Hermes installée : un tutoriel ancien peut viser une structure de plugin qui a depuis changé.

L'installation enregistre notamment PHOTON_PROJECT_ID et PHOTON_PROJECT_SECRET dans le fichier d'environnement Hermes, généralement ~/.hermes/.env. Des métadonnées d'authentification peuvent également être écrites dans un fichier comme auth.json.

Ne copie jamais ces valeurs dans un dépôt ou un ticket de support public. Pour vérifier la configuration, confirme que les variables existent sans afficher leur contenu.

Démarrer la passerelle Hermes

Une fois le canal configuré, la passerelle doit tourner. Selon ta version, la commande et le mode de service peuvent varier. Utilise l'aide locale de hermes gateway et la documentation correspondante.

Le point important est observable : un processus actif doit établir la connexion gRPC vers Photon. Un fichier .env correct ne suffit pas si aucun service ne le lit.

Après le démarrage, cherche dans les journaux :

• le chargement du canal Photon

• l'authentification du projet

• l'établissement de la connexion gRPC

• l'absence de boucle de reconnexion immédiate

• la réception d'un premier événement

Garde les journaux ouverts pendant le premier test. Ils permettent de savoir si le message arrive jusqu'à Hermes ou s'il reste bloqué avant.

Faire le premier test iMessage

Avec une ligne partagée, envoie le premier message depuis ton téléphone vers le numéro Photon. Utilise une phrase reconnaissable, par exemple « test photon 14h32 », afin de la retrouver facilement dans les logs.

Le test complet doit prouver quatre étapes :

1. le message est livré côté iMessage

2. Photon le transmet au projet

3. Hermes crée ou retrouve la bonne session

4. la réponse revient sur le même fil

Une simple réponse ne valide pas tout le système. Envoie ensuite un second message qui dépend du premier, par exemple « quel mot ai-je envoyé juste avant ? ». Cela vérifie que le routage conserve la conversation attendue.

Teste enfin une pièce jointe seulement après le texte. La prise en charge des médias ajoute une couche de téléchargement, de type MIME et de taille. Commencer par une image quand le texte ne fonctionne pas brouille le diagnostic.

Contrôler qui peut parler à l'agent

Un numéro de messagerie est une entrée vers ton agent. S'il peut appeler des outils, lire des fichiers ou déclencher des actions, l'accès doit être explicite.

Utilise une liste d'autorisation pour les premiers tests. Seuls tes numéros et ceux des testeurs prévus doivent pouvoir obtenir une réponse. Ne donne pas immédiatement à l'agent des outils sensibles depuis une surface publique.

Sépare les capacités :

• répondre à une question générale

• lire une mémoire personnelle

• écrire dans un fichier

• envoyer un message à un tiers

• déclencher une action externe

La réception d'un iMessage ne doit jamais être considérée comme une autorisation universelle. Le texte du message peut contenir une instruction malveillante ou provenir d'un contact compromis.

Si plusieurs personnes utilisent le numéro, vérifie que les sessions sont isolées par contact. Deux utilisateurs ne doivent pas partager accidentellement le même historique ou la même mémoire privée.

Erreur 1 : Hermes ne se connecte pas à Photon

Si les logs indiquent un échec de connexion ou une reconnexion permanente, commence par la couche réseau et la version du plugin.

Contrôles utiles :

• la machine a accès à Internet

• la date et l'heure système sont correctes

• les identifiants Photon appartiennent au bon projet

• le secret ne contient pas d'espace ajouté lors du copier-coller

• Hermes et ses dépendances sont à jour selon la branche recommandée

Le plugin Photon s'appuie sur des dépendances gRPC. Des issues historiques du dépôt Hermes ont documenté des incompatibilités de version ou des hôtes devenus invalides. La leçon n'est pas d'appliquer un ancien correctif au hasard : utilise la version actuellement épinglée par le projet, puis réinstalle les dépendances avec la méthode officielle.

Consulte le README actuel du plugin Photon et les issues récentes avant de modifier un paquet manuellement. Un contournement valable en juin peut être faux en août.

Erreur 2 : authentification refusée

Une erreur d'authentification vient généralement d'un mauvais couple identifiant-secret, d'un fichier d'environnement non chargé ou d'un projet désactivé.

Vérifie le chemin du fichier utilisé par le processus réel. Une commande lancée à la main et un service système peuvent avoir des environnements différents. Tu peux avoir correctement rempli ~/.hermes/.env alors que le service tourne sous un autre utilisateur ou avec un autre répertoire de travail.

Confirme aussi que les noms de variables sont exactement ceux attendus : PHOTON_PROJECT_ID et PHOTON_PROJECT_SECRET. Ne journalise pas leur valeur complète. Affiche au besoin leur présence et leur longueur, pas leur contenu.

Si tu régénères un secret dans Photon, redémarre proprement la passerelle pour qu'elle recharge la nouvelle valeur.

Erreur 3 : le message arrive, mais l'agent ne répond pas

Quand l'événement apparaît dans les logs mais qu'aucune réponse ne repart, Photon a fait sa partie. Le problème se situe dans Hermes, le modèle ou l'autorisation.

Cherche :

• une erreur de fournisseur de modèle

• un quota ou une clé API expirée

• une liste d'autorisation qui rejette le contact

• une exception lors du chargement de la session

• un outil qui bloque la boucle avant la réponse finale

Teste le même prompt directement dans Hermes. S'il échoue aussi localement, corrige le modèle ou la configuration centrale. S'il fonctionne localement, compare la session, l'identité du contact et les règles spécifiques au canal Photon.

Évite de redémarrer tous les services sans lire les logs. Tu risques d'effacer l'état précis qui explique la panne.

Erreur 4 : la réponse part vers le mauvais fil

Le routage doit relier un identifiant Photon, un numéro et une session Hermes. Une mauvaise normalisation du numéro ou un ancien état local peut créer une conversation séparée.

Compare l'identifiant exact reçu dans les événements. Les formats internationaux, espaces et préfixes peuvent différer de la valeur affichée dans Contacts.

Ne fusionne pas manuellement plusieurs sessions sans savoir laquelle contient l'historique correct. Fais un test neuf avec un numéro autorisé et un message unique, puis observe la clé de session créée.

Si le problème apparaît après une mise à jour, consulte les issues et commits du dépôt. Le plugin Photon a déjà reçu des corrections sur la pagination ou les curseurs de messages. Utiliser la version courante est plus sûr que recopier un patch historique.

Pièces jointes et messages riches

Les versions récentes du plugin documentent la prise en charge de pièces jointes. Vérifie tout de même chaque type : image, document, message contenant plusieurs médias et fichier trop lourd.

Ton agent doit traiter une pièce jointe comme une donnée non fiable. Il ne doit pas exécuter un fichier reçu ni suivre automatiquement une instruction contenue dans un document.

Pour chaque média, conserve au minimum :

• l'expéditeur

• le type de fichier détecté

• la taille

• la date de réception

• l'action réellement effectuée

Si le modèle ne sait pas analyser le type reçu, il doit l'annoncer plutôt qu'inventer son contenu.

Faire tourner la passerelle sans interruption

Pour un test de quelques minutes, une commande interactive suffit. Pour un usage quotidien, la passerelle doit être supervisée par un gestionnaire de service adapté à ton système.

Le service doit :

• démarrer après le réseau

• redémarrer en cas de crash limité

• garder des logs consultables

• charger le bon environnement

• éviter plusieurs instances concurrentes

Une boucle de redémarrage infinie peut masquer une authentification cassée et saturer les journaux. Ajoute un délai et un nombre de tentatives raisonnables.

Surveille trois signaux simples : processus actif, connexion Photon établie et dernier message traité. Un processus vivant mais déconnecté n'est pas un service sain.

La checklist de mise en service

Avant de considérer l'intégration comme prête, vérifie :

• Hermes répond correctement hors iMessage

• le projet Photon est actif

• les secrets sont stockés hors des dépôts

• la passerelle établit une connexion gRPC stable

• le premier message part du contact si la ligne partagée l'exige

• la réponse revient dans le bon fil

• un second message conserve le bon contexte

• les contacts non autorisés sont rejetés

• les sessions de plusieurs utilisateurs restent séparées

• les pièces jointes sont testées sans exécution automatique

• les logs permettent de diagnostiquer chaque couche

Photon retire une grosse partie de l'infrastructure nécessaire pour relier Hermes Agent à iMessage. Il ne retire pas le besoin de permissions, de supervision et de preuves. Monte d'abord un canal personnel limité, valide le routage, puis ouvre progressivement l'accès et les outils.

Pour comprendre le reste de l'installation, de la mémoire et des tâches planifiées, lis aussi notre guide complet de Hermes Agent.

Pour recevoir les prochains tutoriels sur les agents personnels et leurs intégrations, rejoins la newsletter Kryve.