Passa al contenuto principale

Agent e Worker Node

Questa sezione documenta l'architettura e l'implementazione dell'Agente LangGraph e del Worker Node che costituiscono il cuore del sistema di elaborazione intelligente della piattaforma Tidiko.

Architettura del Sistema​

Il sistema è composto da due componenti principali che lavorano in sinergia:

Agente LangGraph (node-agent)​

L'agente è il componente frontend che gestisce le interazioni con gli utenti e coordina le operazioni complesse. Utilizza il framework LangGraph per orchestrare flussi di lavoro intelligenti basati su AI.

Caratteristiche principali:

  • API REST per comunicazione con il frontend
  • Streaming in tempo reale per risposte immediate
  • Gestione conversazioni con memoria persistente
  • Ricerca prodotti intelligente con AI
  • Elaborazione documenti e RAG (Retrieval Augmented Generation)
  • Sistema di autenticazione e sicurezza

Worker Node (node-worker)​

Il worker è il motore di elaborazione che esegue le operazioni pesanti in background, garantendo performance ottimali e scalabilità.

Funzionalità principali:

  • Elaborazione URL e crawling web
  • Processamento documenti (PDF, Word, etc.)
  • Generazione embeddings per ricerca semantica
  • Elaborazione prodotti e cataloghi
  • Sistema di logging avanzato
  • Gestione code e task asincroni

Deploy Docker Unificato con Profiles​

I due progetti Node.js sono mantenuti nella stessa repository per facilitare il deploy Docker unificato. A partire dalla versione corrente, utilizziamo Docker Compose Profiles per gestire tutti gli ambienti con un singolo file di configurazione.

Vantaggi del Deploy Unificato con Profiles​

  1. Sincronizzazione delle versioni: Garantisce che agent e worker utilizzino sempre versioni compatibili delle dipendenze
  2. Gestione semplificata: Un singolo docker-compose.yml con profiles per tutti gli ambienti (dev, staging, prod)
  3. Comunicazione ottimizzata: I servizi possono comunicare tramite rete Docker interna
  4. Deploy atomico: Aggiornamenti coordinati senza disallineamenti tra componenti
  5. Monitoraggio centralizzato: Logs e metriche unificati per debugging e osservabilità
  6. Configurazione condivisa: Variabili d'ambiente e configurazioni comuni
  7. Nessuna duplicazione: Un solo file da manutenere invece di 3+ file separati
  8. Cambio ambiente istantaneo: Basta cambiare il profile per passare da dev a prod

Struttura del Deploy​

tidiko-node-agent/
├── main/                        # Agente LangGraph
│   ├── src/
│   ├── package.json
│   ├── Dockerfile               # Build produzione
│   └── Dockerfile.dev           # Build development
├── hatchet/                     # Worker Node
│   ├── src/
│   ├── package.json
│   ├── Dockerfile.worker        # Build produzione
│   └── Dockerfile.worker.dev    # Build development
├── docker-compose.yml           # Orchestrazione unificata con profiles
├── deploy.sh                    # Script helper Linux/Mac
├── deploy.ps1                   # Script helper Windows
├── env.dev.example              # Template config dev
├── env.staging.example          # Template config staging
└── env.prod.example             # Template config prod

Quick Start​

# 1. Copia configurazione ambiente
cp env.dev.example .env

# 2. Modifica .env con i tuoi valori

# 3. Avvia ambiente desiderato
./deploy.sh up dev      # Development
./deploy.sh up staging  # Staging
./deploy.sh up prod     # Production

# Windows PowerShell
.\deploy.ps1 up dev

Flusso di Lavoro​

  1. Frontend invia richieste all'Agente LangGraph
  2. Agente analizza la richiesta e crea task per il Worker
  3. Worker elabora i task in background
  4. Agente riceve i risultati e li formatta per l'utente
  5. Frontend presenta la risposta all'utente

Documentazione Dettagliata​

Tecnologie Utilizzate​

  • LangGraph: Orchestrazione di flussi AI
  • Node.js: Runtime JavaScript
  • TypeScript: Tipizzazione statica
  • Docker: Containerizzazione
  • Redis: Cache e gestione code
  • PostgreSQL: Database persistente
  • OpenAI: Modelli di linguaggio
  • Vector Store: Ricerca semantica

Questa architettura garantisce scalabilità, manutenibilità e performance ottimali per il sistema Tidiko.