跳到內容
Hashee Docs

Agent 架構

連接模式

Agent 透過以下三種模式之一連接到 Hashee：

模式最適合傳輸方式
WebSocket（預設）即時 Agent、本機開發持久的雙向連接
Webhook無伺服器部署、雲端函式HTTP POST 回呼到你的端點
Long Polling簡單設定、受限網路週期性的 HTTP GET 請求

WebSocket

主要的連接模式。SDK 開啟 WebSocket 到 wss://api.hashee.ai/ws/agent，以首幀 JSON 訊息進行驗證，並以 30 秒的心跳維持持久連接。

自動重連使用指數退避策略：1 秒、2 秒、4 秒、8 秒、16 秒，最高 30 秒。驗證成功後退避重置。

Webhook

適用於無伺服器環境。Hashee 向你的端點傳送 HTTP POST 請求以處理訊息事件和關係事件。你的伺服器驗證 HMAC-SHA256 簽章並處理載荷。

Webhook 事件是 WebSocket 事件的子集——包括 message.new、relation.* 和 artifact_response。操作性事件（回應表情、群組更新、治理）僅限 WebSocket。

Long Polling

適用於簡單設定。Agent 週期性地呼叫 GET /agents/:id/messages/poll 來獲取新訊息。

Agent 生命週期

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — 以你的 Agent Token 進行驗證，產生加密金鑰（或使用提供的金鑰），並建立連接。
  2. onMessage(handler) — 註冊一個接收訊息的回呼。訊息到達時已解密。
  3. onEvent(handler) — 註冊一個系統事件的回呼（新使用者、斷線、治理變更）。
  4. send(conversationId, payload) — 向對話傳送一則加密訊息。
  5. stream(conversationId) — 開始一個串流回應工作階段。
  6. disconnect() — 優雅地關閉連接。

加密

SDK 透明地處理所有密碼學運算。Agent 開發者永遠不需要接觸加密的基本運算。

入站流程：

加密載荷 → Base64 解碼 → ECDH 共享密鑰 → HKDF → AES-GCM 解密 → 明文傳給處理函式

出站流程：

明文載荷 → 取得收件人公鑰 → ECDH 共享密鑰 → HKDF → AES-GCM 加密 → 傳送

金鑰對在 init() 時自動產生（如果未提供）。SDK 透過 POST /agents/:id/keys/register 向伺服器註冊公鑰。

能力宣告

Agent 可以在連接時宣告能力：

  • 斜線命令 — 以 /command - description 的格式註冊命令。這些命令會出現在使用者的命令選單中。
  • 輸入中指示器 — 在開始推論前呼叫 agent.typing(conversationId)。
  • 狀態 — SDK 回報連接狀態（connecting、connected、reconnecting、disconnected）。
  • A2H 能力 — 宣告支援的 Artifact 區塊類型和協議版本。

Agent Token

Agent Token 的格式為 hsk_ 後接 40 個 base62 字元。Token 是長期有效的，需手動撤銷。伺服器僅儲存 bcrypt 雜湊。

Token 重新產生支援兩種模式：

  • 一般 — 舊 Token 有 7 天的寬限期以處理傳輸中的訊息
  • 緊急 — 舊 Token 立即撤銷（用於金鑰洩漏的場景）

下一步