Azioni

Recuperare dati in tempo reale durante la chiamata

Lascia che l'agente chieda al tuo sistema un ordine, una giacenza o un account mentre chi chiama attende.

Con Strumento API RAG l'agente chiede al tuo sistema dati in tempo reale nel mezzo della conversazione — lo stato di un ordine, la giacenza di un prodotto, i dati di un account — e risponde con quelli. L'agente decide quando usarlo in base alla tua descrizione.

Configurarlo

1. Aggiungi lo strumento

   Apri l'agente → Azioni → Aggiunga strumento → CRM e servizi → Strumento API RAG.

2. Descrivilo e puntalo al tuo endpoint

   Campo	Cosa inserire
   Nome	ad es. Ricerca ordine
   Condizione generale	Quando usarlo, ad es. il cliente chiede lo stato di un ordine
   URL endpoint API	ad es. https://api.yourshop.com/orders/{order_id}: i {placeholders} vengono riempiti con i valori raccolti dall'agente
   Metodo HTTP	GET, POST, PUT, DELETE o PATCH
   Messaggio di esecuzione	Cosa dice l'agente mentre aspetta, ad es. Un attimo, controllo il tuo ordine
   Timeout richiesta (ms)	Quanto aspettare la tua risposta; 5000 di default
   Header, Parametri query	Valori fissi facoltativi, ad es. la tua chiave API

3. Indica cosa deve raccogliere l'agente

   Lo Schema dei parametri (JSON) elenca i valori che l'agente raccoglie da chi chiama e invia: vedi più avanti. Se manca un valore obbligatorio, l'agente lo chiede prima.

suggerimento

Compila sempre il Messaggio di esecuzione: il silenzio mentre la richiesta è in corso sembra una chiamata caduta.

Lo schema dei parametri

Non è il corpo della richiesta in sé, ma un JSON Schema dei valori da raccogliere. Dove finiscono:

Caso	Dove va il valore
L'URL contiene {name}	Nell'URL
GET, DELETE	Il resto come ?key=value
POST, PUT, PATCH	Il resto come corpo JSON

Ricerca di un ordine per numero:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Il numero dell'ordine di cui chiede il cliente, di solito da 6 a 10 cifre. Chiedilo se non lo dice."
    }
  },
  "required": ["order_id"]
}

Una prenotazione con più valori:

{
  "type": "object",
  "properties": {
    "product_id": { "type": "string", "description": "ID del prodotto da una ricerca precedente." },
    "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Quanti. Predefinito 1." },
    "delivery_method": { "type": "string", "enum": ["pickup", "home_delivery", "locker"], "description": "Come il cliente vuole riceverlo." },
    "customer_email": { "type": "string", "format": "email", "description": "Email per la conferma. Chiedila se non la dice." }
  },
  "required": ["product_id", "delivery_method", "customer_email"]
}

Un endpoint statico, ad es. gli orari di apertura: { "type": "object", "properties": {} }.

Buoni schemi per la voce:

• Tienilo piatto: 3–5 valori.
• Scrivi una description per ogni valore, con esempi: è ciò che guida meglio l'agente.
• Usa enum per le scelte fisse: l'agente trasforma «quello blu» in blue.
• Segna un valore come required solo quando la richiesta non può funzionare senza.
• Usa nomi in snake_case che corrispondano ai {placeholders} dell'URL.

Casi d'uso

• Stato dell'ordine: «Dov'è il mio ordine 482913?»
• Disponibilità: controllare la giacenza o un tavolo libero nel tuo sistema.
• Domande sull'account: saldo, scadenza del contratto, ticket aperti.

Problemi comuni

Problema	Cosa controllare
L'agente non lo usa mai	Fai in modo che la Condizione generale indichi la richiesta
Il tuo endpoint riceve valori vuoti	I nomi nello schema devono corrispondere esattamente ai {placeholders}
L'agente dice di non aver potuto controllare	Il tuo endpoint ha impiegato più del timeout o ha risposto con un errore

Vedi anche

• Conoscere chi chiama prima che inizi la chiamata — dati prima del saluto
• Server MCP — molti strumenti da un solo server