External Tools

Comportamento / Collegamento / Riepilogo. Descrivi il risultato e quando l’assistente deve usare questa azione. Collega l’API del tuo servizio. Autenticazione e parametri si configurano nelle sezioni qui sotto. Gli esempi compilano nome e descrizione. Devi collegare il tuo servizio; nessuna integrazione viene attivata. Le sezioni in alto restano modificabili. La prova reale può produrre effetti nel servizio collegato. Il salvataggio non esegue il tool.

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 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"
 }
}