Strumento di Conversazione
Crea uno strumento che l'AI può utilizzare durante le conversazioni. L'AI decide quando chiamarlo in base al contesto.
Quando Utilizzarlo
Usa questo trigger per estendere ciò che la tua AI può fare:
- Cercare prodotti nel tuo catalogo
- Controllare lo stato degli ordini nel tuo sistema
- Cercare dati dei clienti nel CRM
- Creare ticket di supporto in JIRA
- Prenotare appuntamenti
- Qualsiasi capacità personalizzata
Configurazione
Impostazioni di Base
| Campo | Descrizione |
|---|---|
| Nome dello Strumento | Nome leggibile dall'uomo (mostrato nella Libreria dei Nod) |
| Descrizione | Spiega quando e come l'AI dovrebbe utilizzare questo strumento |
Targeting degli Utenti
Scegli chi può utilizzare questo strumento:
| Opzione | Descrizione |
|---|---|
| Tutti gli Utenti | Utenti anonimi + utenti connessi |
| Solo Utenti Connessi | Solo utenti registrati |
| Accesso Basato su Ruolo | Ruoli utente specifici |
Variabili dello Strumento
Definisci i parametri che l'AI deve raccogliere dall'utente:
| Campo | Descrizione |
|---|---|
| Nome Variabile | Nome interno (es. query, orderId) |
| Descrizione | Aiuta l'AI a capire cosa chiedere |
Le variabili diventano disponibili come {{variableName}} nel tuo flusso.
Come Funziona
- Definisci uno strumento con nome, descrizione e variabili
- L'AI apprende quando utilizzarlo dalla tua descrizione
- L'utente chiede qualcosa di correlato (es. "Trova un laptop")
- L'AI raccoglie le variabili richieste in modo conversazionale
- Il flusso viene eseguito con i dati raccolti
- Il risultato torna all'AI per la risposta finale
Nominare i Tuoi Strumenti: Perché È Importante
Quando il tuo assistente AI ha accesso a più strumenti, sceglie quale chiamare in base a tre sole cose: il nome dello strumento, la descrizione dello strumento e le descrizioni delle variabili. Non può vedere cosa c'è dentro il flusso — legge il testo e decide.
Se quei tre campi sono vaghi o troppo simili tra gli strumenti, l'AI sceglierà lo strumento sbagliato. Studi sull'invocazione delle funzioni LLM mostrano che migliorare la chiarezza della descrizione da sola può aumentare la selezione corretta dello strumento di 15–20 punti percentuali, senza cambiare il modello sottostante.
Questo è particolarmente critico quando hai diversi strumenti che cercano in diverse basi di conoscenza — dalla prospettiva dell'AI, tutti "cercano informazioni". Il nome e la descrizione sono l'unico modo in cui può distinguerli.
Nome dello Strumento
Usa il modello domain_action_target in modo che il nome da solo distingua ciascuno strumento:
| ❌ Vago | ✅ Chiaro |
|---|---|
Cerca | rgpd_legal_analysis |
search_docs | ecommerce_product_search |
Strumento 2 | support_ticket_lookup |
L'AI utilizza il nome come primo filtro prima di leggere la descrizione. Un nome chiaro le consente di fare una selezione immediata; un nome generico la costringe a indovinare.
Descrizione dello Strumento
La descrizione è la tua leva più potente. Usa questa formula:
[Cosa fa — 1 frase]
Usa per: [3–5 casi d'uso concreti con le parole che i tuoi utenti direbbero realmente]
❌ Male:
Cerca nella base di conoscenza informazioni.
✅ Bene:
Cerca sanzioni CNIL e giurisprudenza CJUE.
Usa per: trovare decisioni sanzionatorie per settore o tipo di violazione,
cercare importi delle multe, citare precedenti legali,
valutare il rischio finanziario della non conformità al RGPD.
Le parole all'interno di "Usa per" agiscono come trigger semantici. Quando il messaggio di un utente contiene "multa", "sanzione" o "rischio", l'AI lo abbina immediatamente a questo strumento.
Descrizioni delle Variabili
Una variabile descritta come "La query di ricerca" non dice nulla all'AI. Incollerà la domanda grezza dell'utente ogni volta. Una descrizione migliore guida l'AI a estrarre le parole chiave giuste prima di inviarle.
| ❌ Vago | ✅ Chiaro |
|---|---|
La query di ricerca | Query di ricerca: tipo di violazione, nome dell'azienda, settore, importo della multa o concetto legale |
Input utente | Tipo di documento richiesto: modello, modulo, clausola o contratto |
Questo spinge l'AI a riformulare invece di copiare l'intero messaggio dell'utente — risultando in ricerche più mirate e risultati migliori.
Evitare Conflitti tra Strumenti
Quando due strumenti possono rispondere alla stessa domanda, l'AI esita — e a volte sceglie casualmente. Ogni strumento deve coprire un territorio esclusivo.
La regola: se puoi pensare a una domanda dell'utente che potrebbe andare a entrambi gli strumenti, le tue descrizioni necessitano di maggiore precisione.
Esempio — 5 strumenti di conformità con confini chiari:
| Strumento | Copre | Non Copre |
|---|---|---|
compliance_legal_analysis | Articoli di legge, obblighi legali, diritti | Nessun consiglio pratico, nessun caso reale |
compliance_methodology | Guide passo-passo, procedure di audit, framework | Nessun testo legale, nessun modello |
compliance_document_templates | Modelli pronti all'uso, moduli, clausole contrattuali | Nessuna metodologia, nessuna analisi legale |
compliance_business_processes | Flussi di lavoro operativi, circuiti di approvazione | Nessun testo legale, solo processi interni |
compliance_operational_solutions | Soluzioni concrete, raccomandazioni tecniche | Nessuna teoria, solo soluzioni praticabili |
Maggiore è la specificità di ciascuna descrizione riguardo a ciò che lo strumento copre, minore è l'ambiguità. Non è necessario scrivere esclusioni esplicite — la precisione fa il lavoro.
Checklist Veloce
Prima di pubblicare un flusso con un trigger Strumento di Conversazione, verifica:
- Nome segue
domain_action_target— distinguibile senza leggere la descrizione - Descrizione inizia con cosa fa lo strumento in 1 frase
- Descrizione include "Usa per:" con 3–5 casi d'uso concreti
- Descrizioni delle variabili elencano i tipi di informazioni attese, non solo "la query"
- Nessuna sovrapposizione con il territorio di un altro strumento
- Testato con 2–3 domande ambigue nel pannello di Test per confermare il corretto instradamento
Esempio: Ricerca Prodotto
Configurazione dello Strumento:
- Nome:
ecommerce_product_search - Descrizione: Cerca nel catalogo prodotti per nome, categoria o caratteristica. Usa per: trovare un prodotto specifico, confrontare prodotti in una categoria, controllare se un prodotto esiste, cercare specifiche o prezzi di prodotto.
- Variabile:
query— "Nome del prodotto, categoria, caratteristica o fascia di prezzo da cercare"
Flusso:
- Trigger: Strumento di Conversazione
- Azione: Cerca nella Base di Conoscenza (
{{query}}) - Azione: Imposta Osservazione (restituisci risultati)
Conversazione con l'utente:
Utente: "Avete delle cuffie wireless?"
AI: chiama ecommerce_product_search con query="cuffie wireless"
AI: "Sì! Ho trovato 3 cuffie wireless. Le Sony WH-1000XM5 sono il nostro bestseller a €349..."
Esempio: Ticket JIRA
Configurazione dello Strumento:
- Nome:
support_create_jira_ticket - Descrizione: Crea un ticket di supporto JIRA dalla conversazione. Usa per: quando l'utente segnala un bug, richiede una funzionalità o ha bisogno di escalare un problema al team tecnico.
- Variabili:
title— "Breve riassunto del problema (1 frase)",description— "Descrizione dettagliata inclusi i passaggi per riprodurre, comportamento atteso e comportamento reale"
Flusso:
- Trigger: Strumento di Conversazione
- Azione: Richiesta AI (genera titolo/descrizione)
- Parallelo: Genera descrizione + titolo
- Azione: Crea Problema JIRA
