Come creare uno strumento

Cosa imparerai

Come collegare Customer Agent a un endpoint HTTP usando uno strumento completamente personalizzato, scrivere una descrizione dello strumento che Customer Agent userà davvero e testare lo strumento prima di collegarlo a una skill.

Prima di iniziare

Avrai bisogno di:

• Abilitato a Customer Agent
• Un endpoint HTTP raggiungibile tramite un nome host pubblico. Gli indirizzi di rete privata, localhost e gli URL che usano un indirizzo IP invece di un nome host non sono supportati. Se l’endpoint richiede una chiave API o un token, la memorizzerai come segreto (vedi i passaggi 1 e 6).
• Un'abilità con istruzioni modificabili per collegare lo strumento a

Puoi creare e testare lo strumento prima di collegarlo a una skill. Per usarlo nelle conversazioni, aggiungilo alle istruzioni della skill. Se ti serve una nuova skill, vedi Come creare una skill.

Cos'è uno strumento completamente personalizzato

Uno strumento completamente personalizzato è una richiesta HTTP che Customer Agent può effettuare durante una conversazione. Usane uno quando gli strumenti inclusi con Customer Agent non coprono ciò di cui hai bisogno, ad esempio per cercare un ordine nel tuo sistema di gestione degli ordini invece che in Shopify, controllare le scorte in un sistema di magazzino personalizzato o creare un ticket in un helpdesk con cui Klaviyo non si integra nativamente.

Per il concetto alla base, consulta Strumenti: panoramica.

Quando creare uno strumento completamente personalizzato

Raggiungi uno strumento completamente personalizzato quando:

• Hai bisogno di dati in tempo reale da un sistema con cui Klaviyo non si integra
• Vuoi che Customer Agent intraprenda un'azione in un sistema esterno (annullare un abbonamento nel tuo sistema proprietario, creare un ticket, aggiornare un record)
• Uno strumento esistente non funziona: ad esempio, per gli ordini puoi utilizzare un OMS personalizzato invece di un Shopify

Se le informazioni non cambiano spesso e sono le stesse per ogni cliente, aggiungile come contenuto. Gli strumenti servono per gestire azioni e dati dinamici per ogni cliente.

Introduci l'argomento

1. Apri la pagina Strumenti personalizzati

1. Vai a Customer Agent > Connettori, quindi apri la scheda Personalizzato.
2. Se il tuo endpoint richiede una credenziale, vai a Segreti e fai clic su Aggiungi segreto. Inserisci un Nome e un Valore del segreto, poi fai clic su Aggiungi segreto. Salta questo passaggio se il segreto è già salvato o se l’endpoint non ne richiede uno.
3. Fai clic su Crea strumento.

2. Assegna un nome e descrivi lo strumento

• Nome dello strumento — Un breve identificativo come “Recupera inventario” o “Crea ticket di reso”.
• Descrizione — Linguaggio naturale che spiega cosa fa lo strumento e quando usarlo. Customer Agent legge questa descrizione per decidere se utilizzare lo strumento per una determinata richiesta. Sii specifico.

Un buon esempio di descrizione:

Recupera il conteggio delle scorte in tempo reale per un determinato SKU del prodotto dal sistema del magazzino. Da utilizzare quando un acquirente chiede se un prodotto specifico è disponibile.

Un esempio di descrizione vaga (evita):

Ottiene informazioni sul prodotto.

3. Configura la richiesta HTTP

• Metodo HTTP — GET, POST, PUT, DELETE o PATCH.
• Modello URL — l’URL completo dell’endpoint. Puoi includere segnaposto per valori dinamici (vedi il passaggio 5).
• Intestazioni: tutte le intestazioni richieste dal tuo endpoint, tra cui Content-Type e intestazioni di autenticazione.
• Parametri di query — Se il tuo endpoint si aspetta valori nella stringa di query, inserisci qui i loro nomi e valori. Puoi usare dei segnaposto per i valori (vedi il passaggio 5).

4. Configura il corpo della richiesta (per POST, PUT, PATCH)

In Modello del corpo, fornisci un oggetto JSON. Usa segnaposto per i valori che Customer Agent deve compilare in fase di esecuzione.

Corpo dell'esempio:

{
  "customer_id": "{{profile_id}}",
  "sku": "{{product_sku}}"
}

5. Definisci le variabili per i valori dinamici

Ogni segnaposto deve avere una variabile corrispondente in Variabili. Per l’esempio di corpo qui sopra:

1. Fai clic su Aggiungi variabili e inserisci profile_id come Nome variabile. Imposta Origine su Profilo Klaviyo e Proprietà Klaviyo su ID Klaviyo. Questo fornisce l’ID del profilo Klaviyo dell’acquirente autenticato.
2. Aggiungi un’altra variabile denominata product_sku. Imposta Origine su Variabile dinamica, scegli Stringa come Tipo e descrivi lo SKU che Customer Agent deve fornire in Descrizione. Seleziona Obbligatorio se l’endpoint lo richiede.

Ripeti l'operazione per altri valori richiesti dal tuo endpoint, come order_id. I nomi delle variabili devono corrispondere esattamente ai rispettivi segnaposto. Una variabile denominata conversation_id non viene compilata automaticamente con l'ID della conversazione corrente.

Usa le variabili come segnaposto, ad esempio {{profile_id}} e {{product_sku}}, nell’URL, nelle intestazioni, nei parametri di query o nel corpo. Gli strumenti che usano le variabili di profilo Klaviyo richiedono un acquirente autenticato; la mancanza di un valore del profilo obbligatorio impedisce l’esecuzione della richiesta.

6. Autenticazione

Se il tuo endpoint richiede una chiave API, un token bearer o un'altra credenziale, salvala come segreto. I segreti sono crittografati, i loro valori non vengono mai mostrati a Customer Agent e non possono più essere visualizzati dopo che li hai salvati.

1. Nel tuo strumento, in Variabili, fai clic su Aggiungi variabili. Assegna un nome alla variabile (ad esempio, api_key), imposta Origine su Segreto e scegli il segreto che hai salvato.
2. Fai riferimento alla variabile ovunque l'endpoint si aspetta le credenziali: un'intestazione, l'URL, un parametro di query o il corpo. Ad esempio, aggiungi un'intestazione denominata Authorization con il valore Bearer {{api_key}}.

Per ruotare una chiave, apri il menu della riga del segreto, fai clic su Aggiorna, inserisci il valore sostitutivo, quindi fai clic su Aggiorna. Ogni strumento che usa il segreto acquisisce il nuovo valore. La colonna Usato da mostra quali strumenti fanno riferimento a ogni segreto, quindi controllala prima di eliminarne uno.

7. Salva e testa lo strumento

Prima di salvare, controlla Timeout (secondi) e Numero massimo di tentativi in Impostazioni. Puoi impostare un limite di tempo complessivo di 1–10 secondi e 0–3 tentativi per errori temporanei. Se lo strumento modifica i dati, assicurati che il tuo endpoint sia in grado di gestire in sicurezza una richiesta ripetuta.

Fai clic su Salva per creare lo strumento. Lo strumento salvato si apre con una sezione Test.

I test inviano richieste reali al tuo endpoint e possono modificare i dati. Usa un profilo di test e record di test. Salva ed esegui test salva anche eventuali modifiche allo strumento, incluso uno strumento già usato dalle competenze attive.

In Test, inserisci valori di esempio per le variabili dinamiche. Seleziona un profilo di test in profilo se lo strumento utilizza variabili del profilo Klaviyo. Fai clic su Salva ed esegui il test.

Rivedi Risposta e verifica che:

• La risposta arriva correttamente
• La risposta contiene i dati necessari alla tua skill
• I casi di errore previsti restituiscono codici di stato e messaggi utili

8. Collega lo strumento a una competenza

1. Vai a Customer Agent > Skills e apri la skill per cui vuoi usare lo strumento. Se le sue istruzioni sono di sola lettura, crea una skill completamente personalizzata.
2. In Come rispondere, digita / nel punto in cui deve essere usato lo strumento e seleziona lo strumento dal menu. Spiega quando chiamarlo, quali valori fornire e cosa fare con il risultato o con un errore.
3. Quando le istruzioni sono pronte, fai clic su Pubblica per una skill in bozza o su Aggiorna per una skill attiva.

Come scrivere una buona descrizione dello strumento

Una descrizione chiara aiuta Customer Agent a decidere quando usare lo strumento. Le istruzioni della skill guidano anche quale strumento chiama e come usa il risultato. Descrizioni buone:

• Dire cosa fa lo strumento in una sola frase
• Di' quando usarlo in una sola frase
• Sono specifici sui dati restituiti o sull'azione intrapresa

Le descrizioni errate sono vaghe ("Ottiene le informazioni del cliente"), troppo generiche ("Gestisce tutto ciò che riguarda gli ordini") o indicano a Customer Agent come comportarsi anziché cosa fa lo strumento.

Considerazioni sulla sicurezza

• Memorizza le credenziali come segreti. Non incollare mai una chiave API o un token direttamente in un’intestazione, un URL o un corpo. Aggiungila come segreto e fai riferimento a essa con una variabile Secret (vedi passaggio 6).
• Usa, ove possibile, l’allowlisting degli IP. L’endpoint deve comunque essere raggiungibile tramite un nome host pubblico; gli indirizzi di rete privata e localhost sono bloccati. Usa l’allowlisting come ulteriore livello di protezione insieme all’autenticazione.
• Assicurati di sapere quali dati invii. La configurazione della richiesta e le origini delle variabili determinano quali valori vengono inviati all’endpoint. Le istruzioni della skill guidano i valori che Customer Agent fornisce per le variabili dinamiche. Verifica quali campi riceve il tuo endpoint.
• Limiti tariffari. Se il tuo endpoint ha dei limiti di tasso, assicurati che siano abbastanza alti da gestire il volume di conversazioni previsto.

Risoluzione dei problemi

Sintomo: Customer Agent non usa mai lo strumento.
Causa probabile: la descrizione è troppo vaga oppure lo strumento non è incluso nelle istruzioni pubblicate della competenza.
Soluzione: riscrivi la descrizione in modo che indichi chiaramente quando va usato. In Come rispondere, inserisci lo strumento usando / e spiega quando richiamarlo. Fai clic su Pubblica o Aggiorna per applicare le istruzioni.

Sintomo: lo strumento restituisce un errore durante il test.
Causa probabile: URL errato, corpo non valido, dati del profilo obbligatori mancanti o un payload che l’endpoint non accetta.
Correzione: in Test, rivedi Anteprima richiesta e Risposta. Verifica URL, header e corpo rispetto all’input previsto dal tuo endpoint. Se lo strumento utilizza variabili Profilo Klaviyo, seleziona un profilo di test con i valori obbligatori.

Sintomo: Customer Agent usa lo strumento ma passa parametri errati.
Causa probabile: una variabile ha l’origine o la Proprietà del profilo errata, oppure le istruzioni della skill non sono chiare su cosa passare.
Soluzione: controlla i nomi delle variabili, le origini e le Proprietà del profilo selezionate in Variabili. Aggiorna le descrizioni delle variabili e le istruzioni della skill in modo da esplicitare cosa fornire.

Sintomo: lo strumento è lento, causando ritardi nelle risposte.
Probabile causa: latenza Endpoint.
Correzione: ottimizza il tuo endpoint. Controlla se puoi inserire i risultati nella cache dal tuo lato.

Domande frequenti

Uno strumento può essere usato da più skill?
Sì. Una volta creato, uno strumento può essere usato da più skill. Inseriscilo nelle istruzioni modificabili di ogni skill e pubblica o aggiorna ogni skill.

Quali metodi di autenticazione sono supportati?
Qualsiasi metodo che invia una credenziale statica con la richiesta, ad esempio un token bearer o un’intestazione con chiave API. Archivia la credenziale come segreto e fai riferimento ad essa con una variabile Segreto (vedi il passaggio 6). I flussi che devono recuperare o aggiornare un token al momento della richiesta, ad esempio OAuth, non sono supportati negli strumenti completamente personalizzati.

Cosa succede se il mio endpoint non è disponibile o restituisce un errore?
Klaviyo segnala i malfunzionamenti dello strumento a Customer Agent. Gli errori temporanei possono essere ritentati entro i limiti di timeout e di tentativi dello strumento. Nelle istruzioni della skill, spiega come rispondere se lo strumento non riesce a completare la richiesta, ad esempio offrendo un passaggio di consegne. Usa endpoint affidabili e monitora attentamente il comportamento dello strumento.

Posso modificare uno strumento dopo averlo creato?
Sì. Apri lo strumento da Customer Agent > Connettori > Personalizzato, modificane il nome, la descrizione o la configurazione della richiesta, quindi fai clic su Salva. Aggiungi o rimuovi lo strumento nelle istruzioni di ogni competenza.

Posso creare versioni di uno strumento?
Il controllo delle versioni non è ancora supportato. Le modifiche salvate si applicano allo strumento condiviso utilizzato da ogni skill che lo fa riferimento. Salva ed esegui test salva anche le modifiche, quindi controlla quali skill attive usano lo strumento prima di modificarlo.

Risorse aggiuntive