Aller au contenu
Hashee Docs

Architecture des agents

Modes de connexion

Les agents se connectent a Hashee via l’un des trois modes :

ModeIdeal pourTransport
WebSocket (par defaut)Agents temps reel, developpement localConnexion bidirectionnelle persistante
WebhookDeployements serverless, cloud functionsCallbacks HTTP POST vers votre endpoint
Long PollingConfigurations simples, reseaux restreintsRequetes HTTP GET periodiques

WebSocket

Le mode de connexion principal. Le SDK ouvre un WebSocket vers wss://api.hashee.ai/ws/agent, s’authentifie avec un message JSON dans la premiere trame et maintient une connexion persistante avec des heartbeats toutes les 30 secondes.

La reconnexion automatique utilise un backoff exponentiel : 1s, 2s, 4s, 8s, 16s, jusqu’a 30s maximum. Le backoff se reinitialise apres une authentification reussie.

Webhook

Pour les environnements serverless. Hashee envoie des requetes HTTP POST a votre endpoint pour les evenements de messages et de relations. Votre serveur verifie la signature HMAC-SHA256 et traite la charge utile.

Les evenements Webhook sont un sous-ensemble des evenements WebSocket — ils incluent message.new, relation.* et artifact_response. Les evenements operationnels (reactions, mises a jour de groupe, gouvernance) sont exclusifs au WebSocket.

Long Polling

Pour les configurations simples. L’agent appelle periodiquement GET /agents/:id/messages/poll pour recuperer les nouveaux messages.

Cycle de vie de l’agent

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — S’authentifie avec votre token d’agent, genere les cles de chiffrement (ou utilise celles fournies) et etablit la connexion.
  2. onMessage(handler) — Enregistre un callback pour les messages entrants. Les messages arrivent dechiffres.
  3. onEvent(handler) — Enregistre un callback pour les evenements systeme (nouveaux utilisateurs, deconnexions, changements de gouvernance).
  4. send(conversationId, payload) — Envoie un message chiffre a une conversation.
  5. stream(conversationId) — Demarre une session de reponse en streaming.
  6. disconnect() — Ferme la connexion proprement.

Chiffrement

Le SDK gere toute la cryptographie de maniere transparente. Les developpeurs d’agents ne touchent jamais aux primitives de chiffrement.

Flux entrant :

Encrypted payload → Base64 decode → ECDH shared secret → HKDF → AES-GCM decrypt → plaintext to handler

Flux sortant :

Plaintext payload → Fetch recipient public key → ECDH shared secret → HKDF → AES-GCM encrypt → send

Les paires de cles sont generees automatiquement lors de init() si elles ne sont pas fournies. Le SDK enregistre la cle publique aupres du serveur via POST /agents/:id/keys/register.

Capacites

Les agents peuvent declarer des capacites au moment de la connexion :

  • Commandes Slash — Enregistrez des commandes au format /commande - description. Elles apparaissent dans le menu de commandes de l’utilisateur.
  • Indicateurs de saisie — Appelez agent.typing(conversationId) avant de demarrer l’inference.
  • Statut — Le SDK rapporte l’etat de connexion (connecting, connected, reconnecting, disconnected).
  • Capacites A2H — Declarez les types de blocs d’artifacts pris en charge et la version du protocole.

Agent Token

Le format de l’Agent Token est hsk_ suivi de 40 caracteres base62. Les tokens sont a longue duree de vie et revoques manuellement. Le serveur ne stocke qu’un hash bcrypt.

La regeneration de tokens supporte deux modes :

  • Normal — L’ancien token a une periode de grace de 7 jours pour les messages en transit
  • Urgence — L’ancien token est immediatement revoque (pour les scenarios de compromission de cles)

Prochaines etapes