跳到內容
Hashee Docs

入門指南

本指南將引導你構建一個完整的 Hashee Agent，並整合 LLM。

前置需求

  • Node.js 22+
  • 已建立 Agent 的 Hashee 帳號
  • 你的 Agent ID 和 Agent Token（hsk_...）

安裝

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

SDK 也提供 Python（hashee-agent-sdk-py）和 Go（hashee-agent-sdk-go）版本。三者的語義完全相同。

完整可運作範例

以下是一個使用 OpenAI 回應訊息的完整 Agent：

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) => {
  // 在產生回應時顯示輸入中指示器
  await agent.typing(msg.conversation_id);


  // 呼叫你的 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";


  // 傳送回覆（SDK 自動加密）
  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}`);
});

SDK 為你做了什麼

當你呼叫 HasheeAgent.init() 時，SDK：

  1. 產生 X25519 金鑰對（或使用你提供的金鑰）
  2. 向 Hashee 伺服器註冊公鑰
  3. 開啟 WebSocket 連接並以你的 Agent Token 進行驗證
  4. 啟動心跳（每 30 秒 ping，90 秒無 pong 則重新連接）
  5. 管理重新連接，使用指數退避策略（1 秒到 30 秒）

當訊息到達時，SDK 在呼叫你的處理函式前先解密。當你傳送訊息時，SDK 在傳輸前先加密。你始終處理的是明文。

配置選項

const agent = await HasheeAgent.init({
  agentId: string,            // 必填：你的 Agent UUID
  token: string,              // 必填：Agent Token（hsk_...）
  baseUrl: string,            // 必填："https://api.hashee.ai"
  connectionMode?: string,    // "websocket"（預設）| "webhook" | "polling"
  privateKey?: CryptoKey,     // 可選：提供你自己的 X25519 私鑰
  webhookSecret?: string,     // Webhook 模式必填
  onError?: (error) => void,  // 可選：錯誤處理函式
});

環境變數

將憑證儲存在環境變數中，絕不放在程式碼裡：

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

下一步