Azione Agente AI: Make HTTP requests

Idoneità al piano: Disponibile nei piani Advanced, Enterprise e in alcuni piani Legacy. Il test è disponibile per tutti gli utenti, ma per pubblicare è necessario un piano idoneo.

L'azione Make HTTP requests permette al tuo Agente AI di chiamare API esterne durante una conversazione. Questo consente all'Agente AI di recuperare dati in tempo reale o di attivare azioni in sistemi esterni in base alla richiesta del Contatto. Ad esempio, può verificare lo stato dell'ordine, recuperare informazioni sul conto o creare record in un altro sistema. In questo articolo imparerai a configurare l'azione di richiesta HTTP e a testarla con il tuo Agente AI.

L'Agente AI:

1. Analizza il messaggio del Contatto per determinare se corrisponde all'intento definito nelle tue istruzioni per l'azione.

2. Raccoglie le informazioni richieste.

3. Invia la richiesta HTTP.

4. Interpreta la risposta API.

5. Risponde in modo naturale al Contatto.

Aggiungi un'azione Make HTTP requests

Attiva l'azione e clicca sul pulsante "Add action" per iniziare a configurare la tua richiesta HTTP.

Definisci quando l'azione deve essere eseguita

Assegna un nome descrittivo all'azione nel campo Action name .

Nel campo When and how should this action be performed? campo, descrivi:

• Quando l'Agente AI dovrebbe usare questa azione

• Cosa recupera o invia

• Eventuali condizioni o risultati da gestire

Esempio:

Usa questa azione per recuperare lo stato dell'ordine di un Contatto quando chiede informazioni sul suo ordine. Se l'API restituisce un errore 404, informa il Contatto che l'ordine non è stato trovato.

L'Agente AI usa questa descrizione per decidere quando attivare la richiesta.

Informazioni di cui l'Agente AI potrebbe avere bisogno (opzionale)

Definisci qui gli input richiesti prima di chiamare la tua API.

Si tratta di variabili strutturate che l'AI deve raccogliere. La richiesta viene attivata solo dopo che tutti gli input richiesti sono disponibili.

Se un valore è:

• Già menzionato nella conversazione → l'AI lo usa.

• Mancante → l'AI chiede al Contatto di fornirlo.

Le variabili create qui possono essere usate nella configurazione dell'API. Le variabili del Contatto (come $contact.email) sono disponibili automaticamente e non devono essere aggiunte.

Impostazioni del campo

Configurazione API

Definisci come l'Agente AI deve chiamare la tua API.

Puoi configurare:

• Metodo

• URL

• Parametri di query

• Intestazioni

• Corpo JSON (per POST, PUT, PATCH)

Riferimento alle variabili

Puoi inserire variabili nell'URL, nei parametri, nelle intestazioni o nel corpo usando $.

Ci sono due tipi:

• Variabili del Contatto — campi esistenti del Contatto

  • $contact.email

• Variabili dell'Agente AI — campi definiti in Informazioni di cui l'Agente AI potrebbe avere bisogno

  • $agent.order_id

Le variabili vengono sostituite con valori reali quando la richiesta viene eseguita. Se manca una variabile obbligatoria dell'Agente AI, l'AI la richiederà prima di attivare la chiamata API.

Come l'AI gestisce le risposte API

Esempio di body:

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

L'Agente AI interpreta automaticamente la risposta JSON dell'API e genera una risposta naturale.

Esempio di risposta API:

{
  "status": "shipped",
  "eta": "2025-12-12"
}

Risposta AI: “Buone notizie! Il tuo ordine è stato spedito e dovrebbe arrivare il 12 dicembre 2025.”

Test

Puoi testare la tua azione di richiesta HTTP nel pannello Test AI Agent prima di pubblicare.

Come testare

1. Avvia una conversazione di test che corrisponda alle condizioni della tua azione.

   

2. Quando l'intento viene rilevato e gli input richiesti sono disponibili, l'Agente AI esegue la richiesta HTTP.

3. Un evento di esecuzione appare nel pannello di test:

   

   1. {AI Agent name} ha eseguito {Action name}

   2. Le risposte 2xx vengono considerate un successo

   3. Tutti gli altri codici di stato vengono mostrati come errore

4. Clicca l'evento per visualizzare:

   1. Response scheda (predefinita) — corpo completo della risposta API

   2. Request scheda — payload completo della richiesta cURL

   3. Opzione copia per il debug

5. Dopo aver ricevuto la risposta API, l'Agente AI genera una risposta basata sui dati restituiti.

Note importanti

• Gli eventi di esecuzione appaiono solo nel pannello Test AI Agent. Non appaiono nella Inbox o in Contact Activity.

• Se mancano input obbligatori, l'Agente AI li richiederà prima di attivare la richiesta.

Buone pratiche

• Sii preciso nella descrizione dell'azione. Istruzioni vaghe portano ad attivazioni vaghe.

• Definisci chiaramente gli input richiesti. Se l'AI deve chiedere qualcosa, rendilo ovvio.

• Gestisci i casi di errore nelle tue istruzioni.

• Testa sempre prima di pubblicare.

• Evita di duplicare la logica già gestita dai Workflows a meno che non sia progettato intenzionalmente.

Limitazioni

• Massimo 10 azioni di richiesta HTTP per Agente AI.

• Massimo per azione:

  • 20 campi di input dati

  • 50 parametri

  • 50 intestazioni

• L'Agente AI determina quando chiamare l'API in base alla tua descrizione scritta. Istruzioni scritte male possono causare attivazioni impreviste.

• La gestione della risposta API è automatica. Non puoi mappare manualmente i campi della risposta — l'AI interpreta il JSON contestualmente.

• Gli eventi di esecuzione delle richieste HTTP appaiono solo nel pannello Test AI Agent e non in Contact Activity.

• Gli Agenti AI vocali possono attivare l'azione Make HTTP requests. Tuttavia, la risposta API restituita non viene passata indietro all'Agente AI vocale per generare la risposta, il che significa che le conversazioni vocali non possono rispondere dinamicamente in base al risultato dell'API.