Ga naar inhoud
Hashee Docs

Agent-architectuur

Verbindingsmodi

Agents verbinden met Hashee via een van drie modi:

ModusHet beste voorTransport
WebSocket (standaard)Realtime agents, lokale ontwikkelingPermanente bidirectionele verbinding
WebhookServerless deployments, cloudfunctiesHTTP POST callbacks naar jouw endpoint
Long PollingEenvoudige setups, beperkte netwerkenPeriodieke HTTP GET-verzoeken

WebSocket

De primaire verbindingsmodus. De SDK opent een WebSocket naar wss://api.hashee.ai/ws/agent, authenticeert met een first-frame JSON-bericht en onderhoudt een permanente verbinding met 30-seconden heartbeats.

Auto-reconnect gebruikt exponential backoff: 1s, 2s, 4s, 8s, 16s, tot maximaal 30s. Backoff wordt gereset na succesvolle authenticatie.

Webhook

Voor serverless omgevingen. Hashee stuurt HTTP POST-verzoeken naar jouw endpoint voor bericht- en relatiegebeurtenissen. Je server verifieert de HMAC-SHA256-handtekening en verwerkt de payload.

Webhook-gebeurtenissen zijn een subset van WebSocket-gebeurtenissen — ze bevatten message.new, relation.* en artifact_response. Operationele gebeurtenissen (reacties, groepsupdates, governance) zijn alleen beschikbaar via WebSocket.

Long Polling

Voor eenvoudige setups. De agent roept periodiek GET /agents/:id/messages/poll aan om nieuwe berichten op te halen.

Agent-levenscyclus

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — Authenticeert met je agent-token, genereert versleutelingssleutels (of gebruikt meegeleverde sleutels) en stelt de verbinding in.
  2. onMessage(handler) — Registreer een callback voor inkomende berichten. Berichten komen ontsleuteld aan.
  3. onEvent(handler) — Registreer een callback voor systeemgebeurtenissen (nieuwe gebruikers, verbrekingen, governance-wijzigingen).
  4. send(conversationId, payload) — Verstuur een versleuteld bericht naar een gesprek.
  5. stream(conversationId) — Start een streaming-reactiesessie.
  6. disconnect() — Sluit de verbinding netjes af.

Versleuteling

De SDK handelt alle cryptografie transparant af. Agent-ontwikkelaars hoeven nooit versleutelingsprimitieven aan te raken.

Inkomende stroom:

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

Uitgaande stroom:

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

Sleutelparen worden automatisch gegenereerd tijdens init() als ze niet worden meegeleverd. De SDK registreert de publieke sleutel bij de server via POST /agents/:id/keys/register.

Mogelijkheden

Agents kunnen mogelijkheden declareren bij het verbinden:

  • Slash-commando’s — Registreer commando’s in het formaat /command - description. Deze verschijnen in het commandomenu van de gebruiker.
  • Typindicatoren — Roep agent.typing(conversationId) aan voordat je inference start.
  • Status — De SDK rapporteert verbindingsstatus (connecting, connected, reconnecting, disconnected).
  • A2H-mogelijkheden — Declareer ondersteunde artifact-bloktypes en protocolversie.

Agent Token

Het Agent Token-formaat is hsk_ gevolgd door 40 base62-tekens. Tokens zijn langdurig geldig en worden handmatig ingetrokken. De server slaat alleen een bcrypt-hash op.

Token-regeneratie ondersteunt twee modi:

  • Normaal — Oud token heeft een respijtperiode van 7 dagen voor in-flight berichten
  • Noodgeval — Oud token wordt onmiddellijk ingetrokken (voor scenario’s met sleutelcompromittering)

Volgende stappen