External Tools

Gli External Tools sono webhook HTTP che configuri tu: l'agente vocale li chiama in tempo reale per recuperare dati o eseguire azioni nel tuo sistema (CRM, gestionale, automazioni custom).

Cosa sono

Un External Tool è una funzione che vive sul tuo server. yourang.ai la registra come strumento disponibile per l'agente AI: quando il modello capisce che serve quell'azione (es. cercare un cliente nel CRM, controllare disponibilità di una stanza), invia una richiesta HTTP all'URL che hai configurato.

Come configurarli

1. 1

   Apri il pannello strumenti dell'agente

   Vai su /ai-agents → seleziona l'agente → tab Strumenti → External tools.

2. 2

   Definisci nome e descrizione

   Il nome interno (tool_name) è un identificatore tecnico (es. lookup_customer). La descrizione spiega all'AI quando usare lo strumento: deve essere chiara, concreta, focalizzata sull'intento utente.

3. 3

   Imposta il webhook

   URL HTTPS che riceverà le chiamate, metodo (GET/POST/PUT), schema dei parametri (JSON Schema) che l'AI passerà al payload.

4. 4

   Configura l'autenticazione

   Nessuna, Bearer token, API key in header, Basic auth o header personalizzati multipli. Le credenziali vengono cifrate at-rest.

5. 5

   Testa con una chiamata di prova

   Attiva l'agente in playground e chiedi qualcosa che dovrebbe attivare il tool. Il log della chiamata mostra request, response e tempi.

Autenticazione

None

Endpoint pubblico, niente header. Sconsigliato in produzione.

API key

Inviata in header HTTP scelto (es. X-API-Key).

Bearer

Header Authorization: Bearer <token>.

Basic

Authorization: Basic <base64(user:pass)>.

Custom header

Uno o più header arbitrari (es. X-Tenant, X-Signature).

Quando usarli

• Lookup CRM. L'agente cerca un cliente per numero di telefono e personalizza la risposta con i suoi dati.
• Disponibilità gestionale. L'agente chiede al PMS hotel se ci sono camere libere in una data.
• Creazione ticket. L'agente registra un reclamo come ticket nel sistema di customer care.
• Aggiornamento ordine. L'agente cambia lo stato di un ordine già in carico nel tuo e-commerce.

Esempio di richiesta

{
 "phone": "+39 333 1234567",
 "call_id": "cl_abc123",
 "organization_id": "org_xyz"
}

# Risposta attesa (200 OK):
{
 "found": true,
 "customer": {
 "name": "Mario Rossi",
 "tier": "gold",
 "last_order_date": "2026-03-12"
 }
}