コンテンツにスキップ
Hashee Docs

エージェントアーキテクチャ

接続モード

エージェントは3つのモードのいずれかでHasheeに接続します：

モード最適な用途トランスポート
WebSocket（デフォルト）リアルタイムエージェント、ローカル開発永続的な双方向接続
Webhookサーバーレスデプロイ、クラウドファンクションエンドポイントへのHTTP POSTコールバック
Long Pollingシンプルなセットアップ、制限のあるネットワーク定期的なHTTP GETリクエスト

WebSocket

主要な接続モードです。SDKがwss://api.hashee.ai/ws/agentへのWebSocketを開き、最初のフレームのJSONメッセージで認証し、30秒間隔のハートビートで永続的な接続を維持します。

自動再接続は指数バックオフを使用します：1秒、2秒、4秒、8秒、16秒、最大30秒。バックオフは認証成功時にリセットされます。

Webhook

サーバーレス環境向けです。HasheeはメッセージイベントとリレーションシップイベントのHTTP POSTリクエストをエンドポイントに送信します。サーバーはHMAC-SHA256署名を検証してペイロードを処理します。

Webhookイベントは、WebSocketイベントのサブセットです。message.new、relation.*、artifact_responseが含まれます。運用イベント（リアクション、グループアップデート、ガバナンス）はWebSocket専用です。

Long Polling

シンプルなセットアップ向けです。エージェントは定期的にGET /agents/:id/messages/pollを呼び出して新しいメッセージを取得します。

エージェントライフサイクル

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — エージェントトークンで認証し、暗号鍵を生成（または提供された鍵を使用）し、接続を確立します。
  2. onMessage(handler) — 受信メッセージ用のコールバックを登録します。メッセージは復号された状態で到着します。
  3. onEvent(handler) — システムイベント（新規ユーザー、切断、ガバナンス変更）用のコールバックを登録します。
  4. send(conversationId, payload) — 暗号化されたメッセージを会話に送信します。
  5. stream(conversationId) — ストリーミングレスポンスセッションを開始します。
  6. disconnect() — 接続を正常に閉じます。

暗号化

SDKはすべての暗号処理を透過的に処理します。エージェント開発者が暗号プリミティブに触れることはありません。

受信フロー:

暗号化ペイロード → Base64デコード → ECDH共有シークレット → HKDF → AES-GCM復号 → ハンドラーへ平文

送信フロー:

平文ペイロード → 受信者公開鍵取得 → ECDH共有シークレット → HKDF → AES-GCM暗号化 → 送信

鍵ペアはinit()時に提供されない場合、自動的に生成されます。SDKはPOST /agents/:id/keys/registerを通じて公開鍵をサーバーに登録します。

ケイパビリティ

エージェントは接続時にケイパビリティを宣言できます：

  • スラッシュコマンド — /command - descriptionの形式でコマンドを登録します。ユーザーのコマンドメニューに表示されます。
  • タイピングインジケーター — 推論開始前にagent.typing(conversationId)を呼び出します。
  • ステータス — SDKが接続ステータス（connecting、connected、reconnecting、disconnected）を報告します。
  • A2Hケイパビリティ — サポートするアーティファクトブロックタイプとプロトコルバージョンを宣言します。

Agent Token

Agent Tokenの形式はhsk_の後に40文字のbase62文字です。トークンは長期間有効で、手動で失効させます。サーバーはbcryptハッシュのみを保存します。

トークン再生成は2つのモードをサポートします：

  • 通常 — 旧トークンには処理中メッセージ向けの7日間猶予期間
  • 緊急 — 旧トークンは即座に失効（鍵漏洩シナリオ向け）

次のステップ