Tool Feedback (messaggi intermedi)

Durante l'esecuzione dei tool LangGraph, l'agente invia messaggi di feedback brevi all'utente per comunicare cosa sta facendo (es. "Sto cercando i prodotti...").

Standardizzato con la PR #63 (marzo 2026) e aggiornato nei tool successivi.

Flusso

Parametro feedbackToUser

Ogni tool che interagisce con l'utente accetta un parametro feedbackToUser nello schema Zod:

/main/src/agentTools/documentSearchTool.ts

feedbackToUser: z
  .string()
  .describe('Very short feedback message in the user language, max 100 characters')

Regole per l'LLM

• Massimo 100 caratteri nel parametro feedbackToUser (l'LLM deve rispettare il limite)
• Il server tronca a 100 caratteri e aggiunge ... se superato (fino a 103 caratteri emessi)
• Nella stessa lingua del messaggio utente
• Descrivono l'azione in corso, non il nome del tool
• Esempi: "Sto cercando nei documenti...", "Cerco i prodotti..."

Emissione feedback

/main/src/agentTools/toolFeedback.ts

export async function emitToolFeedback(runnableConfig: unknown, feedback: string) {
  const config = runnableConfig as ToolFeedbackConfig | undefined
  const eventData = { feedback }
  if (typeof config?.writer === 'function') {
    await Promise.resolve(config.writer({ name: 'tool_feedback', data: eventData }))
    return
  }
  await dispatchCustomEvent('tool_feedback', eventData)
}

Truncation lato server

Il socket server tronca i messaggi oltre 100 caratteri e aggiunge ... prima di inviarli al client (massimo 103 caratteri emessi):

/main/src/server/socketServer.ts

const feedback =
  feedbackData?.feedback && feedbackData.feedback.length > 100
    ? `${feedbackData.feedback.substring(0, 100)}...`
    : (feedbackData?.feedback ?? '')
socket.emit('tool_feedback', { feedback })

Tool che usano feedbackToUser

Tool	Azione comunicata
searchDocuments	Ricerca nei documenti knowledge-base
productWebSearch	Ricerca prodotti nel catalogo
semanticProductSearch	Ricerca semantica prodotti
categoryList	Elenco categorie
attributeList	Elenco attributi
attributeTerms	Termini attributo
storePaymentsMethods	Metodi di pagamento

Il tool requestContactForm non usa feedbackToUser — apre direttamente l'overlay del modulo contatto.

Evento Socket.IO client

socket.on('tool_feedback', ({ feedback }) => {
  // Mostra messaggio intermedio nella UI chat
  console.log('Agent is doing:', feedback)
})

Vedi anche: Chat e Streaming.