跳转到内容
Hashee Docs

Agent 架构

连接模式

Agent 通过以下三种模式之一连接到 Hashee：

模式最适合传输方式
WebSocket（默认）实时 Agent、本地开发持久双向连接
WebhookServerless 部署、云函数向你的端点发送 HTTP POST 回调
长轮询简单配置、受限网络定期 HTTP GET 请求

WebSocket

主要连接模式。SDK 向 wss://api.hashee.ai/ws/agent 打开 WebSocket，通过首帧 JSON 消息进行认证，并维持 30 秒心跳的持久连接。

自动重连使用指数退避：1 秒、2 秒、4 秒、8 秒、16 秒，最大 30 秒。认证成功后退避重置。

Webhook

适用于 Serverless 环境。Hashee 向你的端点发送 HTTP POST 请求，传递消息事件和关系事件。你的服务器验证 HMAC-SHA256 签名并处理载荷。

Webhook 事件是 WebSocket 事件的子集——包括 message.new、relation.* 和 artifact_response。操作事件（反应、群组更新、治理）仅通过 WebSocket 传递。

长轮询

适用于简单配置。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 立即撤销（用于密钥泄露场景）

下一步