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. Execus 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. Ogni sezione dei parametri (path, query, body) ha anche una vista JSON: puoi incollare lo JSON Schema pubblicato dal servizio invece di inserire i campi uno per uno.

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

   Cosa crea questa azione (facoltativo)

   Se lo strumento crea qualcosa nel tuo gestionale, scegli in «Cosa crea questa azione» che cosa produce un'esecuzione riuscita durante una chiamata (il valore predefinito è «Niente»). Prenotazione: la prenotazione compare nel calendario come copia di riferimento, che non occupa lo slot e non viene inviata a Google o Apple, e ricevi la notifica «Prenotazione presa al telefono»; data, ora, nome e telefono vengono letti dai parametri dello strumento (il telefono, se manca, è quello di chi chiama). Nuovo contatto: chi chiama viene salvato nei contatti. Ordine: conta solo nelle analytics. In tutti i casi l'esecuzione conta come risultato nelle analytics, e al salvataggio vengono ricontate anche le chiamate già fatte (senza creare prenotazioni o notifiche per il passato). La scelta compare come etichetta sulla scheda dello strumento. Disponibile solo per gli agenti vocali.

6. 6

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