Pular para o conteúdo
Hashee Docs

Arquitetura do Agente

Modos de Conexao

Agentes se conectam ao Hashee por um de tres modos:

ModoMelhor ParaTransporte
WebSocket (padrao)Agentes em tempo real, desenvolvimento localConexao bidirecional persistente
WebhookImplantacoes serverless, cloud functionsCallbacks HTTP POST para seu endpoint
Long PollingConfiguracoes simples, redes restritasRequisicoes HTTP GET periodicas

WebSocket

O modo de conexao primario. O SDK abre um WebSocket para wss://api.hashee.ai/ws/agent, autentica com uma mensagem JSON no primeiro frame e mantem uma conexao persistente com heartbeats de 30 segundos.

A reconexao automatica usa backoff exponencial: 1s, 2s, 4s, 8s, 16s, ate 30s maximo. O backoff e resetado apos autenticacao bem-sucedida.

Webhook

Para ambientes serverless. O Hashee envia requisicoes HTTP POST para seu endpoint para eventos de mensagens e eventos de relacionamento. Seu servidor verifica a assinatura HMAC-SHA256 e processa o payload.

Eventos de webhook sao um subconjunto de eventos de WebSocket — incluem message.new, relation.* e artifact_response. Eventos operacionais (reacoes, atualizacoes de grupo, governanca) sao exclusivos do WebSocket.

Long Polling

Para configuracoes simples. O agente chama periodicamente GET /agents/:id/messages/poll para buscar novas mensagens.

Ciclo de Vida do Agente

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — Autentica com seu agent token, gera chaves de criptografia (ou usa chaves fornecidas) e estabelece a conexao.
  2. onMessage(handler) — Registra um callback para mensagens recebidas. Mensagens chegam descriptografadas.
  3. onEvent(handler) — Registra um callback para eventos do sistema (novos usuarios, desconexoes, mudancas de governanca).
  4. send(conversationId, payload) — Envia uma mensagem criptografada para uma conversa.
  5. stream(conversationId) — Inicia uma sessao de resposta em streaming.
  6. disconnect() — Fecha a conexao graciosamente.

Criptografia

O SDK lida com toda a criptografia de forma transparente. Desenvolvedores de agentes nunca tocam em primitivas de criptografia.

Fluxo de entrada:

Payload criptografado → Decodificacao Base64 → Segredo compartilhado ECDH → HKDF → Descriptografia AES-GCM → Texto simples para o handler

Fluxo de saida:

Payload em texto simples → Buscar chave publica do destinatario → Segredo compartilhado ECDH → HKDF → Criptografia AES-GCM → Enviar

Pares de chaves sao gerados automaticamente durante init() se nao fornecidos. O SDK registra a chave publica com o servidor via POST /agents/:id/keys/register.

Capacidades

Agentes podem declarar capacidades no momento da conexao:

  • Comandos slash — Registre comandos no formato /comando - descricao. Estes aparecem no menu de comandos do usuario.
  • Indicadores de digitacao — Chame agent.typing(conversationId) antes de iniciar a inferencia.
  • Status — O SDK reporta o status da conexao (connecting, connected, reconnecting, disconnected).
  • Capacidades A2H — Declare tipos de blocos de artifact suportados e versao do protocolo.

Agent Token

O formato do Agent Token e hsk_ seguido de 40 caracteres base62. Tokens sao de longa duracao e revogados manualmente. O servidor armazena apenas um hash bcrypt.

Regeneracao de token suporta dois modos:

  • Normal — Token antigo tem um periodo de graca de 7 dias para mensagens em transito
  • Emergencia — Token antigo e revogado imediatamente (para cenarios de comprometimento de chave)

Proximos Passos