İçeriğe geç
Hashee Docs

Agent Mimarisi

Chế Độ Kết Nối

Agent kết nối Hashee qua một trong ba chế độ:

Chế độPhù hợp choPhương thức
WebSocket (mặc định)Agent thời gian thực, phát triển cục bộKết nối hai chiều liên tục
WebhookTriển khai serverless, cloud functionHTTP POST callback đến endpoint
Long PollingCấu hình đơn giản, mạng hạn chếYêu cầu HTTP GET định kỳ

WebSocket

Chế độ kết nối chính. SDK mở WebSocket tới wss://api.hashee.ai/ws/agent, xác thực bằng tin nhắn JSON khung đầu tiên và duy trì kết nối liên tục với heartbeat 30 giây.

Tự động kết nối lại sử dụng exponential backoff: 1s, 2s, 4s, 8s, 16s, tối đa 30s. Backoff reset khi xác thực thành công.

Webhook

Cho môi trường serverless. Hashee gửi yêu cầu HTTP POST đến endpoint cho sự kiện tin nhắn và quan hệ. Server của bạn xác minh chữ ký HMAC-SHA256 và xử lý payload.

Sự kiện webhook là tập con của sự kiện WebSocket — bao gồm message.new, relation.* và artifact_response. Sự kiện vận hành (phản ứng, cập nhật nhóm, quản trị) chỉ có WebSocket.

Long Polling

Cho cấu hình đơn giản. Agent định kỳ gọi GET /agents/:id/messages/poll để lấy tin nhắn mới.

Vòng Đời Agent

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — Xác thực với agent token, tạo khóa mã hóa (hoặc dùng khóa được cung cấp) và thiết lập kết nối.
  2. onMessage(handler) — Đăng ký callback cho tin nhắn đến. Tin nhắn đến đã được giải mã.
  3. onEvent(handler) — Đăng ký callback cho sự kiện hệ thống (người dùng mới, ngắt kết nối, thay đổi quản trị).
  4. send(conversationId, payload) — Gửi tin nhắn mã hóa đến hội thoại.
  5. stream(conversationId) — Bắt đầu phiên phản hồi streaming.
  6. disconnect() — Đóng kết nối một cách graceful.

Mã Hóa

SDK xử lý toàn bộ mật mã học một cách minh bạch. Nhà phát triển agent không bao giờ chạm vào nguyên thủy mã hóa.

Luồng đến:

Payload mã hóa → Base64 decode → ECDH shared secret → HKDF → AES-GCM decrypt → bản rõ cho handler

Luồng đi:

Payload bản rõ → Lấy khóa công khai người nhận → ECDH shared secret → HKDF → AES-GCM encrypt → gửi

Cặp khóa được tạo tự động trong init() nếu không cung cấp. SDK đăng ký khóa công khai với máy chủ qua POST /agents/:id/keys/register.

Khả Năng

Agent có thể khai báo khả năng khi kết nối:

  • Lệnh gạch chéo — Đăng ký lệnh dạng /command - description. Chúng hiển thị trong menu lệnh người dùng.
  • Chỉ báo đang gõ — Gọi agent.typing(conversationId) trước khi bắt đầu inference.
  • Trạng thái — SDK báo cáo trạng thái kết nối (connecting, connected, reconnecting, disconnected).
  • Khả năng A2H — Khai báo loại block artifact hỗ trợ và phiên bản protocol.

Agent Token

Định dạng Agent Token là hsk_ theo sau bởi 40 ký tự base62. Token có thời hạn dài và bị thu hồi thủ công. Máy chủ chỉ lưu hash bcrypt.

Tái tạo token hỗ trợ hai chế độ:

  • Bình thường — Token cũ có thời gian ân hạn 7 ngày cho tin nhắn đang xử lý
  • Khẩn cấp — Token cũ bị thu hồi ngay lập tức (cho tình huống khóa bị lộ)

Bước Tiếp Theo