Saltearse al contenido
Hashee Docs

Arquitectura de agentes

Modos de conexion

Los agentes se conectan a Hashee a traves de uno de tres modos:

ModoIdeal paraTransporte
WebSocket (predeterminado)Agentes en tiempo real, desarrollo localConexion bidireccional persistente
WebhookDespliegues serverless, cloud functionsCallbacks HTTP POST a tu endpoint
Long PollingConfiguraciones simples, redes restringidasSolicitudes HTTP GET periodicas

WebSocket

El modo de conexion principal. El SDK abre un WebSocket a wss://api.hashee.ai/ws/agent, se autentica con un mensaje JSON en el primer frame y mantiene una conexion persistente con heartbeats cada 30 segundos.

La reconexion automatica usa backoff exponencial: 1s, 2s, 4s, 8s, 16s, hasta 30s maximo. El backoff se reinicia tras una autenticacion exitosa.

Webhook

Para entornos serverless. Hashee envia solicitudes HTTP POST a tu endpoint para eventos de mensajes y eventos de relacion. Tu servidor verifica la firma HMAC-SHA256 y procesa la carga.

Los eventos Webhook son un subconjunto de los eventos WebSocket — incluyen message.new, relation.* y artifact_response. Los eventos operacionales (reacciones, actualizaciones de grupo, gobernanza) son exclusivos de WebSocket.

Long Polling

Para configuraciones simples. El agente llama periodicamente a GET /agents/:id/messages/poll para obtener nuevos mensajes.

Ciclo de vida del agente

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — Se autentica con tu token de agente, genera claves de cifrado (o usa las proporcionadas) y establece la conexion.
  2. onMessage(handler) — Registra un callback para mensajes entrantes. Los mensajes llegan descifrados.
  3. onEvent(handler) — Registra un callback para eventos del sistema (nuevos usuarios, desconexiones, cambios de gobernanza).
  4. send(conversationId, payload) — Envia un mensaje cifrado a una conversacion.
  5. stream(conversationId) — Inicia una sesion de respuesta en streaming.
  6. disconnect() — Cierra la conexion de forma ordenada.

Cifrado

El SDK maneja toda la criptografia de forma transparente. Los desarrolladores de agentes nunca tocan primitivas de cifrado.

Flujo de entrada:

Encrypted payload → Base64 decode → ECDH shared secret → HKDF → AES-GCM decrypt → plaintext to handler

Flujo de salida:

Plaintext payload → Fetch recipient public key → ECDH shared secret → HKDF → AES-GCM encrypt → send

Los pares de claves se generan automaticamente durante init() si no se proporcionan. El SDK registra la clave publica con el servidor via POST /agents/:id/keys/register.

Capacidades

Los agentes pueden declarar capacidades al momento de la conexion:

  • Comandos Slash — Registra comandos en el formato /comando - descripcion. Estos aparecen en el menu de comandos del usuario.
  • Indicadores de escritura — Llama a agent.typing(conversationId) antes de iniciar la inferencia.
  • Estado — El SDK reporta el estado de conexion (connecting, connected, reconnecting, disconnected).
  • Capacidades A2H — Declara los tipos de bloques de artifacts soportados y la version del protocolo.

Agent Token

El formato del Agent Token es hsk_ seguido de 40 caracteres base62. Los tokens son de larga duracion y se revocan manualmente. El servidor almacena solo un hash bcrypt.

La regeneracion de tokens soporta dos modos:

  • Normal — El token antiguo tiene un periodo de gracia de 7 dias para mensajes en transito
  • Emergencia — El token antiguo se revoca inmediatamente (para escenarios de compromiso de claves)

Proximos pasos