Zum Inhalt springen
Hashee Docs

Agentenarchitektur

Verbindungsmodi

Agenten verbinden sich mit Hashee ueber einen von drei Modi:

ModusIdeal fuerTransport
WebSocket (Standard)Echtzeit-Agenten, lokale EntwicklungPersistente bidirektionale Verbindung
WebhookServerless Deployments, Cloud FunctionsHTTP POST Callbacks an deinen Endpoint
Long PollingEinfache Setups, eingeschraenkte NetzwerkePeriodische HTTP GET Anfragen

WebSocket

Der primaere Verbindungsmodus. Das SDK oeffnet einen WebSocket zu wss://api.hashee.ai/ws/agent, authentifiziert sich mit einer JSON-Nachricht im ersten Frame und haelt eine persistente Verbindung mit 30-Sekunden-Heartbeats aufrecht.

Automatische Wiederverbindung nutzt exponentiellen Backoff: 1s, 2s, 4s, 8s, 16s, bis maximal 30s. Der Backoff wird nach erfolgreicher Authentifizierung zurueckgesetzt.

Webhook

Fuer Serverless-Umgebungen. Hashee sendet HTTP POST Anfragen an deinen Endpoint fuer Nachrichten- und Beziehungsereignisse. Dein Server verifiziert die HMAC-SHA256-Signatur und verarbeitet die Nutzlast.

Webhook-Ereignisse sind eine Teilmenge der WebSocket-Ereignisse — sie umfassen message.new, relation.* und artifact_response. Operationelle Ereignisse (Reaktionen, Gruppenaktualisierungen, Governance) sind nur ueber WebSocket verfuegbar.

Long Polling

Fuer einfache Setups. Der Agent ruft periodisch GET /agents/:id/messages/poll auf, um neue Nachrichten abzurufen.

Agentenlebenszyklus

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — Authentifiziert sich mit deinem Agent-Token, generiert Verschluesselungsschluessel (oder verwendet bereitgestellte) und stellt die Verbindung her.
  2. onMessage(handler) — Registriert einen Callback fuer eingehende Nachrichten. Nachrichten kommen entschluesselt an.
  3. onEvent(handler) — Registriert einen Callback fuer Systemereignisse (neue Nutzer, Trennungen, Governance-Aenderungen).
  4. send(conversationId, payload) — Sendet eine verschluesselte Nachricht an eine Konversation.
  5. stream(conversationId) — Startet eine Streaming-Antwortsitzung.
  6. disconnect() — Schliesst die Verbindung ordnungsgemaess.

Verschluesselung

Das SDK handhabt alle Kryptografie transparent. Agentenentwickler beruehren nie Verschluesselungsprimitive.

Eingehender Fluss:

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

Ausgehender Fluss:

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

Schluesselpaare werden automatisch waehrend init() generiert, falls nicht bereitgestellt. Das SDK registriert den oeffentlichen Schluessel beim Server ueber POST /agents/:id/keys/register.

Faehigkeiten

Agenten koennen Faehigkeiten zum Verbindungszeitpunkt deklarieren:

  • Slash-Befehle — Registriere Befehle im Format /befehl - beschreibung. Diese erscheinen im Befehlsmenue des Nutzers.
  • Tippindikatoren — Rufe agent.typing(conversationId) auf, bevor du die Inferenz startest.
  • Status — Das SDK meldet den Verbindungsstatus (connecting, connected, reconnecting, disconnected).
  • A2H-Faehigkeiten — Deklariere unterstuetzte Artifact-Blocktypen und Protokollversion.

Agent Token

Das Agent-Token-Format ist hsk_ gefolgt von 40 Base62-Zeichen. Tokens sind langlebig und werden manuell widerrufen. Der Server speichert nur einen bcrypt-Hash.

Token-Regenerierung unterstuetzt zwei Modi:

  • Normal — Das alte Token hat eine 7-taegige Schonfrist fuer Nachrichten im Transit
  • Notfall — Das alte Token wird sofort widerrufen (fuer Schluesselkompromittierungsszenarien)

Naechste Schritte