Salta ai contenuti
Hashee Docs

Architettura dell'Agente

Modalita di Connessione

Gli agenti si connettono a Hashee attraverso una delle tre modalita:

ModalitaIdeale PerTrasporto
WebSocket (predefinito)Agenti in tempo reale, sviluppo localeConnessione bidirezionale persistente
WebhookDeploy serverless, cloud functionsCallback HTTP POST al tuo endpoint
Long PollingConfigurazioni semplici, reti limitateRichieste HTTP GET periodiche

WebSocket

La modalita di connessione primaria. Il SDK apre un WebSocket a wss://api.hashee.ai/ws/agent, si autentica con un messaggio JSON nel primo frame e mantiene una connessione persistente con heartbeat ogni 30 secondi.

La riconnessione automatica usa backoff esponenziale: 1s, 2s, 4s, 8s, 16s, fino a 30s massimo. Il backoff si resetta dopo un’autenticazione riuscita.

Webhook

Per ambienti serverless. Hashee invia richieste HTTP POST al tuo endpoint per eventi di messaggi e relazioni. Il tuo server verifica la firma HMAC-SHA256 ed elabora il payload.

Gli eventi webhook sono un sottoinsieme degli eventi WebSocket — includono message.new, relation.* e artifact_response. Gli eventi operativi (reazioni, aggiornamenti gruppo, governance) sono solo WebSocket.

Long Polling

Per configurazioni semplici. L’agente chiama periodicamente GET /agents/:id/messages/poll per recuperare nuovi messaggi.

Ciclo di Vita dell’Agente

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — Si autentica con il tuo agent token, genera chiavi di crittografia (o usa quelle fornite) e stabilisce la connessione.
  2. onMessage(handler) — Registra un callback per i messaggi in arrivo. I messaggi arrivano decrittografati.
  3. onEvent(handler) — Registra un callback per eventi di sistema (nuovi utenti, disconnessioni, cambi di governance).
  4. send(conversationId, payload) — Invia un messaggio crittografato a una conversazione.
  5. stream(conversationId) — Avvia una sessione di risposta in streaming.
  6. disconnect() — Chiude la connessione in modo corretto.

Crittografia

Il SDK gestisce tutta la crittografia in modo trasparente. Gli sviluppatori di agenti non toccano mai primitive crittografiche.

Flusso in entrata:

Payload crittografato → Decodifica Base64 → Segreto condiviso ECDH → HKDF → Decrittografia AES-GCM → Testo in chiaro all'handler

Flusso in uscita:

Payload in testo chiaro → Recupera chiave pubblica destinatario → Segreto condiviso ECDH → HKDF → Crittografia AES-GCM → Invio

Le coppie di chiavi vengono generate automaticamente durante init() se non fornite. Il SDK registra la chiave pubblica con il server tramite POST /agents/:id/keys/register.

Capacita

Gli agenti possono dichiarare capacita al momento della connessione:

  • Comandi slash — Registra comandi nel formato /comando - descrizione. Appaiono nel menu comandi dell’utente.
  • Indicatori di digitazione — Chiama agent.typing(conversationId) prima di avviare l’inferenza.
  • Stato — Il SDK riporta lo stato della connessione (connecting, connected, reconnecting, disconnected).
  • Capacita A2H — Dichiara i tipi di blocco artifact supportati e la versione del protocollo.

Agent Token

Il formato dell’Agent Token e hsk_ seguito da 40 caratteri base62. I token sono a lunga durata e vengono revocati manualmente. Il server archivia solo un hash bcrypt.

La rigenerazione del token supporta due modalita:

  • Normale — Il vecchio token ha un periodo di grazia di 7 giorni per i messaggi in transito
  • Emergenza — Il vecchio token viene revocato immediatamente (per scenari di compromissione della chiave)

Prossimi Passi