Passa al contenuto principale

Introduzione

Questa sezione documenta il Node Agent basato su LangGraph che espone un server HTTP/Socket.IO per chat in tempo reale, caricamento documenti/prodotti e integrazione con servizi esterni (Laravel app, Hatchet worker, Qdrant).

Architettura​

  • Server HTTP (Express): inizializzato in src/server.ts, applica CORS, parsing JSON, statici, routing HTTP da src/server/serverHttp.ts e gestore errori globale.
  • Socket.IO: avviato da initializeSocketServer in src/server/socketServer.ts con autenticazione JWT; gestisce eventi create_thread, chat_message, load_thread_messages e streaming chunk della risposta.
  • LangGraph App: definita in src/index.ts come grafo di stato con nodi agent e tools, model OpenAI (gpt-4o-mini) e strumenti dinamici in base alla configurazione (documenti, e‑commerce). Supporta checkpointer PostgreSQL opzionale.
  • Code di background: src/utils/queue.ts accoda eventi (es. chat:message, embed:*) verso il Worker Hatchet tramite WORKER_URL e salva in background gli ultimi messaggi della conversazione.
  • Integrazioni:
    • Laravel: src/services/laravelService.ts (limiti messaggi, creazione conversazioni, storage check, info client/IP, Woo tokens).
    • Qdrant: client REST in src/index.ts e servizi/tool dedicati (agentTools/qdrantService.ts, services/productRagSearchService.ts).
    • Traduzioni/i18n: src/translations/*, src/services/i18n.ts.

Flusso di esecuzione​

  1. Il client crea un thread via HTTP (POST /create-thread/:agentId) o via socket (create_thread).
  2. Il client invia un messaggio (chat_message su socket) con configurazione configurable (es. thread_id, agent_id, collection_name, language, companyName, flag hasDocuments, websiteUrl/baseFeedUrl, ecc.).
  3. L’App LangGraph costruisce il system prompt con regole e abilita i tool necessari, poi invoca il modello. Se il modello effettua tool calls, la conversazione passa al nodo tools e ritorna all’agent fino a risposta finale.
  4. Le risposte vengono streammate via Socket.IO in eventi: typing, chat_response_start, chat_response_chunk, chat_response_end.
  5. Se attivo, il checkpointer PostgreSQL memorizza lo stato del thread. Un task asincrono invia all’Hatchet i messaggi utente/assistant più recenti.

Endpoint principali (HTTP)​

  • POST /create-thread/:agentId: crea un nuovo thread e registra la conversazione su Laravel.
  • GET /thread/:threadId/messages: carica i messaggi del thread (se presenti nel checkpointer).
  • POST /upload/files/:collectionName: carica file (PDF, TXT, DOCX, CSV, XLS/XLSX, JSON, XML, YAML) e accoda il task su Worker.
  • POST /upload/url/:collectionName: embeddizza contenuti da URL/sitemap e accoda il task.
  • POST /upload/products/:collectionName: avvia l’elaborazione prodotti per e‑commerce.
  • GET /queue/tasks/:taskUuid: stato avanzamento di un task nella coda.
  • POST /queue/tasks/:taskUuid/cancel: annulla un task.
  • POST /estimate/sitemap: stima dimensione sitemap.
  • DELETE /collections/:collectionName/:resourceUuid: elimina documenti per risorsa.
  • DELETE /collections/:collectionName e DELETE /upload/:vectorStoreUuid: eliminazione collezioni.
  • GET /health e GET /health/simple: health checks.

Le rotte sono protette da JWT eccetto alcuni endpoint pubblici (es. /health, /api/qdrant/*, queue monitor). Il middleware valida i token e scarta richieste non autorizzate.

Socket events​

  • create_thread → { agentId, type } → thread_created.
  • chat_message → messaggio e configurazione → stream typing/chat_response_*.
  • load_thread_messages → restituisce lo storico dal checkpointer.

Autenticazione via io.use(validateToken) con JWT (companyId nel payload). Ogni socket riceve socketId usato per arricchire i metadati (IP/domino) salvati su Laravel.

Configurazione​

  • langgraph.json definisce il grafo agent (./src/index.ts:app) e .env richiesto.
  • Variabili chiave: OPENAI_API_KEY, JWT_SECRET, WORKER_URL, LARAVEL_APP_URL, QDRANT_URL, QDRANT_API_KEY, DB_URI, ENABLE_CHECKPOINTER.
  • Avvio sviluppo: pnpm dev (porta interna 3000, log in logs/).

Strumenti (Tools)​

Caricati dinamicamente da src/agentTools/index.ts:

  • Documenti: searchDocumentsTool.
  • E‑commerce: semanticProductSearchTool, productWebSearchTool (render HTML card), categorie/attributi/termini, storePaymentsMethodsTool.

Sicurezza e validazione​

  • Validazione schema request con Zod (utils/validation.ts), errori coerenti e gestore errori globale.
  • Log strutturati con Winston (utils/logger.ts).
  • Limiti upload: 1GB per file, MIME type consentiti, cartella uploads/ creata al boot.

Note operative​

  • Il Worker Hatchet gira separatamente e gestisce le code; questo server delega via HTTP a WORKER_URL.
  • Lo stato conversazioni è persistito se ENABLE_CHECKPOINTER=true e DB_URI è configurato (PostgreSQL).

Flusso Documenti & RAG​

  • Upload file/URL → Task al Worker → estrazione testo + embedding → inserimento in Qdrant.
  • Il tool searchDocuments interroga Qdrant con l’embedding della query e restituisce passaggi pertinenti.
  • Per i prodotti: similarità su Qdrant e (se configurato) reranking con Jina per migliorare la rilevanza.

Flusso Prodotti & Card​

  • productSemanticSearch recupera gli ID dei prodotti candidati dalla collezione Qdrant.
  • productWebSearch interroga WooCommerce, adatta i dati e genera card HTML standardizzate pronte all’uso.

Osservabilità​

  • Health: endpoint /health (dettagliato) e /health/simple (sintetico).
  • Monitor coda: pagina /queue/monitor per visualizzare lo stato dei task.
  • Log: file e console tramite Winston con livello configurabile (LOG_LEVEL).