Contact Form HITL (LangGraph Interrupt)

Il Node Agent gestisce il modulo di contatto in chat tramite il tool requestContactForm e gli handler Socket.IO dedicati.

Tool requestContactForm

/main/src/agentTools/requestContactFormTool.ts

export const requestContactFormTool = tool(
  async (_input, runnable_config) => {
    const threadId = getConfigurable(runnable_config)?.thread_id
    if (!canOpenContactForm(threadId)) {
      return JSON.stringify({ status: 'throttled' })
    }
    const requestId = randomUUID()
    const rawResume = interrupt({ kind: 'contact_form', requestId })
    // ... parse resume (submitted / closed / timeout)
  },
  {
    name: 'requestContactForm',
    description: 'Open the in-chat contact form...',
    schema: z.object({}),
  }
)

Regole per l'agente

• Chiamare da solo in un turno (mai insieme ad altri tool)
• Usare quando l'utente chiede preventivo, offerta personalizzata, callback o vuole lasciare contatti
• Non usare searchDocuments al posto del contact form
• L'agente non vede mai i valori inviati, solo l'esito (submitted / closed / throttled)

Throttling

canOpenContactForm(threadId) impedisce aperture ripetute sullo stesso thread. Un flag inFlightContactFormThreads evita race condition durante resume.

Socket handlers

File: main/src/server/contactFormSocketHandlers.ts

Evento	Azione
Rilevamento interrupt	app.getState() → emit contact_form_request
contact_form_submitted	Command({ resume: { success: true, ... } })
contact_form_cancelled	Command({ resume: { success: false, reason: 'cancelled' } })
contact_form_heartbeat	Reset TTL manager (5 minuti)
Timeout TTL	Resume automatico con reason: 'timeout'

HMAC signing

shared util contactFormSigning.ts genera:

• openToken — firmato dal Node Agent, verificato da Laravel al submit
• receipt — firmato da Laravel, usato dal widget per confermare al Node Agent

Context push verso Laravel

Dopo il submit, il Node Agent invia in fire-and-forget:

• POST /api/embed/contact-form/context/{uuid} — recap LLM + transcript conversazione
• Autenticazione: JWT node (AuthenticateNodeJwt middleware)

Endpoint riepilogo conversazione

POST /conversations/summary

Genera un riepilogo della conversazione tramite LLM (gpt-4.1-mini), usato dalla dashboard admin.

Diagramma stati