API di Customer Agent (Beta)

Cosa imparerai

Cosa sono le API di Customer Agent, cosa fa ogni endpoint e come iniziare a chiamarle. Le API ti permettono di configurare il tuo Customer Agent, leggere cosa sta facendo nella produzione ed eseguirlo a livello di programmazione, direttamente su HTTP, insieme al resto dell'API pubblico di Klaviyo.

Nota: Le API Customer Agent sono in beta. Gli endpoint e gli schemi potrebbero cambiare prima della disponibilità generale. Le API beta non sono pensate per l'uso in produzione: per i dettagli, consulta la policy di Klaviyo su versioning e deprecazione.

Cosa ti permettono le API

Le API di Customer Agent coprono 4 attività:

1. Configura l'agente: leggi o aggiorna l'agente stesso, oltre alle sue competenze, ai suoi strumenti, alle sue fonti di conoscenza e ai suoi segreti.
2. Leggi le conversazioni di produzione: elenca e controlla le conversazioni di Customer Agent.
3. Report sulle prestazioni: volume di pull, tasso di risoluzione e metriche per competenza.
4. Esegui l'agente per un turno: invia un turno di conversazione e recupera la risposta dell'agente. Questo è il primitivo headless — utile per incorporare l'agente nella tua superficie.

Poiché questi quattro compiti si trovano tutti dietro un’unica API, puoi collegarli in un ciclo di addestramento continuo: estrarre ciò che è successo, diagnosticare cosa ha funzionato e cosa no, poi distribuire di nuovo le modifiche di configurazione. Con un’integrazione API configurata in modo sicuro o una connessione MCP, un assistente AI come Claude o ChatGPT può aiutarti a leggere le conversazioni, individuare schemi nei fallimenti e proporre modifiche alle tue competenze, ai tuoi strumenti, alle tue conoscenze e alle tue linee guida.

Autenticazione e accesso

Usa una chiave API privata di Klaviyo con l'ambito agents per chiamare questi endpoint. Customer Agent deve essere già abilitato per il tuo account.

Quando crei la chiave, scegli il livello di accesso per l'ambito agents:

Scegli di sola lettura se la tua integrazione deve osservare solo l'agente (ad esempio, un pannello di controllo di reportistica). Scegli lettura/scrittura se deve configurare l'agente o eseguire i turni di conversazione.

1. Vai su Impostazioni > chiavi API e fai clic su Crea chiave API privata.
2. Inserisci un nome per la chiave API privata e seleziona chiave personalizzata.
3. Nella riga Agents, seleziona Read Access o Full Access per la tua integrazione, utilizzando la tabella sopra.
4. Fai clic su Crea, quindi fai clic sull’icona di copia e conserva la chiave in modo sicuro. Non puoi visualizzare di nuovo la chiave dopo aver lasciato la pagina di conferma.

Per maggiori dettagli, vedi come creare o clonare una chiave API privata.

Invia richieste API dal tuo server a https://a.klaviyo.com e includi questa intestazione di autorizzazione. Tieni la chiave privata fuori dal codice del browser e dalle app rivolte ai clienti:

Authorization: Klaviyo-API-Key your-private-api-key

Ogni richiesta deve includere anche l'intestazione della revisione beta:

revision: 2026-10-15.pre

Senza l'intestazione della revisione beta, la richiesta sarà respinta.

Limiti tariffari

I limiti di frequenza dipendono dal gruppo di endpoint:

• Agente, competenze, strumenti, conoscenze, segreti e risposte: limite di burst di 10 richieste al secondo e limite stabile di 150 richieste al minuto.
• Conversazioni, messaggi delle conversazioni e report: limite burst di 3 richieste al secondo e limite steady di 60 richieste al minuto.

Formato della richiesta

Utilizza le convenzioni di richiesta JSON:API di Klaviyo, con un formato separato per i caricamenti di file:

• Tipo di contenuto: application/vnd.api+json per richieste JSON. Usa multipart/form-data per POST /api/agent-knowledge-files.
• Le raccolte con paginazione usano page[cursor] e page[size] (valore predefinito 50, max 100, solo in avanti). Segui links.next finché non è vuoto per recuperare le pagine rimanenti.
• Il filtraggio utilizza i campi e gli operatori supportati elencati nel riferimento di ciascun endpoint. L’ordine di ordinamento dipende dall’endpoint: le conversazioni sono dalla più recente alla meno recente, i messaggi dalla meno recente alla più recente e le competenze e gli strumenti sono ordinati per ID.

Endpoint

Agente

Esiste al massimo 1 Customer Agent per azienda. Chiama GET /api/customer-agents per trovare il suo ID, poi usa quell’ID nell’URL GET o PATCH. L’elenco è vuoto se Customer Agent non è abilitato per l’account.

Competenze degli agenti

Puoi leggere skill predefinite e personalizzate. Solo le skill personalizzate possono essere aggiornate o eliminate. Imposta status di una skill personalizzata su draft per metterla in staging o sospenderla, oppure su live per attivarla.

Strumenti dell’agente

Solo gli strumenti personalizzati possono essere aggiornati o eliminati. Dopo aver creato uno strumento HTTP esterno, collegalo a un’abilità personalizzata tramite la relazione agent-tools dell’abilità. Uno strumento non è disponibile per quell’abilità finché non viene collegato.

Conoscenze dell’agente

Crea snippet di testo, pagine web, coppie Q&A o cartelle impostando source.source_type su snippet, webpage, qa o folder. Per aggiungere un file, usa l’endpoint separato per il caricamento dei file.

Segreti dell’agente

Segreti crittografati utilizzati dagli strumenti personalizzati. L'endpoint dell'elenco restituisce solo metadati sicuri: il valore segreto non viene mai restituito.

Conversazioni

Leggi le conversazioni che l’agente ha avuto con gli acquirenti o crea una conversazione da eseguire tramite l’API. Una conversazione può estendersi su molti messaggi per un lungo periodo. L’elenco può includere conversazioni live e di anteprima; usa filter=equals(mode,"live") per limitarlo alle conversazioni live.

Report

Metriche aggregate, con ambito limitato all’azienda richiedente. Entrambi i report di seguito sono endpoint POST: passa i parametri del report nel body. Richiedono agents:read, quindi una chiave di sola lettura può eseguirli.

Esegui l'agente

Si tratta dell'integrazione primitiva di Customer Agent nella tua superficie (la tua app, il tuo centro assistenza, un pannello di assistenza creato dai partner).

Crea una conversazione aperta con POST /api/customer-agent-conversations prima di eseguire un turn. L’endpoint di risposta accetta solo conversazioni create tramite l’API. Una conversazione chiusa, o già instradata al tuo team, non può accettare altre risposte.

Cosa richiede ancora Klaviyo UI

Alcuni passaggi di configurazione non sono ancora presenti nell'API:

• Configurazione del canale (web chat, e-mail, SMS, WhatsApp): la configurazione del canale si basa sulle impostazioni di Piattaforma Klaviyo.
• Attivazione su ogni canale: l'interruttore di accensione/spegnimento per canale rimane nell'interfaccia utente.
• Selezione di Helpdesk — in Customer Agent, apri un canale in Canali e configura la sezione Handoff. Per i dettagli, vedi Gestire le impostazioni di Customer Agent.

Flussi di lavoro tipici

Configura una volta, quindi mantieni

1. Crea una chiave API privata con l’ambito agents e accesso in lettura/scrittura in Klaviyo.
2. Recupera lo stato attuale — GET /api/customer-agents per trovare l’ID dell’agente, quindi recupera l’agente e gli elenchi di competenze, strumenti e conoscenze. Segui i link di paginazione per leggere tutte le pagine.
3. Apporta modifiche — crea o aggiorna competenze personalizzate, strumenti, knowledge e segreti in base alle tue esigenze. Associa i nuovi strumenti alle competenze che li usano e imposta lo stato delle competenze personalizzate su: live quando sei pronto ad attivarli.
4. Controlla la produzione: elenca le conversazioni recenti e recupera un report sui valori per vedere come sta andando l'agente.
5. Itera.

Forma il tuo agente in un ciclo

Le API sono progettate per chiudere il cerchio tra ciò che il tuo agente ha fatto nella produzione e come è configurato. Un ciclo tipico:

1. Recupera conversazioni recenti — ESEGUI GET delle conversazioni filtrate per created_at e status, aggiungendo equals(mode,"live") al filtro per le conversazioni di produzione. Recupera i customer-agent-messages di ogni conversazione e segui links.next per leggere ogni pagina.
2. Diagnostica: per ogni conversazione, classificala come riuscita o non riuscita. Cerca dei modelli: le escalation sono raggruppate attorno a un argomento? Certe competenze vengono instradate quando non dovrebbero? All'agente mancano le conoscenze di cui ha bisogno?
3. Metriche pull: i valori riportano il volume e il tasso di risoluzione, più i valori delle abilità riportano le suddivisioni per competenza. Conferma i pattern conservati in forma aggregata.
4. Proponi modifiche: in base alle tendenze di errore, decidi cosa cambiare: modifica le istruzioni di un'abilità, aggiungi uno snippet di conoscenza, crea un nuovo strumento personalizzato, stringi una regola di tono, aggiungi un trigger di escalation.
5. Applica i cambiamenti: individua le competenze interessate, pubblica nuove fonti di conoscenza, ecc.
6. Loop Ripeti la procedura rispetto alla finestra di conversazioni successiva.

Puoi usare un assistente AI come Claude, ChatGPT o Cursor per estrarre conversazioni, individuare lacune, proporre modifiche specifiche e applicare i cambiamenti con la tua approvazione. Collegalo tramite il server MCP di Klaviyo o tramite la tua integrazione API e conserva le chiavi API private in una configurazione sicura anziché nei prompt. Il server MCP supporta molte di queste attività, ma la creazione o l'aggiornamento dei segreti e il caricamento dei file di conoscenza richiedono chiamate API dirette.

Incorpora l'agente nella tua superficie

Usa mode: preview per fare test senza fatturazione o metriche di produzione. mode: live serve per le interazioni reali con gli acquirenti e viene conteggiato ai fini della fatturazione e delle metriche di produzione. L’avviso sull’utilizzo beta riportato sopra è ancora valido.

1. Crea una chiave con l'ambito agenti (lettura/scrittura).
2. Crea una conversazione — dal tuo server, invia una richiesta POST a /api/customer-agent-conversations con mode scelto. Salva l’ID conversazione restituito.
3. Apri una conversazione nella tua interfaccia utente: raccogli il contributo dell'acquirente.
4. Esegui un turno — dal tuo server, invia una POST a /api/customer-agent-responses con mode, messages e l’ID salvato in data.relationships.conversation.data.id. Usa il tipo di relazione customer-agent-conversation. Includi la cronologia della conversazione in messages, terminando con l’ultimo messaggio dell’acquirente con role: user.
5. Rendering della risposta — elabora gli eventi restituiti in ordine e visualizza i messaggi dell’agente ed eventuali dati strutturati supportati nella tua interfaccia. Gestisci gli eventi di handoff nella tua integrazione. L’API restituisce gli eventi insieme senza streaming e non li fornisce tramite un canale.
6. Ripeti per ogni turno utilizzando lo stesso ID conversazione e la stessa modalità mentre la conversazione è aperta. Dopo un passaggio di consegne brusco o silenzioso, interrompi le richieste di risposta all'agente e instrada il cliente al tuo team di assistenza.

Domande frequenti

C'è un server MCP?

Sì. Il server MCP di Klaviyo ospitato da remoto include strumenti Customer Agent per competenze, strumenti, conoscenza, metadati segreti, conversazioni, report ed eseguire l’agente. La creazione di una conversazione, la creazione o l’aggiornamento dei segreti e il caricamento dei file di conoscenza richiedono chiamate API dirette. Vedi server MCP di Klaviyo.

È abbastanza stabile da poter continuare?

La versione beta indica che lo schema potrebbe cambiare. Gli endpoint sono interamente richiamabili, ma non ci impegniamo ancora per la stabilità a lungo termine. Non inviare integrazioni essenziali per la produzione rispetto alla versione beta.

Dove posso trovare lo schema completo?

Il riferimento completo si trova nel portale di sviluppo di Klaviyo all’indirizzo https://developers.klaviyo.com/en/reference/. Gli endpoint di Customer Agent sono disponibili in Beta API nella revisione 2026-10-15.pre.

Articoli correlati