# 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: {% stepper %} {% step %} ### 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." > {% endstep %} {% step %} ### Configurazione della API {% hint style="info" %} 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. {% endhint %} 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: {% stepper %} {% step %} #### 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`). {% endstep %} {% step %} #### 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." > {% endstep %} > {% endstepper %} #### Costruzione del Body della Richiesta (JSON) {% hint style="warning" %} ‼️ 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. {% endhint %} 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: ```json { "order_id": "valore_estratto" } ``` * Esempio 2: Oggetto nidificato * Parametri (JSONPath): `$.customer.name`, `$.customer.email` * JSON Risultante: ```json { "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: ```json { "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}` {% endstep %} {% endstepper %} ### 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: ```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.