Skip to content
Hashee Docs

Getting Started

This guide walks through building a complete Hashee agent that integrates with an LLM.

Prerequisites

  • Node.js 22+
  • A Hashee account with an agent created
  • Your Agent ID and Agent Token (hsk_...)

Installation

Terminal window
npm install @hasheeai/agent-sdk-ts

The SDK is also available for Python (hashee-agent-sdk-py) and Go (hashee-agent-sdk-go). All three expose identical semantics.

Full Working Example

Here is a complete agent that uses OpenAI to respond to messages:

import { HasheeAgent } from "@hasheeai/agent-sdk-ts";
import OpenAI from "openai";


const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });


const agent = await HasheeAgent.init({
  agentId: process.env.HASHEE_AGENT_ID!,
  token: process.env.HASHEE_AGENT_TOKEN!,
  baseUrl: "https://api.hashee.ai",
  connectionMode: "websocket",
});


agent.onMessage(async (msg) => {
  // Show typing indicator while generating
  await agent.typing(msg.conversation_id);


  // Call your LLM
  const completion = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: msg.content }],
  });


  const reply = completion.choices[0].message.content ?? "No response";


  // Send the reply (SDK encrypts automatically)
  await agent.send(msg.conversation_id, {
    type: "text",
    content: reply,
  });
});


agent.onEvent((event) => {
  if (event.type === "relation.established") {
    console.log(`New user connected: ${event.payload.display_name}`);
  }
});


agent.onStatusChange((status) => {
  console.log(`Connection: ${status}`);
});

What the SDK Does for You

When you call HasheeAgent.init(), the SDK:

  1. Generates an X25519 key pair (or uses one you provide)
  2. Registers the public key with the Hashee server
  3. Opens a WebSocket connection and authenticates with your agent token
  4. Starts heartbeats (ping every 30s, reconnect if no pong within 90s)
  5. Manages reconnection with exponential backoff (1s to 30s)

When messages arrive, the SDK decrypts them before calling your handler. When you send messages, the SDK encrypts them before transmission. You work with plaintext at all times.

Configuration Options

const agent = await HasheeAgent.init({
  agentId: string,            // Required: your agent's UUID
  token: string,              // Required: agent token (hsk_...)
  baseUrl: string,            // Required: "https://api.hashee.ai"
  connectionMode?: string,    // "websocket" (default) | "webhook" | "polling"
  privateKey?: CryptoKey,     // Optional: provide your own X25519 private key
  webhookSecret?: string,     // Required for webhook mode
  onError?: (error) => void,  // Optional: error handler
});

Environment Variables

Store credentials in environment variables, never in code:

Terminal window
HASHEE_AGENT_ID=your-agent-uuid
HASHEE_AGENT_TOKEN=hsk_your-token
OPENAI_API_KEY=sk-your-openai-key

Next Steps