Azioni

Definisci cosa può fare il tuo agente AI durante una conversazione: rispondere a domande usando dati API in tempo reale, raccogliere lead e dati per ricerche di mercato oppure svolgere attività personalizzate.

Gli agenti Quickchat AI hanno due tipi di azione.

Le azioni Quickchat AI sono integrate: devi soltanto attivarle e configurarle:

• Passaggio a un operatore trasferisce la conversazione a una persona.
• Raccolta intelligente dei dati raccoglie lead e altri dati durante la chat.

Le azioni personalizzate si collegano a servizi esterni a Quickchat AI:

• Le azioni API chiamano qualsiasi endpoint HTTP. Sono descritte in questa pagina.
• Le azioni MCP collegano un intero server MCP in una sola volta.
• Google Sheets è una scorciatoia che configura con un clic un’azione di registrazione dei dati.

Ogni azione può leggere i dati aggiornati della conversazione tramite le Variabili delle azioni AI. L’esempio Jira mostra la creazione di un’azione dall’inizio alla fine.

Strumenti di configurazione facoltativi

• Verifica le condizioni di esecuzione delle azioni. Valuta le condizioni su metadati di esempio forniti senza eseguire un’azione.

• Verifica un collegamento MCP di esempio. Inizializza ed elenca gli strumenti soltanto sull’endpoint della documentazione di Cloudflare o di Microsoft Learn. Non vengono effettuati accessi o esecuzioni di strumenti.

Azioni personalizzate

Le azioni personalizzate permettono all’AI di chiamare strumenti esterni durante una conversazione: cercare in sistemi interni, creare ticket, attivare avvisi o recuperare dati aggiornati non presenti nella Knowledge Base. Le trovi in Azioni e MCP, nella sezione Azioni personalizzate.

Fai clic su + Aggiungi azione per crearne una. Il menu offre:

• Azione API: chiama qualsiasi endpoint REST tramite HTTP. È l’opzione più generale; usala per qualsiasi servizio che abbia un URL e accetti JSON.
• MCP: collega un server MCP esterno con un clic e consente all’AI di usarne gli strumenti. Vedi Azioni MCP.
• Azione HubSpot: collegamento predefinito al tuo CRM HubSpot. Usalo per lavorare con contatti, trattative e ticket, anche aggiungendo note private ai ticket, senza gestire personalmente i token API.
• Azione Discord: installa modelli modificabili di azioni API per assistenza e moderazione. Richiede una tua app Discord. Vedi Azioni Discord.
• Google Sheets: legge e scrive in un foglio di calcolo collegato.
• Shopify MCP: collega un negozio Shopify tramite il server Shopify Storefront MCP, così l’AI può cercare nel catalogo e nelle politiche del negozio, leggere i dettagli dei prodotti e creare un carrello. È consentita una sola azione Shopify MCP per scenario. Non include la ricerca degli ordini: vedi la nota seguente.

Nota

Il contatore Rimanenti: N accanto al pulsante + Aggiungi azione mostra quante azioni il tuo piano consente di mantenere attive. Separatamente, ogni agente può avere al massimo 15 azioni complessive, indipendentemente dal piano. Passa a un piano superiore se ti servono più azioni attive oppure contattaci.

Lo stato degli ordini richiede un’azione separata

Shopify Storefront MCP è rivolto ai clienti e non espone dati sugli ordini, quindi un agente AI collegato soltanto tramite questo servizio non può cercare l’ordine di un cliente. Lo stato degli ordini proviene da un’azione API separata Verifica stato dell’ordine, che legge la Shopify Admin API e viene configurata automaticamente quando installi l’app Quickchat dallo Shopify App Store. I negozi collegati incollando un URL non hanno accesso Admin e quindi non possono cercare ordini: reinstalla l’app dall’App Store se ti serve questa funzione.

Come funzionano le azioni personalizzate

1. Scegli un tipo di azione: Azione API, MCP, Azione HubSpot, Azione Discord, Google Sheets o Shopify MCP. Configura il collegamento e le istruzioni necessarie all’AI.
2. Durante una chat, l’AI normalmente usa la descrizione dell’azione e i dettagli disponibili sugli strumenti o sui parametri per decidere quando eseguirla. Un’azione API può invece essere eseguita automaticamente prima della prima risposta o quando le condizioni sui metadati vengono soddisfatte per la prima volta.
3. Quickchat esegue la chiamata. Per un’azione scelta dall’AI o eseguita prima della prima risposta, l’AI può usare la risposta ricevuta. Un’azione attivata dai metadati viene eseguita silenziosamente e il suo risultato non viene aggiunto alla chat.
4. Prova o collega l’azione dal suo editor prima di usarla nelle conversazioni.

Consiglio

Scrivi la descrizione come un’istruzione per l’AI. Indica quando usare l’azione, cosa restituisce ed eventuali vincoli (ad esempio “chiama solo quando l’utente fornisce un numero d’ordine”).

Preparare azioni da una descrizione

1. In Azioni e MCP, scegli + Aggiungi azione > Azione API.
2. Descrivi il flusso di lavoro, quando l’agente deve intervenire, le API da usare (o inserisci i link alla loro documentazione) e le informazioni necessarie a ogni passaggio. Fai clic su Genera.
3. Quickchat prepara fino a quattro nuove bozze di azioni API, tutte inattive. Il risultato può consigliare azioni esistenti anziché creare duplicati oppure chiedere maggiori dettagli. Generare bozze non esegue le azioni.
4. Leggi Azioni esistenti utilizzate, eventuali prerequisiti e Passaggi successivi. Completa la configurazione, sostituisci i valori segnaposto e controlla richiesta, istruzioni e condizioni di esecuzione di ogni azione. Prova ogni azione prima di abilitare le bozze o un’azione esistente inattiva necessaria.

La sequenza suggerita descrive il comportamento previsto. Non garantisce l’ordine delle azioni scelte dall’AI. Usa input obbligatori, memoria salvata e condizioni di esecuzione per esprimere le dipendenze. Dopo aver abilitato le azioni, prova l’intero flusso in una conversazione.

Creare un’azione API

1. Vai in Azioni e MCP.
2. Fai clic su + Aggiungi azione in Azioni personalizzate, scegli Azione API, poi fai clic su Crea manualmente.
3. Compila Dettagli:
   • Nome: chiaro e descrittivo.
   • Descrizione: quando usarla e cosa includere nei parametri.
4. In Quando eseguire, scegli Decide l’AI, Prima della prima risposta o Quando i metadati corrispondono.
5. Configura Collegamento:
   • Tipo di azione: metodo HTTP (GET, POST e così via).
   • URL dell’endpoint dell’azione: URL completo dell’API.
   • Header: aggiungi gli header necessari, come Authorization o content-type: application/json.
6. Definisci i Parametri: assegna a ciascuno un nome, una posizione (query, corpo o header) e una descrizione che indichi all’AI come comporre il valore. I valori del percorso non sono una posizione dei parametri: inseriscili direttamente nell’URL dell’endpoint usando i segnaposto {{placeholder}}.
7. Esegui Testa richiesta e verifica la risposta. Poi fai clic su Fatto.

Consiglio

Ogni campo di valore (URL, header, corpo o query) accetta segnaposto dinamici tramite il pulsante + Aggiungi dati AI. Puoi inserire parametri AI, variabili di conversazione predefinite ({{scenario_id}}, {{language}}, {{country}}, …) e metadati della conversazione ({{metadata_*}}). Consulta Variabili delle azioni AI per il riferimento completo.

Oltre alla richiesta, un’azione API offre tre impostazioni facoltative utili: Salva in memoria, Esegui solo quando e Filtro della risposta.

Visualizza un’anteprima di una richiesta di azione API usando un modello fornito e valori di esempio sintetici. Ometti gli header con credenziali. L’anteprima compila la richiesta senza inviarla.

Scegliere quando eseguire un’azione API

Usa Quando eseguire per selezionare una delle tre modalità:

La sezione è chiusa per impostazione predefinita e mostra la modalità attiva accanto al titolo; espandila per modificarla.

• Decide l’AI: la modalità predefinita. L’AI legge la descrizione dell’azione e decide se la richiesta del visitatore la richiede. Usala quando l’azione deve essere eseguita soltanto per domande specifiche o dopo che l’AI ha raccolto informazioni dal visitatore.
• Prima della prima risposta: Quickchat esegue l’azione una volta dopo il primo messaggio del visitatore e prima che l’AI scriva la prima risposta. La normale risposta AI riceve il risultato e i valori salvati con Salva in memoria. L’AI non può più scegliere questa azione come strumento, quindi viene eseguita soltanto nel primo scambio e non più avanti nella conversazione. Usala per identificare il cliente, acquisire il contesto dell’account, verificare i diritti di accesso o altre operazioni iniziali necessarie a ogni conversazione reale.
• Quando i metadati corrispondono: Quickchat verifica le condizioni Esegui quando dell’azione dopo ogni turno dell’AI e la esegue la prima volta che tutte sono soddisfatte. I valori salvati in memoria da un’altra azione durante quel turno sono immediatamente disponibili. L’AI non può scegliere questa azione come strumento e la sua risposta non viene aggiunta alla chat. Usala per notifiche interne, aggiornamenti del CRM o richieste successive che devono avvenire automaticamente quando diventano disponibili i dati della conversazione.

Prima della prima risposta è legata al primo messaggio del visitatore, non alla creazione della conversazione. Aprire una chat o ricevere un messaggio di benvenuto non la esegue, quindi le chat abbandonate non generano richieste. Quickchat registra l’esecuzione prima di chiamare l’endpoint, quindi non riprova nella stessa conversazione anche se la richiesta fallisce o il suo esito è incerto.

La prima risposta attende la richiesta, quindi questa modalità può aggiungere latenza. Se più azioni usano questa modalità, vengono eseguite una dopo l’altra e i tempi delle richieste si sommano. Se mancano metadati obbligatori, l’endpoint non è disponibile o una richiesta fallisce, l’AI risponde comunque. Apri Log delle richieste dell’azione per vedere cosa è successo.

Poiché l’azione viene eseguita prima che l’AI possa scegliere i valori dei parametri, ogni parametro AI usato deve avere un valore predefinito. Metadati e variabili predefinite possono essere inseriti direttamente nell’URL, negli header, nella query o nel corpo.

Quando i metadati corrispondono richiede almeno una condizione Esegui quando e un valore predefinito per ogni parametro AI. Quickchat registra il tentativo prima di chiamare l’endpoint, quindi, una volta inviata la richiesta, l’azione non viene ritentata nella stessa conversazione, indipendentemente dal successo, dal fallimento o dall’incertezza dell’esito. Una richiesta impossibile da costruire perché manca ancora un valore necessario non viene registrata e rimane idonea per un turno successivo. L’azione viene eseguita subito dopo che l’AI conclude il turno, quindi un errore non sostituisce mai la risposta AI. Nei canali che non trasmettono la risposta in streaming, il tempo di andata e ritorno della richiesta si aggiunge all’attesa del visitatore.

Scegliendo Quando i metadati corrispondono, l’editor Esegui quando compare nella stessa sezione, mantenendo insieme l’attivazione e le sue condizioni.

Identificare tramite email o telefono

Per i canali che possono fornire un indirizzo email o un numero di telefono, crea un’azione di ricerca per ogni identificatore. Imposta entrambe su Prima della prima risposta, poi aggiungi una condizione Esegui solo quando corrispondente, come visitor_email exists o visitor_phone_number exists. Quickchat invia soltanto la richiesta i cui metadati sono presenti.

Azioni HubSpot

Azione HubSpot apre una raccolta di azioni API precompilate e modificabili che usano il tuo account HubSpot collegato.

Il modello Aggiungi nota al ticket crea una nota privata nel ticket HubSpot collegato alla conversazione. Salva il contenuto della nota nella memoria della conversazione come hubspot_note_body, poi aggiungi il modello e attivalo. È preconfigurato con Quando i metadati corrispondono e attende che siano presenti sia hubspot_note_body sia hubspot_ticket_id, fornito dal server di Quickchat. Puoi modificare il valore predefinito del parametro note_body per aggiungere testo fisso attorno a {{metadata_hubspot_note_body}}.

La nota è interna a HubSpot e non viene mostrata al visitatore. Il modello tenta la richiesta una volta per conversazione Quickchat. Apri il Log delle richieste dell’azione per confermare la consegna o indagare su una richiesta non riuscita.

Azioni Discord

Azione Discord apre una raccolta di azioni API precompilate e modificabili:

• Assistenza e ticket: Apri ticket di assistenza ti chiede di selezionare un server e un canale testuale. Puoi scegliere facoltativamente un ruolo di assistenza menzionabile. Crea tre azioni che aprono un thread privato, aggiungono il richiedente corrente e pubblicano un riepilogo con l’eventuale menzione del ruolo.
• Moderazione: Metti membro in timeout, Espelli membro, Banna membro, Revoca ban membro, Assegna ruolo, Imposta modalità lenta e Invia annuncio. Ogni modello si installa con un clic e usa il server, il membro, il ruolo o il canale della richiesta Discord corrente.

Quickchat crea sul backend metodo HTTP, URL, header, corpo, parametri, descrizione, impostazioni della risposta e condizioni di esecuzione. Le schede risultanti sono normali azioni di richiesta HTTP. Puoi esaminare e modificare tutti i campi.

Tutti e sette i modelli di moderazione includono author_is_admin is true in Esegui solo quando. Discord calcola l’autorizzazione Amministratore dell’autore corrente, il gateway Discord fornisce quel valore e Quickchat lo verifica prima di inviare la richiesta. La chat pubblica e i metadati API non possono impostare questa chiave. Prova le azioni di moderazione in Discord con un account amministratore e con uno non amministratore; l’anteprima AI non fornisce un mittente Discord autorizzato.

Attenzione

Le azioni di moderazione sono modificabili. Rimuovere o indebolire la condizione author_is_admin is true elimina il limite di autorizzazione fornito. Espulsione e ban non chiedono conferma prima dell’esecuzione.

I modelli non aggiungono automazioni autonome. L’agente li esegue soltanto quando un amministratore lo chiede nella conversazione; non sono previsti conteggi delle infrazioni tra conversazioni, verifica di screenshot o altre prove, né sanzioni programmate o avviate autonomamente.

Il bot deve comunque disporre dell’autorizzazione Discord richiesta per ogni operazione:

Azione	Autorizzazione o accesso del bot
Metti membro in timeout	Moderate Members
Espelli membro	Kick Members
Banna membro, Revoca ban membro	Ban Members
Assegna ruolo	Manage Roles
Imposta modalità lenta	Manage Channels
Invia annuncio	View Channels e Send Messages

Discord applica anche la gerarchia dei ruoli. Posiziona il ruolo del bot sopra i membri e i ruoli che deve gestire. Il modello non esegue un’ulteriore verifica della gerarchia o delle singole autorizzazioni dell’amministratore richiedente.

Imposta modalità lenta e Invia annuncio accettano un parametro ID del canale. Senza una destinazione fissa aggiuntiva, il modello non verifica che il canale appartenga al server in cui l’amministratore ha inviato la richiesta. Se lo stesso bot appartiene a più server, modifica queste azioni per usare un ID di canale fisso oppure separa i server tra agenti e credenziali dei bot diversi.

L’installazione del ticket di assistenza usa funzionalità esistenti delle azioni per trasmettere dati:

1. open_support_ticket crea un thread privato nel canale selezionato, acquisisce $.id e lo salva nella memoria della conversazione come discord_ticket_thread_id. Richiede discord_message is true, viene eseguita soltanto nel server selezionato e soltanto finché quella chiave di memoria non esiste.
2. add_ticket_requester legge {{metadata_discord_ticket_thread_id}} e {{metadata_discord_author_id}} fornito da Discord. Richiede discord_message is true e viene eseguita soltanto nel server selezionato dopo che esiste l’ID del thread.
3. post_in_ticket legge lo stesso ID del thread salvato, pubblica il riepilogo del problema in una riga formulato dall’agente e menziona il richiedente. Se hai selezionato un ruolo di assistenza, menziona anche quello. Ha le stesse condizioni relative a messaggio Discord, server e thread salvato. Il suo corpo Discord allowed_mentions è limitato al richiedente e, se configurato, a quel ruolo.

Le descrizioni e il prompt dell’agente devono indicare di eseguire le azioni in quell’ordine. Non esiste un livello separato di stato del flusso di lavoro, blocco, conferma, nuovi tentativi, ripristino, riconciliazione o protezione dalle ripetizioni. Se un esito è incerto, controlla Discord e il log dell’azione prima di riprovare, perché Discord potrebbe avere già completato la richiesta.

discord_ticket_thread_id non viene cancellato automaticamente. La configurazione iniziale supporta quindi un ticket per conversazione Quickchat. Avvia una nuova conversazione o un nuovo thread Discord per un altro ticket, oppure modifica le azioni per aggiungere il ciclo di gestione della memoria necessario.

Per il ticket di assistenza, concedi al bot View Channels, Send Messages, Read Message History, Create Private Threads, Send Messages in Threads e Manage Threads nel canale ticket selezionato. Lascia Notifica un ruolo (facoltativo) su Non notificare alcun ruolo se non vuoi menzionare ruoli. Se selezioni un ruolo, deve essere menzionabile e i suoi membri devono avere accesso ai thread privati. Quando non sono disponibili ruoli menzionabili, i ticket si aprono comunque senza notifiche ai ruoli. La raccolta elenca canali testuali e ruoli menzionabili, ma non convalida tutte le autorizzazioni specifiche dei canali.

Attenzione

Le azioni Discord richiedono il token della tua app Discord in App esterne → Discord → Configurazione avanzata. Il solo bot condiviso installabile con un clic non può fornire quel token. Vedi Discord.

La raccolta è una scorciatoia di configurazione, non un ulteriore livello di regole. Se modifichi un’azione generata o crei un’azione API Discord personalizzata, controlla credenziali, destinazioni, parametri, esposizione della risposta e condizioni Esegui solo quando prima di abilitarla.

Salva in memoria

Salva un valore di un input dell’azione o della risposta API nella memoria della conversazione con una chiave a tua scelta. Le azioni successive possono riutilizzarlo come {{metadata_<key>}} e il valore compare nei dettagli della conversazione (Posta in arrivo, API ed esportazioni).

Usalo quando un’azione produce un valore necessario a un’azione successiva. Un’azione di ricerca può salvare customer_id dalla risposta; un’azione successiva invia poi {{metadata_customer_id}} senza che l’AI debba copiare il valore.

Nell’editor dell’azione API, apri Salva in memoria e aggiungi una riga:

1. Scegli una Fonte. Risposta API legge la risposta JSON dell’API ed è l’impostazione predefinita per le nuove righe. Input dell’Azione legge i valori dei parametri di ingresso dichiarati nell’azione.
2. In Valore da salvare, seleziona il parametro dal menu a discesa per Input dell’Azione. Per Risposta API, inserisci un’espressione JSONPath come $.customer_id.
3. Scegli una Chiave di memoria. I nomi inglesi comuni degli input di nome, telefono ed email suggeriscono la chiave del visitatore corrispondente. Puoi mantenere il suggerimento o inserire una tua chiave.

Per salvare i recapiti in Posta in arrivo, usa Input dell’Azione con queste mappature:

Parametro dell’azione	Chiave di memoria
Name o Full name	visitor_name
Phone number o Phone	visitor_phone_number
Email o Email address	visitor_email

L’input deve essere dichiarato nell’azione. Salvarlo tramite una regola di memoria Input dell’Azione conta come utilizzo del parametro, quindi può essere raccolto per la memoria senza essere inviato nella richiesta HTTP. Queste chiavi del visitatore compilano i campi di contatto non impostati in Posta in arrivo e i metadati della conversazione usando la stessa convalida della Raccolta intelligente dei dati. I recapiti esistenti e i campi esplicitamente cancellati da un operatore vengono conservati. Le regole della risposta API non possono scrivere queste chiavi del visitatore: usa una chiave personalizzata come customer_id per i valori della risposta del CRM.

Gli input vengono salvati dopo il superamento delle verifiche sugli input obbligatori e sulle condizioni di esecuzione, prima della richiesta HTTP. I recapiti validi rimangono quindi disponibili se l’API restituisce un errore o scade il tempo di attesa. Per verificarli, esegui l’azione in una nuova conversazione di anteprima e aprila in Posta in arrivo. Il test API isolato dell’editor non ha una conversazione in cui salvare la memoria.

Le chiavi di memoria sono condivise con gli strumenti MCP remoti dell’agente. Se uno strumento MCP salva già nella stessa chiave, il campo Chiave di memoria segnala il conflitto al salvataggio: scegli quindi una chiave diversa. Gli strumenti MCP remoti continuano a salvare valori dai propri risultati.

Consiglio

Usa chiavi snake_case (lettere, cifre e trattini bassi). Una chiave come customer_id può essere richiamata come {{metadata_customer_id}}; le chiavi con spazi o altra punteggiatura non possono essere usate nei segnaposto. Vedi Metadati della conversazione per il funzionamento delle variabili dei metadati.

Esegui solo quando

Limita un’azione affinché venga eseguita soltanto quando sono soddisfatte condizioni sui metadati della conversazione. Le condizioni vengono sempre verificate lato nostro, al di fuori del modello. Con Decide l’AI o Prima della prima risposta, Quickchat le verifica immediatamente prima di inviare la richiesta. Con Quando i metadati corrispondono, sono le condizioni stesse ad attivare la richiesta dopo un turno dell’AI, senza attendere che l’AI scelga l’azione.

È lo strumento adatto per azioni privilegiate o irreversibili (bannare un membro, emettere un rimborso, eliminare un record). Una frase nel prompt come “solo gli amministratori possono farlo” è un’istruzione utile, ma non costituisce una barriera di sicurezza: un utente determinato può discutere con il modello o tentare una prompt injection. Una condizione di esecuzione è deterministica ed esiste al di fuori del prompt, quindi vale indipendentemente da ciò che viene detto nella conversazione.

• La condizione di esecuzione è il limite di sicurezza. Viene valutata lato server e non fa parte del prompt letto dal modello. È ciò che impedisce effettivamente l’esecuzione dell’azione.
• La regola del prompt definisce l’esperienza utente. Mantieni anche una frase nel prompt, affinché l’AI rifiuti cortesemente e spieghi il motivo anziché restare in silenzio.

Aggiungi condizioni nella sezione Esegui solo quando dell’editor dell’azione. Per un’azione Quando i metadati corrispondono, la sezione si chiama Esegui quando. Fai clic su Aggiungi condizione, scegli una chiave dei metadati (ad esempio telegram_sender_is_admin) e scegli come confrontarla:

Condizione	Soddisfatta quando il valore del metadato…
è vero	è valutato come vero
è falso	è valutato come falso
esiste	è presente nella conversazione
non esiste	è assente
è uguale a	corrisponde a un valore specificato
non è uguale a	differisce da un valore specificato
è uno di	corrisponde esattamente a uno dei valori elencati, incluse maiuscole, minuscole e spazi
contiene il testo	è un testo che contiene letteralmente il testo specificato, distinguendo maiuscole e minuscole

L’azione viene eseguita soltanto quando tutte le condizioni sono soddisfatte. L’editor mostra AND tra le righe. Quando una condizione blocca un’azione scelta dall’AI, l’AI può spiegare che l’azione non è disponibile. Un’azione Quando i metadati corrispondono rimane silenziosa finché le condizioni non sono soddisfatte.

Usa è uno di per alternative sulla stessa chiave, inserendo ciascuna come valore separato. Ad esempio, modelName is one of [K-65XR95M2, K-75XR95M2, K-85XR95M2] può essere affiancata da country equals UK; entrambe le righe devono essere soddisfatte. Puoi aggiungere fino a 50 alternative di massimo 500 caratteri ciascuna. Le virgole sono parti letterali del valore. Righe è uguale a separate per valori diversi della stessa chiave non possono essere tutte soddisfatte.

contiene il testo cerca una sottostringa letterale, non un carattere jolly o un’espressione regolare. XR95M2 corrisponde anche a varianti del nome del modello oltre alle tre elencate sopra. Entrambe le nuove condizioni rifiutano chiavi mancanti, null, elenchi e oggetti; contiene il testo rifiuta anche numeri e valori booleani. Un testo di confronto vuoto non è consentito. Le condizioni esistenti è falso, non è uguale a e non esiste possono corrispondere a chiavi mancanti.

Quando una condizione non è soddisfatta, non viene inviata alcuna richiesta e l’AI comunica all’utente di non poter eseguire l’operazione. Di seguito, la stessa richiesta di ban viene bloccata per un non amministratore e consentita per un amministratore, cambiando soltanto chi la richiede:

Attenzione

Usa come vincolo soltanto metadati impostati da Quickchat (come il flag telegram_sender_is_admin verificato dal canale), non valori influenzabili dal visitatore. Vedi Metadati della conversazione per l’origine di ogni chiave.

Filtro della risposta

Per impostazione predefinita, l’AI vede la risposta API completa. Aggiungi espressioni JSONPath nella sezione Filtro della risposta per limitarla a parti specifiche.

Due motivi comuni per filtrare:

• Nascondere campi sensibili. Escludi email dei clienti, dettagli dei pagamenti o ID interni dal contesto del modello quando l’endpoint restituisce più di quanto serve all’AI.
• Ridurre il prompt. Le API molto verbose possono restituire grandi quantità di dati; filtrare i pochi campi rilevanti mantiene la risposta compatta e l’AI concentrata.

Aggiungi una o più espressioni JSONPath. Il filtro mantiene i campi selezionati all’interno degli oggetti e degli array che li contengono, anziché appiattirli in un elenco di valori. I campi esterni ai percorsi selezionati vengono omessi. Ad esempio, usa queste due righe:

• $.customer.name
• $.orders[*].id

Data questa risposta API:

{
  "customer": {"name": "Ada", "email": "ada@example.com"},
  "orders": [{"id": 101, "total": 25}, {"id": 102, "total": 40}]
}

L’AI riceve questa risposta filtrata, in cui customer rimane un oggetto e orders rimane un array di oggetti:

{
  "customer": {"name": "Ada"},
  "orders": [{"id": 101}, {"id": 102}]
}

Consiglio

Usa il pannello Testa risposta per vedere esattamente cosa riceverà l’AI dopo il filtro prima di farvi affidamento. Vedi Provare l’azione.

Attenzione

Un JSONPath che non trova corrispondenze lascia all’AI una risposta vuota. Inizia senza filtro, verifica che la chiamata funzioni e poi restringilo.

Visualizza un’anteprima delle corrispondenze JSONPath in una risposta JSON fornita. L’anteprima supporta percorsi radice, campi, indici di array e caratteri jolly per le regole Filtro della risposta o Salva in memoria.

Verificare lo stato e i log delle azioni

Un avviso accanto ad Azioni e MCP nella barra laterale indica che un’azione richiede attenzione. Apri la pagina e passa il puntatore sul badge della scheda, o selezionalo tramite tastiera, per vedere il motivo:

• In errore: le chiamate recenti sono fallite ripetutamente. Il badge mostra il numero di errori e l’ultimo errore, quando disponibile.
• Non in esecuzione: l’azione è stata saltata ripetutamente, senza chiamate eseguite nella finestra corrente di valutazione dello stato. Controlla il motivo indicato, ad esempio valori della conversazione mancanti o un problema di configurazione.
• Riconnessione necessaria: un collegamento MCP ha perso l’autorizzazione ed è stato disattivato. Apri Modifica, ricollegalo e riattivalo.

Lo stato si basa sulle conversazioni reali degli ultimi sette giorni oppure da quando l’azione è stata modificata l’ultima volta, se più recentemente. È separato dalle richieste di test. Dopo aver corretto e salvato un’azione, controlla nuove conversazioni per confermare la correzione; eliminare un vecchio avviso non dimostra da solo che funzioni.

Per In errore o Non in esecuzione, fai clic su Visualizza dettagli per aprire il Log delle richieste con Solo problemi attivo. Visualizza log apre il log con tutte le chiamate. Disattiva Solo problemi per confrontare le chiamate problematiche con quelle riuscite.

Conversazioni saltate elenca le conversazioni in cui l’azione non ha potuto essere eseguita, separatamente dalle chiamate effettivamente eseguite. Usa Visualizza conversazione per esaminare il contesto e Mostra altro per caricare voci meno recenti. Un’azione può funzionare in alcune conversazioni ed essere saltata in altre, quindi questo elenco può comparire anche senza un badge di avviso.

Quando il motivo elenca valori mancanti come {{metadata_visitor_email}}, forniscili tramite i metadati del sito web o del canale oppure fai in modo che un’azione precedente li salvi in memoria. Poi controlla la modalità di esecuzione:

• Decide l’AI: l’azione viene proposta all’AI soltanto nelle conversazioni che hanno già i valori necessari.
• Prima della prima risposta: i valori devono essere presenti quando il visitatore invia il primo messaggio.
• Quando i metadati corrispondono: aggiungi una condizione esiste per ogni valore necessario, così l’azione attende che sia disponibile.

Vedi Variabili delle azioni AI per l’origine dei valori della conversazione.

Le email di riepilogo delle attività includono anche una sezione Le azioni AI richiedono attenzione quando un’azione HTTP o MCP remota richiede attenzione. Elenca fino a cinque azioni, con un motivo e un link ad Azioni e MCP; un conteggio aggiuntivo indica quante altre richiedono attenzione. La sezione viene omessa quando tutto funziona correttamente.

L’email mostra lo stato corrente, che può coprire un periodo più ampio della finestra di attività del riepilogo giornaliero. Dopo il salvataggio di un’azione API corretta, la valutazione dello stato riparte da quella modifica. Ricollegare o scollegare un collegamento MCP interessato elimina l’avviso di autorizzazione. Si applicano le preferenze e le regole di idoneità delle email di riepilogo esistenti e non viene inviata un’email di avviso separata.

Buone pratiche

• Sii esplicito nelle descrizioni. Indica all’AI quando usare l’azione e cosa deve contenere ogni parametro.
• Mantieni gli ambiti di accesso al minimo. Includi soltanto gli header e i token necessari all’endpoint. Per Jira, usa l’header Basic derivato dall’email Atlassian e dal token API.
• Prova prima di distribuire, usando il pannello Testa richiesta. Verifica che codici di stato e contenuti di esempio siano corretti nello strumento di destinazione.

Tutorial

• Collegare un agente AI ai ticket Jira (riferimento ufficiale) oppure la guida narrata nel blog
• Inviare una notifica Slack con un’azione AI