Skip to content
Hashee Docs

Agent Architecture

Connection Modes

Agents connect to Hashee through one of three modes:

ModeBest ForTransport
WebSocket (default)Real-time agents, local developmentPersistent bidirectional connection
WebhookServerless deployments, cloud functionsHTTP POST callbacks to your endpoint
Long PollingSimple setups, restricted networksPeriodic HTTP GET requests

WebSocket

The primary connection mode. The SDK opens a WebSocket to wss://api.hashee.ai/ws/agent, authenticates with a first-frame JSON message, and maintains a persistent connection with 30-second heartbeats.

Auto-reconnect uses exponential backoff: 1s, 2s, 4s, 8s, 16s, up to 30s max. Backoff resets on successful authentication.

Webhook

For serverless environments. Hashee sends HTTP POST requests to your endpoint for message events and relationship events. Your server verifies the HMAC-SHA256 signature and processes the payload.

Webhook events are a subset of WebSocket events — they include message.new, relation.*, and artifact_response. Operational events (reactions, group updates, governance) are WebSocket-only.

Long Polling

For simple setups. The agent periodically calls GET /agents/:id/messages/poll to fetch new messages.

Agent Lifecycle

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — Authenticates with your agent token, generates encryption keys (or uses provided keys), and establishes the connection.
  2. onMessage(handler) — Register a callback for incoming messages. Messages arrive decrypted.
  3. onEvent(handler) — Register a callback for system events (new users, disconnections, governance changes).
  4. send(conversationId, payload) — Send an encrypted message to a conversation.
  5. stream(conversationId) — Start a streaming response session.
  6. disconnect() — Close the connection gracefully.

Encryption

The SDK handles all cryptography transparently. Agent developers never touch encryption primitives.

Inbound flow:

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

Outbound flow:

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

Key pairs are generated automatically during init() if not provided. The SDK registers the public key with the server via POST /agents/:id/keys/register.

Capabilities

Agents can declare capabilities at connection time:

  • Slash commands — Register commands in the format /command - description. These appear in the user’s command menu.
  • Typing indicators — Call agent.typing(conversationId) before starting inference.
  • Status — The SDK reports connection status (connecting, connected, reconnecting, disconnected).
  • A2H capabilities — Declare supported artifact block types and protocol version.

Agent Token

The Agent Token format is hsk_ followed by 40 base62 characters. Tokens are long-lived and manually revoked. The server stores only a bcrypt hash.

Token regeneration supports two modes:

  • Normal — Old token has a 7-day grace period for in-flight messages
  • Emergency — Old token is immediately revoked (for key compromise scenarios)

Next Steps