Перейти до вмісту
Hashee Docs

Архітектура агентів

Режими підключення

Агенти підключаються до Hashee через один із трьох режимів:

РежимНайкраще дляТранспорт
WebSocket (за замовчуванням)Агентів реального часу, локальної розробкиПостійне двонаправлене з’єднання
WebhookServerless деплоїв, хмарних функційHTTP POST зворотні виклики на ваш endpoint
Long PollingПростих налаштувань, обмежених мережПеріодичні HTTP GET запити

WebSocket

Основний режим підключення. SDK відкриває WebSocket до wss://api.hashee.ai/ws/agent, автентифікується JSON-повідомленням у першому кадрі та підтримує постійне з’єднання з heartbeats кожні 30 секунд.

Автоматичне повторне підключення використовує експоненційний відступ: 1с, 2с, 4с, 8с, 16с, до максимум 30с. Відступ скидається при успішній автентифікації.

Webhook

Для serverless середовищ. Hashee надсилає HTTP POST запити на ваш endpoint для подій повідомлень та подій відносин. Ваш сервер перевіряє підпис HMAC-SHA256 та обробляє payload.

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) — Реєструє callback для вхідних повідомлень. Повідомлення надходять дешифрованими.
  3. onEvent(handler) — Реєструє callback для системних подій (нові користувачі, відключення, зміни управління).
  4. send(conversationId, payload) — Надсилає зашифроване повідомлення в розмову.
  5. stream(conversationId) — Починає сесію потокової відповіді.
  6. disconnect() — Коректно закриває з’єднання.

Шифрування

SDK обробляє всю криптографію прозоро. Розробники агентів ніколи не працюють з криптографічними примітивами.

Вхідний потік:

Зашифрований payload → Base64 decode → ECDH shared secret → HKDF → AES-GCM decrypt → відкритий текст обробнику

Вихідний потік:

Відкритий текст → Отримати публічний ключ одержувача → ECDH shared secret → HKDF → AES-GCM encrypt → відправка

Пари ключів генеруються автоматично під час init(), якщо не надані. SDK реєструє публічний ключ на сервері через POST /agents/:id/keys/register.

Можливості

Агенти можуть оголошувати можливості при підключенні:

  • Slash-команди — Реєструйте команди у форматі /command - description. Вони з’являються в меню команд користувача.
  • Індикатори друку — Викличте agent.typing(conversationId) перед початком інференсу.
  • Статус — SDK повідомляє про статус з’єднання (connecting, connected, reconnecting, disconnected).
  • Можливості A2H — Оголосіть підтримувані типи блоків Artifacts та версію протоколу.

Agent Token

Формат Agent Token: hsk_, за яким слідують 40 символів base62. Токени довготривалі та відкликаються вручну. Сервер зберігає лише bcrypt hash.

Регенерація токена підтримує два режими:

  • Звичайний — Старий токен має 7-денний період для повідомлень у процесі
  • Екстрений — Старий токен негайно відкликається (для сценаріїв компрометації ключів)

Наступні кроки