Come creare uno strumento

Cosa sono gli strumenti personalizzati?

Gli "Strumenti" sono una funzionalità avanzata di Bookli che permette di estendere le capacità dell'intelligenza artificiale attraverso le Tool Calls. In breve, offrono a Bookli la possibilità di effettuare chiamate API a sistemi esterni in modo autonomo, sia durante una conversazione che al verificarsi di eventi specifici.

Queste chiamate possono essere innescate da:

• Trigger Conversazionali: Azioni o parole chiave specifiche che emergono durante il dialogo con l'utente (es. "vorrei controllare il mio ordine").

• Trigger CRM: Eventi predefiniti nel sistema che avvengono al di fuori della conversazione (es. al termine di una telefonata).

Esempio pratico: "Quando una chiamata viene contrassegnata come 'completata', esegui automaticamente questa chiamata API per aggiornare il nostro sistema di ticketing."

Questa guida ti accompagnerà passo dopo passo nella configurazione e nell'utilizzo degli strumenti personalizzati.

---

Struttura di uno Strumento

La creazione di uno strumento è suddivisa in due sezioni principali, che analizzeremo nel dettaglio:

1

Informazioni di Base

In questa sezione si definiscono gli aspetti che governano il modo in cui l'AI interagisce con lo strumento a livello conversazionale.

• Nome Personalizzato È un'etichetta interna che serve unicamente a te per identificare e salvare lo strumento. Non ha impatti funzionali ma è fondamentale per ritrovarlo facilmente quando dovrai assegnarlo a una Task.

• Discorso dello Strumento È la frase esatta che l'intelligenza artificiale pronuncerà prima di eseguire la chiamata API. Serve a informare l'utente di ciò che sta accadendo, rendendo l'interazione più naturale e trasparente, proprio come farebbe un operatore umano.

  Esempio: "Un attimo solo che controllo lo stato del suo ordine..."

• Descrizione dello Strumento Questa è l'istruzione fondamentale che fornisci all'AI per spiegarle quando e come utilizzare questo strumento. Sii il più preciso e dettagliato possibile, perché l'AI si baserà su questo testo per decidere se e come attivare la chiamata API.

  Esempio: "Utilizza questo strumento se l'utente desidera controllare lo stato di una spedizione. Per procedere, è indispensabile ottenere il numero di tracking dell'ordine."

2

Configurazione della API

Questa sezione è pensata per un pubblico con competenze tecniche (sviluppatori, marketing technologist o utenti "smanettoni"). Tuttavia, seguendo attentamente questa guida, anche gli utenti meno esperti possono configurare con successo le proprie chiamate API.

Qui si definiscono tutti i dettagli tecnici necessari affinché Bookli possa comunicare correttamente con il sistema esterno.

Metodo e Endpoint

• Metodo: Seleziona il metodo HTTP corretto per l'azione che desideri compiere (GET, POST, PUT, PATCH, DELETE).

• Endpoint: Inserisci l'URL completo (l'indirizzo) dell'API che vuoi interrogare.

Esempio: POST https://api.iltuoservizio.com/v1/orders

Autenticazione

Seleziona il tipo di autenticazione richiesto dalla tua API per garantire un accesso sicuro. Bookli supporta diverse modalità:

• Nessuna autenticazione

• Bearer Token

• API Key / Credentials

• OAuth 1.0 & OAuth 2.0

Le configurazioni specifiche per ogni metodo verranno trattate nelle sezioni dedicate di questo manuale.

Header

Gli header sono metadati inviati insieme alla richiesta, spesso utilizzati per specificare il formato dei dati o per l'autenticazione. Puoi trovare le informazioni sugli header richiesti all'interno della documentazione ufficiale dell'API che stai utilizzando.

Esempio di header comune (chiave-valore): Content-Type: application/json

Parametri di Query

I parametri sono i dati effettivi che invii con la tua chiamata API. Possono essere di due tipi:

1

Statici (Variabili di Bookli)

Sono valori che Bookli già conosce, come le informazioni del contatto o della chiamata in corso. Cliccando sul pulsante Variabili, puoi inserire dei segnaposto che verranno automaticamente sostituiti con i dati reali al momento della chiamata (es. nome del contatto, email, numero di telefono, nome dell'agente AI).

2

Da Estrarre (Dati dalla Conversazione)

Sono valori dinamici che Bookli deve ottenere direttamente dalla conversazione con l'utente. Per questi campi, è necessario istruire l'AI su come ottenerli.

Esempio:

• Tipo: Estrai

• Chiave: order_id

• Valore (Prompt per l'AI):

  "Estrai dalla conversazione oppure chiedi esplicitamente all'utente il suo numero di ordine."

Nota bene: Più sei preciso nel prompt, migliore sarà il risultato. Puoi aggiungere vincoli specifici per aiutare l'AI.

"Il codice dell'ordine è sempre un codice alfanumerico di 8 caratteri. Se l'utente fornisce un codice di lunghezza diversa, richiedilo di nuovo specificando il formato corretto."

Costruzione del Body della Richiesta (JSON)

‼️ ATTENZIONE Il prefisso $. che vedi precompilato nei campi dei parametri non deve mai essere eliminato. Bookli utilizza la sintassi JSONPath per costruire dinamicamente il corpo (body) della richiesta in formato JSON. Rimuovere $. impedirà il corretto funzionamento dello strumento.

Mentre compili i parametri, puoi vedere un'anteprima in tempo reale del JSON generato sulla destra. Vediamo alcuni esempi.

• Esempio 1: Chiave di primo livello

  • Parametro (JSONPath): $.order_id

  • JSON Risultante:

  {
    "order_id": "valore_estratto"
  }

• Esempio 2: Oggetto nidificato

  • Parametri (JSONPath): $.customer.name, $.customer.email

  • JSON Risultante:

  {
    "customer": {
      "name": "valore_estratto_o_statico",
      "email": "valore_estratto_o_statico"
    }
  }

• Esempio 3: Array di oggetti (es. un carrello)

  • Parametri (JSONPath): $.items[0].product_id, $.items[0].quantity

  • JSON Risultante:

  {
    "items": [
      {
        "product_id": "valore_estratto",
        "quantity": "valore_estratto"
      }
    ]
  }

Esempi di Chiamate API per Metodo

• GET (Ottenere dati): Per recuperare i dettagli di una risorsa esistente.

  • Uso: Leggere i dettagli di un ordine.

  • Endpoint: https://api.esempio.com/v1/orders/{orderId}

  • Parametri: Un parametro orderId estratto dalla conversazione.

• POST (Creare dati): Per creare una nuova risorsa.

  • Uso: Inserire un nuovo ordine nel sistema.

  • Endpoint: https://api.esempio.com/v1/orders

  • Parametri: $.product_id, $.quantity, $.customer_details.name.

• PUT / PATCH (Aggiornare dati): Per modificare una risorsa esistente. PUT sostituisce l'intera risorsa, PATCH la aggiorna parzialmente.

  • Uso: Modificare l'indirizzo di spedizione di un ordine.

  • Endpoint: https://api.esempio.com/v1/orders/{orderId}

  • Parametri: $.shipping_address.street, $.shipping_address.city.

• DELETE (Eliminare dati): Per cancellare una risorsa.

  • Uso: Annullare un ordine.

  • Endpoint: https://api.esempio.com/v1/orders/{orderId}

Variabili di Risposta

La risposta (response) di un'API spesso contiene molte più informazioni di quelle necessarie, incluse note interne o dati sensibili. Le Variabili di Risposta sono un potente filtro che permette a Bookli di isolare e salvare solo i dati pertinenti dalla risposta ricevuta.

Questo è fondamentale per due motivi principali:

1. Sicurezza: Impedisce che informazioni sensibili (es. note private, margini di profitto) vengano lette dall'AI o, peggio, comunicate all'utente finale.

2. Efficienza: Fornisce all'AI solo il dato esatto che le serve per formulare la risposta corretta, senza informazioni superflue.

Esempio Pratico

Immaginiamo che, dopo aver chiesto lo stato di un ordine, l'API risponda con il seguente JSON:

{
  "order": {
    "id": "XYZ-123",
    "date": "2024-10-26T10:00:00Z",
    "status": "In preparazione",
    "total_amount": 99.90,
    "currency": "EUR",
    "customer_id": "CUST-007",
    "internal_data": {
      "profit_margin": 0.23,
      "private_notes": "Cliente VIP, aggiungere omaggio al pacco."
    },
    "shipping_details": {
      "carrier": "Express Courier",
      "tracking_code": "TCK987654321"
    }
  }
}

A noi interessa comunicare all'utente solo lo status. Per farlo, creiamo una Variabile di Risposta:

• Nome Variabile: stato_ordine (un nome personalizzato che potrai riutilizzare in Bookli).

• Path della Risposta (JSONPath): $.order.status

In questo modo, Bookli ignorerà tutti gli altri dati e salverà unicamente il valore "In preparazione" nella variabile stato_ordine, pronta per essere utilizzata nella conversazione.