Custom Tools

Casi d'uso

Configurazione

Campi

• Nome — un identificatore per la funzione (lettere, numeri, trattini bassi), ad es. get_order_status. L'AI vede questo nome.
• Descrizione — il campo più importante. Indica all'AI quando chiamare lo strumento. Sii esplicito: “Chiama questo ogni volta che il cliente menziona un numero d'ordine. Non chiedere alcuna verifica.”
• URL dell'endpoint — l'URL HTTPS pubblico che Asyntai chiamerà.
• Metodo HTTP — GET (di sola lettura, consigliato) o POST (può modificare i dati — vedi Sicurezza di seguito).
• Parametri — gli input che l'AI estrae dalla conversazione e invia. Ciascuno ha un nome, un tipo, una descrizione e un flag di obbligatorietà. Per GET vengono inviati come parametri della query string; per POST come corpo JSON.
• Header di autenticazione (opzionale) — un nome di header + valore inviato a ogni chiamata, ad es. X-API-Key. Usalo se il tuo endpoint richiede una chiave.

Esempio pratico: ricerca dello stato dell'ordine

Supponiamo che il tuo negozio esponga questo endpoint:

GET https://yourstore.com/api/order-status?order_number=10294

…che restituisce JSON come:

{
  "found": true,
  "status": "Accepted, preparing for shipment",
  "carrier": "DHL",
  "customer_message": "Your order has been accepted and is being prepared for shipment."
}

Configureresti uno strumento in questo modo:

• Nome: get_order_status
• Descrizione: “Cerca lo stato di un ordine di un cliente. Chiama questo immediatamente ogni volta che il cliente fornisce un numero d'ordine — non chiedere ulteriori verifiche. Usa il customer_message restituito nella tua risposta.”
• URL dell'endpoint: https://yourstore.com/api/order-status
• Metodo: GET
• Parametro: order_number (string, obbligatorio) — “Il numero d'ordine del cliente, tipicamente di 8+ cifre.”

Quando un cliente scrive “Com'è il mio ordine #10294?”, l'AI chiama get_order_status(order_number=10294), Asyntai richiede il tuo URL con ?order_number=10294 e l'AI risponde utilizzando la risposta.

Cosa riceve e cosa dovrebbe restituire il tuo endpoint

• Richiesta: un GET con i tuoi parametri nella query string, o un POST con un corpo JSON. Qualsiasi header di autenticazione configurato è incluso.
• Risposta: restituisci JSON (preferito) o testo semplice. Asyntai passa il corpo all'AI. Un campo che l'AI può citare direttamente — come customer_message — funziona bene.
• Non trovato / errori: restituisci un payload chiaro (ad esempio un oggetto JSON con found: false e un customer_message) affinché l'AI possa rispondere in modo veritiero invece di tirare a indovinare.

Testare il tuo strumento

Ogni strumento dispone di un pannello integrato Testa questo strumento nella pagina di configurazione, così puoi verificare che funzioni prima che qualsiasi cliente lo utilizzi — e senza inviare un messaggio tramite il bot.

1. Inserisci valori di esempio per i parametri dello strumento (ad es. un numero d'ordine reale).
2. Fai clic su Esegui test. Asyntai chiama il tuo endpoint esattamente come farebbe l'AI — stessa query string o corpo JSON, stesso header di autenticazione, stesso timeout di 5 secondi e stessi controlli di sicurezza.
3. Vedrai il risultato all'istante: un badge di successo/fallimento, lo stato HTTP, il tempo di risposta, l'URL esatto che abbiamo chiamato e la risposta grezza del tuo endpoint (formattata in modo leggibile se è JSON).

Questo funziona anche con le modifiche non salvate, così puoi regolare l'URL, i parametri o l'header di autenticazione e ripetere il test finché non restituisce ciò che ti aspetti.

Sicurezza — leggi questo

• Preferisci GET / sola lettura. Le ricerche (stato dell'ordine, disponibilità, tracciamento) sono sicure da esporre. GET è l'impostazione predefinita per questo motivo.
• POST richiede una conferma. Poiché POST può modificare i dati, uno strumento POST può essere salvato solo dopo aver spuntato una casella che conferma che sei l'unico responsabile della protezione e dell'autorizzazione delle richieste sul tuo endpoint. Non collegare mai rimborsi, cancellazioni, modifiche di password o movimenti di denaro a meno che il tuo endpoint non verifichi la richiesta in modo indipendente.
• Proteggiti dall'enumerazione. Se una chiave di ricerca è indovinabile (come numeri d'ordine sequenziali), richiedi un secondo fattore — ad es. il numero d'ordine e l'email associata all'ordine, e verifica che corrispondano — così un visitatore non può leggere i dati di altri clienti provando numeri.
• Non fidarti mai degli argomenti dell'AI. Convalida e autorizza ogni richiesta lato server come se provenisse da un aggressore anonimo — perché di fatto può esserlo.

Verificare le chiamate live

Una volta che il tuo strumento è attivo, ogni invocazione reale da una conversazione viene registrata. Per ogni chiamata registriamo il nome dello strumento, gli argomenti inviati dall'AI, l'URL esatto che abbiamo richiesto, lo stato HTTP, la risposta e la durata. Questo ti consente di confermare che uno strumento è stato attivato in una chat reale e di vedere cosa ha restituito il tuo endpoint, senza dover frugare nei log del tuo server. (Il pannello Testa questo strumento sopra serve per verificare tu stesso la configurazione; questo registro cattura ciò che accade durante le effettive conversazioni con i clienti.)

Limiti & protezioni

• Fino a 10 strumenti per sito web.
• Timeout di 5 secondi per chiamata; le risposte sono limitate a 10 KB.
• Gli endpoint devono essere URL http(s) pubblici. Gli indirizzi privati, di loopback e di rete interna sono bloccati.
• Disponibile nei piani Standard e Pro.
• Fatturazione: ogni chiamata di strumento conta come un messaggio aggiuntivo del tuo piano. Una risposta normale usa 1 messaggio; una risposta in cui l'IA chiama uno strumento ne usa 2 (la risposta più la chiamata di strumento), perché una chiamata di strumento richiede una richiesta IA aggiuntiva.
• Se una chiamata a uno strumento fallisce (timeout, errore, blocco), l'AI viene informata e risponde con garbo — non manderà in crash la conversazione.