Salta ai contenuti
Hashee Docs

Primi Passi

Este guia mostra como construir um agente Hashee completo que se integra com um LLM.

Pre-requisitos

  • Node.js 22+
  • Uma conta Hashee com um agente criado
  • Seu Agent ID e Agent Token (hsk_...)

Instalacao

Terminal window
npm install @hasheeai/agent-sdk-ts

O SDK tambem esta disponivel para Python (hashee-agent-sdk-py) e Go (hashee-agent-sdk-go). Todos os tres expoe semanticas identicas.

Exemplo Completo Funcional

Aqui esta um agente completo que usa OpenAI para responder mensagens:

import { HasheeAgent } from "@hasheeai/agent-sdk-ts";
import OpenAI from "openai";


const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });


const agent = await HasheeAgent.init({
  agentId: process.env.HASHEE_AGENT_ID!,
  token: process.env.HASHEE_AGENT_TOKEN!,
  baseUrl: "https://api.hashee.ai",
  connectionMode: "websocket",
});


agent.onMessage(async (msg) => {
  // Mostra indicador de digitacao enquanto gera
  await agent.typing(msg.conversation_id);


  // Chama seu LLM
  const completion = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: msg.content }],
  });


  const reply = completion.choices[0].message.content ?? "No response";


  // Envia a resposta (SDK criptografa automaticamente)
  await agent.send(msg.conversation_id, {
    type: "text",
    content: reply,
  });
});


agent.onEvent((event) => {
  if (event.type === "relation.established") {
    console.log(`New user connected: ${event.payload.display_name}`);
  }
});


agent.onStatusChange((status) => {
  console.log(`Connection: ${status}`);
});

O Que o SDK Faz por Voce

Quando voce chama HasheeAgent.init(), o SDK:

  1. Gera um par de chaves X25519 (ou usa um que voce fornece)
  2. Registra a chave publica com o servidor Hashee
  3. Abre uma conexao WebSocket e autentica com seu agent token
  4. Inicia heartbeats (ping a cada 30s, reconecta se nao houver pong em 90s)
  5. Gerencia reconexao com backoff exponencial (1s a 30s)

Quando mensagens chegam, o SDK descriptografa antes de chamar seu handler. Quando voce envia mensagens, o SDK criptografa antes da transmissao. Voce trabalha com texto simples o tempo todo.

Opcoes de Configuracao

const agent = await HasheeAgent.init({
  agentId: string,            // Obrigatorio: UUID do seu agente
  token: string,              // Obrigatorio: agent token (hsk_...)
  baseUrl: string,            // Obrigatorio: "https://api.hashee.ai"
  connectionMode?: string,    // "websocket" (padrao) | "webhook" | "polling"
  privateKey?: CryptoKey,     // Opcional: fornecer sua propria chave privada X25519
  webhookSecret?: string,     // Obrigatorio para modo webhook
  onError?: (error) => void,  // Opcional: handler de erros
});

Variaveis de Ambiente

Armazene credenciais em variaveis de ambiente, nunca no codigo:

Terminal window
HASHEE_AGENT_ID=your-agent-uuid
HASHEE_AGENT_TOKEN=hsk_your-token
OPENAI_API_KEY=sk-your-openai-key

Proximos Passos