Come creare uno strumento (Beta)

Funzionalità beta. La creazione di strumenti completamente personalizzati da zero è in versione open beta ed è disponibile per tutti gli account Customer Agent: non è richiesta alcuna iscrizione. Troverai la pagina Strumenti in Customer Agent. La funzionalità è ancora in fase di espansione e potrebbe cambiare.

Cosa imparerai

Come connettere Customer Agent a qualsiasi endpoint HTTP utilizzando uno strumento completamente personalizzato, scrivere una descrizione dello strumento che Customer Agent utilizzerà effettivamente e testare il tuo strumento prima di collegarlo a un'abilità.

Prima di iniziare

Avrai bisogno di:

• Abilitato a Customer Agent
• Un endpoint HTTP a cui vuoi che Customer Agent chiami, uno che non richiede credenziali segrete (Chiavi API, token del portatore, ecc.) a cui accedere oggi (presto disponibili endpoint autenticati, vedi l'avviso qui sotto)
• Un'abilità a cui collegare lo strumento: o un'abilità in dotazione o un'abilità completamente personalizzata che hai creato

Se non hai ancora impostato una competenza, creane una prima. Gli strumenti non fanno niente di per sé: devono essere legati a un'abilità.

Attenzione: presto arriverà un sistema di archiviazione sicuro per Chiavi API e altri segreti. Finché non sarà disponibile, non inserire Chiavi API, token del portatore o altre credenziali sensibili in strumenti completamente personalizzati: la configurazione degli strumenti non è ancora un luogo sicuro in cui archiviarli. Per ora, usa solo gli strumenti con endpoint sicuri da chiamare senza autenticazione segreta (ad esempio, endpoint interni dietro l'elenco degli indirizzi IP consentiti o endpoint che accettano identificatori non sensibili). È in arrivo l'assistenza per gli endpoint autenticati.

Cos'è uno strumento completamente personalizzato

Uno strumento completamente personalizzato è una richiesta HTTP che Customer Agent può effettuare durante una conversazione. La creazione di strumenti completamente personalizzati è in versione open beta ed è disponibile per tutti gli account Customer Agent. Usane uno quando gli strumenti forniti da Customer Agent non soddisfano le tue esigenze: ad esempio, cercare un ordine nel tuo sistema di gestione degli ordini anziché in quello di Shopify, controllare l'inventario in un magazzino personalizzato o creare un ticket in un helpdesk con cui Klaviyo non effettua l'integrazione nativa.

Per il concetto di base, vedere l'articolo Informazioni sugli strumenti di Customer Agent.

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

Vai su Customer Agent > Strumenti, quindi fai clic su Crea strumento.

2. Assegna un nome e descrivi lo strumento

• Nome — un identificatore breve come "Ottieni l'inventario" o "Crea un 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: GET, POST, PUT, DELETE o PATCH.
• URL — URL endpoint completo. Puoi includere segnaposto per i valori dinamici (vedi il passaggio 5).
• Intestazioni: tutte le intestazioni richieste dal tuo endpoint, tra cui Content-Type e intestazioni di autenticazione.

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

Fornisci un corpo JSON. Utilizza i segnaposto per i valori che Customer Agent deve compilare in fase di esecuzione.

Corpo dell'esempio:

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

5. Usa i segnaposto per i valori dinamici

Customer Agent può compilare i valori in fase di esecuzione utilizzando i segnaposto. Segnaposto comuni:

• {{profile_id}} - L'ID del profilo Klaviyo del cliente nella conversazione
• {{conversation_id}} — L'ID della conversazione attuale
• Qualsiasi parametro definito nello schema di input (ad esempio {{product_sku}}, {{order_id}})

I segnaposto funzionano nell'URL, nelle intestazioni e nel corpo.

6. Autenticazione

L'assistenza per gli endpoint autenticati sarà presto disponibile. Nel frattempo, non inserire Chiavi API, token del portatore o altri segreti in uno strumento completamente personalizzato. Usa solo endpoint sicuri per le chiamate senza credenziali segrete, ad esempio endpoint interni protetti da elenco di indirizzi IP consentiti o endpoint pubblici che accettano identificatori non sensibili.

L'archiviazione sicura e segreta è in arrivo e sbloccherà gli endpoint autenticati.

7. Testa lo strumento

Fai clic su Strumento di prova. Fornisci valori campione per qualsiasi parametro di input. Controlla che:

• La risposta arriva correttamente
• Il formato di risposta è quello che Customer Agent si aspetta
• Tutti i casi di errore vengono gestiti

8. Salva e collega un'abilità

Clicca su Salva. Per fare in modo che Customer Agent utilizzi davvero lo strumento, apri l'abilità che desideri utilizzarlo e aggiungi lo strumento lì.

Come scrivere una buona descrizione dello strumento

La descrizione è il campo più importante. Customer Agent sceglie quale strumento utilizzare in base alla descrizione, non al nome. Descrizioni del Buono:

• 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

• Non utilizzare strumenti completamente personalizzati per endpoint che richiedono ancora credenziali segrete. L'assistenza per gli endpoint autenticati sarà presto disponibile. Finché non spedisce, usa solo endpoint sicuri per chiamare senza autorizzazione segreta.
• Se possibile, utilizza IP allowlisting. Se il tuo endpoint è interno, limita l'accesso alle gamme di IP di Klaviyo invece di affidarti ai segreti.
• Scopri quali dati invii. Customer Agent trasferisce i dati dei clienti nello strumento in base a ciò che indicano le istruzioni sulle competenze. Controlla 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 utilizza mai lo strumento.
Probabile causa: la descrizione è troppo vaga o lo strumento non è collegato all'abilità che lo utilizzerebbe.
Correzione: riscrivi la descrizione per descrivere in modo specifico quando deve essere utilizzata. Verifica che lo strumento appaia nell'elenco degli strumenti dell'abilità.

Sintomo: lo strumento restituisce un errore durante il test.
Probabile causa: URL errato, corpo malformato o carico utile che il tuo endpoint non accetta.
Correzione: usa la funzionalità dello strumento Test per controllare la richiesta e la risposta grezze. Verifica l'URL e il formato del corpo dell'endpoint rispetto all'input previsto.

Sintomo: Customer Agent utilizza lo strumento ma supera parametri errati.
Probabile causa: i nomi dei segnaposto non corrispondono allo schema o le istruzioni sulle abilità non sono chiare su cosa passare.
Corretto: controlla che i nomi dei segnaposto corrispondano esattamente. Aggiorna le istruzioni di abilità per indicare in modo esplicito quando utilizzare lo strumento e quali parametri 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 utilizzato da più competenze?
Sì. Una volta creato, uno strumento può essere associato a un numero qualsiasi di competenze.

Quali metodi di autenticazione sono supportati?
L'assistenza per gli endpoint autenticati sarà presto disponibile. Per ora, usa endpoint che non richiedono credenziali segrete (endpoint interni con elenco di indirizzi IP consentiti o endpoint pubblici con identificatori non sensibili).

Cosa succede se il mio endpoint è inattivo o restituisce un errore?
La gestione degli errori per gli strumenti completamente personalizzati non è ancora stata creata. Se il tuo endpoint non va a buon fine, Customer Agent potrebbe produrre una risposta degradata o confusa. Finché non avrai risolto il problema delle spedizioni, usa solo gli endpoint su cui hai fiducia e controlla attentamente il comportamento degli strumenti.

Posso modificare uno strumento dopo averlo creato?
Sì. Puoi modificare il nome, la descrizione, la configurazione e le competenze associate in qualsiasi momento.

Posso creare una versione di uno strumento?
La versione non è ancora supportata. Le modifiche apportate a uno strumento vengono applicate immediatamente a tutte le abilità che lo utilizzano.

Additional resources