Strumento di Conversazione
Crea uno strumento che l'IA può utilizzare durante le conversazioni. L'IA decide quando chiamarlo in base al contesto.
Fai agire il tuo agente IA · costruisci il tuo primo Strumento
Quando Utilizzarlo
Utilizza questo trigger per estendere ciò che la tua IA può fare:
- Cerca prodotti nel tuo catalogo
- Controlla lo stato degli ordini nel tuo sistema
- Cerca dati dei clienti nel CRM
- Crea ticket di supporto in JIRA
- Prenota 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/come l'IA 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'IA deve raccogliere dall'utente:
| Campo | Descrizione |
|---|---|
| Nome Variabile | Nome interno (es. query, orderId) |
| Descrizione | Aiuta l'IA a capire cosa chiedere |
Le variabili diventano disponibili come {{variableName}} nel tuo flusso.
Come Funziona
- Definisci uno strumento con nome, descrizione e variabili
- L'IA apprende quando utilizzarlo dalla tua descrizione
- L'utente chiede qualcosa di correlato (es. "Trova un laptop")
- L'IA raccoglie le variabili richieste in modo conversazionale
- Il flusso viene eseguito con i dati raccolti
- Il risultato torna all'IA per la risposta finale
Nominare i Tuoi Strumenti: Perché È Importante
Quando il tuo assistente IA ha accesso a più strumenti, sceglie quale chiamare in base a soltanto tre 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 loro, l'IA sceglierà lo strumento sbagliato. Studi sul funzionamento delle chiamate LLM mostrano che migliorare la chiarezza della descrizione 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 — dal punto di vista dell'IA, tutti "cercano informazioni". Il nome e la descrizione sono l'unico modo per distinguerli.
Nome dello Strumento
Utilizza il modello domain_action_target in modo che il nome da solo distingua ciascun strumento:
| ❌ Vago | ✅ Chiaro |
|---|---|
Cerca | rgpd_legal_analysis |
search_docs | ecommerce_product_search |
Strumento 2 | support_ticket_lookup |
L'IA 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. Utilizza 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 di non conformità al RGPD.
Le parole all'interno di "Usa per" agiscono come trigger semantici. Quando il messaggio di un utente contiene "multa", "penale" o "rischio", l'IA lo abbina immediatamente a questo strumento.
Descrizioni delle Variabili
Una variabile descritta come "La query di ricerca" non dice nulla all'IA. Incollerà ogni volta la domanda grezza dell'utente. Una descrizione migliore guida l'IA 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'IA a riformulare invece di copiare l'intero messaggio dell'utente — risultando in ricerche più mirate e migliori risultati.
Evitare Conflitti tra Strumenti
Quando due strumenti possono rispondere alla stessa domanda, l'IA 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 attuabili |
Più specifica è ogni descrizione riguardo a ciò che lo strumento copre, meno ambiguità c'è. Non è necessario scrivere esclusioni esplicite — la precisione fa il lavoro.
Checklist Rapida
Prima di pubblicare un flusso con un trigger dello 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 dell'utente:
Utente: "Hai delle cuffie wireless?"
IA: chiama ecommerce_product_search con query="cuffie wireless"
IA: "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 effettivo"
Flusso:
- Trigger: Strumento di Conversazione
- Azione: Richiesta IA (genera titolo/descrizione)
- Parallelo: Genera descrizione + titolo
- Azione: JIRA Crea Problema
