# Procedure: playbook passo per passo per il tuo agente

> Scrivi procedure che l'agente segue passo per passo per un tipo di richiesta, come un rimborso: fare domande, chiamare le tue azioni API, controllare condizioni e chiedere conferma al visitatore prima di modificare qualcosa.

Una procedura dice al tuo agente esattamente come gestire un tipo di richiesta. Per un rimborso, per esempio: chiedere il numero d'ordine, cercare l'ordine con una delle tue [azioni API](/it/docs/api-actions), controllare se può essere rimborsato e poi rimborsarlo dopo la conferma del visitatore, oppure spiegare perché non è possibile. L'agente avvia la procedura quando la richiesta di un visitatore corrisponde e poi segue i tuoi passi in ordine, uno alla volta.

Insieme a **Only inside procedures** su un'azione, una procedura decide anche quando un'azione rischiosa può essere eseguita: solo nel passo in cui l'hai inserita e, se vuoi, solo dopo che il visitatore ha confermato.

> Le procedure fanno parte dei piani Starter, Pro ed Enterprise. Vedi [Piani](#piani).

## Piani

| | Free | Starter | Pro | Enterprise |
| --- | --- | --- | --- | --- |
| Procedure per agente | Nessuna | 3 | 10 | Nessun limite del piano (fino a 50 per agente) |

L'agente segue solo le prime procedure attive fino al limite del tuo piano, nell'ordine dell'elenco. Una procedura oltre quel punto mostra **Over your plan's limit** nell'elenco. Le procedure disattivate non occupano un posto.

Nel piano Free la sezione **Procedures** mostra **Included from Starter**. Dopo un downgrade non viene eliminato nulla: le procedure che non puoi più usare restano nell'elenco e tornano a funzionare dopo un upgrade. Una chat che era a metà di una procedura la termina al messaggio successivo del visitatore.

## Creare una procedura

1. Nella scheda **Actions** (azioni) vai a **Procedures**, sotto le tue azioni, e clicca su **Add procedure**.
2. Scegli **Start from scratch** oppure parti da un template: **Refund request**, **Cancel a subscription** o **Reschedule an appointment**. I passi di azione di un template non hanno ancora un'azione; scegline una delle tue in ciascuno prima di salvare.
3. Compila la procedura:
   - **Name** (nome): fino a 80 caratteri. Compare nell'elenco, in **Why this answer** e nella scheda **Conversations**. Lo legge anche l'agente.
   - **When to use** (quando usarla): fino a 500 caratteri. Lo legge l'agente, i visitatori non lo vedono. Vedi [Scrivere un buon "When to use"](#scrivere-un-buon-when-to-use).
   - **Steps** (passi): fino a 15. Clicca su **Add step** e scegli un tipo. Usa le frecce per cambiare l'ordine e il pulsante del cestino per rimuovere un passo. Vedi [Tipi di passo](#tipi-di-passo).
   - **Agent can follow this procedure**: attivo per impostazione predefinita.
4. Clicca su **Add procedure**.

Se manca qualcosa o qualcosa non va, il campo indica cosa correggere, per esempio "Pick the action this step calls" o "Pick a step that exists".

Nell'elenco, ogni procedura mostra il badge **Procedure**, il numero di passi e il suo **When to use**.

- L'interruttore **Enabled** impedisce all'agente di avviare la procedura, senza eliminarla.
- Le frecce cambiano l'ordine. Quando il limite del tuo piano esclude alcune procedure, vengono seguite quelle in cima.
- **Edit** apre la procedura.
- Il pulsante del cestino la elimina. Le conversazioni continuano a mostrare che è stata eseguita.

I membri del team con il ruolo **Viewer** vedono l'elenco e possono aprire una procedura con **View**, ma non possono modificare nulla.

## Scrivere un buon "When to use"

L'agente avvia una procedura solo quando la richiesta del visitatore corrisponde chiaramente al suo **When to use**. Quando la corrispondenza non è chiara, chiede invece al visitatore di cosa ha bisogno.

- Descrivi la richiesta con le parole del visitatore: "Il visitatore chiede la restituzione dei soldi per un ordine che ha effettuato."
- Indica a cosa non serve quando potrebbe esserci confusione: "Non per domande generali sulla politica dei rimborsi."
- Tieni un solo tipo di richiesta per procedura e non lasciare che due procedure coprano la stessa richiesta.

Un testo vago come "Rimborsi" fa avviare all'agente la procedura per qualsiasi domanda che citi i rimborsi, compreso "Quanto tempo richiede un rimborso?".

## Tipi di passo

| Passo | Cosa fa l'agente | Limiti |
| --- | --- | --- |
| **Instruction** | Ciò che scrivi tu, come spiegare una politica o offrire un [passaggio via email](/it/docs/handoff), un [modulo in chat](/it/docs/chat-forms) o una [prenotazione](/it/docs/booking). | Fino a 1.000 caratteri |
| **Ask the visitor** | Fa la tua domanda e salva la risposta con un nome. | Domanda fino a 500 caratteri |
| **Call an action** | Chiama una delle tue azioni API lato server. Facoltativamente chiede prima conferma al visitatore. | Un'azione per passo |
| **Condition** | Controlla qualcosa che descrivi e va a un passo se è vero, a un altro se non lo è. | Fino a 500 caratteri |
| **End** | Conclude la procedura, con un messaggio di chiusura facoltativo. | Fino a 1.000 caratteri |

- **Instruction**: il passo è completato quando l'agente ha fatto ciò che dice. Se ha bisogno della risposta del visitatore, l'agente la aspetta. Gli strumenti integrati come il passaggio via email, i moduli e la prenotazione restano disponibili come sempre, quindi un'istruzione può dire all'agente di usarli.
- **Ask the visitor**: in **Save the answer as**, dai alla risposta un nome fatto di lettere minuscole, numeri e trattini bassi, che inizi con una lettera, fino a 32 caratteri, per esempio `order_number`. Due passi non possono salvare con lo stesso nome. L'agente chiede nella lingua del visitatore e, se il visitatore ha già dato la risposta prima nella chat, salva quella invece di chiedere di nuovo. Una risposta può arrivare a 500 caratteri. intoCHAT salva solo una risposta che viene da ciò che il visitatore ha scritto: ogni numero deve comparire nei suoi messaggi, e così la maggior parte delle parole. Quindi l'agente non può compilare un passo con un'ipotesi o un segnaposto; deve chiedere e aspettare la risposta. Può accorciare una risposta, ma deve mantenere le parole del visitatore, nella sua lingua.
- **Call an action**: scegli una delle [azioni API](/it/docs/api-actions) lato server di questo agente. Le [azioni lato client](/it/docs/client-actions) e i [pulsanti personalizzati](/it/docs/custom-buttons) non si possono usare. Il passo è completato quando l'azione riesce, e l'agente prosegue da solo. Quando non riesce, il passo resta dov'è: l'agente può riprovare una volta se l'errore suggerisce una correzione, oppure lo dice al visitatore e interrompe la procedura. Vedi anche [Compilare gli input dell'azione](#compilare-gli-input-dell-azione) e [Conferma del visitatore](#conferma-del-visitatore).
- **Condition**: descrivi cosa controllare in **If**, per esempio "L'ordine è stato consegnato meno di 30 giorni fa." In **If yes, go to** e **If no, go to** scegli **Next step**, **End** o un altro passo. Una condizione può tornare a un passo precedente, ma non a se stessa. L'agente decide in base a ciò che ha detto il visitatore e a ciò che hanno restituito le azioni; quando non riesce a stabilirlo, prima chiede al visitatore.
- **End**: la procedura è conclusa appena l'agente arriva a questo passo, e l'agente la chiude con il tuo messaggio, con parole sue. Senza messaggio, dice brevemente al visitatore cosa è stato fatto. Anche andare oltre l'ultimo passo conclude la procedura.

## Compilare gli input dell'azione

In un passo di azione, **Fill inputs from the visitor's answers** invia alcuni degli [input di dati](/it/docs/api-actions) dell'azione esattamente come li ha dati il visitatore. Clicca su **Fill an input**, scegli l'input e scrivi il suo valore con i nomi delle risposte precedenti tra doppie parentesi graffe, per esempio `{{order_number}}`. Un valore può anche mescolare testo fisso e risposte, come `Order {{order_number}}`, fino a 500 caratteri.

- intoCHAT compila questi input da solo, e sostituiscono qualunque valore l'AI avrebbe passato. L'agente non può modificarli.
- Gli input che non compili li compila l'agente dalla conversazione, come sempre.
- Quando salvi, intoCHAT controlla che l'azione sia una delle azioni lato server di questo agente, che ogni input che compili sia uno dei suoi input di dati e che ogni `{{name}}` venga salvato da un passo **Ask the visitor** prima di questo passo.
- Se una condizione ha saltato il passo che salva una risposta, l'azione non viene chiamata con un valore vuoto. L'agente dice al visitatore che non può finire e interrompe la procedura.

## Azioni solo nelle procedure

Nell'editor di un'[azione API](/it/docs/api-actions) lato server, attiva **Only inside procedures** per le azioni che modificano qualcosa, come un rimborso o una disdetta.

- In una chat normale l'agente non riceve l'azione. La riceve solo mentre una procedura si trova su un passo che la chiama.
- Una chiamata in qualsiasi altro momento viene rifiutata con "This action can only run inside a procedure step." e compare come **Failed** in **Why this answer**. Alla tua API non viene inviato nulla.
- Nell'elenco l'azione mostra il badge **Procedure only**. Un'azione che nessuna procedura chiama non viene mai usata.
- Le azioni lato client e i pulsanti non possono essere solo per le procedure.

> Senza **Only inside procedures**, l'agente può chiamare l'azione anche fuori dalla procedura, come qualsiasi altra azione, e lì la conferma del passo di una procedura non vale. Attivalo per ogni azione che deve essere eseguita solo dopo i tuoi passi.

Un'azione chiamata da una procedura non si può eliminare e non si può trasformare in un'azione lato client o in un pulsante. Il messaggio indica le procedure da modificare prima.

## Conferma del visitatore

Con **Ask the visitor to confirm first** selezionato in un passo di azione:

1. La prima chiamata dell'agente non esegue l'azione. L'agente viene informato di cosa verrebbe inviato, dice al visitatore cosa succederà con quei valori e gli chiede di confermare.
2. intoCHAT esegue l'azione solo quando l'agente la chiama di nuovo per lo stesso passo, con esattamente gli stessi valori, e il visitatore ha inviato un nuovo messaggio da quando l'agente ha chiesto. Una chiamata nella stessa risposta della domanda viene sempre rifiutata.
3. Se i valori sono cambiati, per esempio perché il visitatore ha corretto il numero d'ordine, l'agente deve chiedere di nuovo con i nuovi valori.

Il controllo lo fa il server di intoCHAT, non l'AI. Quello che il server non può controllare è se il messaggio del visitatore dice davvero di sì: è una valutazione dell'agente, così come ogni **Condition**. Un visitatore insistente può convincere l'agente a superare una condizione, quindi fai rifiutare alla tua API ciò che non deve mai succedere, come rimborsare un ordine che non ne ha diritto o più del suo totale.

Quando compili **tutti** gli input di dati dell'azione con le risposte del visitatore (vedi [Compilare gli input dell'azione](#compilare-gli-input-dell-azione)), intoCHAT prepara la conferma appena la procedura raggiunge il passo. L'agente mostra allora i valori e chiede il sì nella stessa risposta, l'azione viene eseguita al messaggio successivo del visitatore senza chiedere due volte, e viene eseguita esattamente con i valori che il visitatore ha visto, qualunque cosa passi l'AI. È la configurazione più prevedibile per tutto ciò che modifica dati. Quando alcuni input sono lasciati all'agente, valgono i passi descritti sopra.

Quando una chiamata confermata non riesce, riprovare con gli stessi valori non chiede di nuovo conferma al visitatore.

## Come l'agente segue una procedura

- L'agente lavora su una procedura alla volta. Se il visitatore fa una richiesta che corrisponde a un'altra procedura, interrompe quella attuale prima di avviare la successiva.
- Interrompe una procedura quando il visitatore cambia argomento, vuole fermarsi o la procedura non può proseguire, e poi continua normalmente.
- Fa un passo alla volta, in ordine, e non salta passi né inventa il risultato di un'azione. In una risposta può fare diversi passi, per esempio salvare il numero d'ordine, cercare l'ordine e controllare una condizione.
- Ciò che scrive il visitatore, comprese le sue risposte, viene trattato come dati. Non cambia mai i tuoi passi né il loro ordine.

Se modifichi una procedura mentre una chat è a metà, dopo il salvataggio la chat prosegue dal passo in cui si trova. Se quel passo è stato rimosso, se hai disattivato o eliminato la procedura o se supera il limite del tuo piano, la procedura termina al messaggio successivo del visitatore e l'agente continua normalmente.

## Cosa vedi

- **Why this answer** nella scheda **Conversations** elenca ogni passo sotto **Actions called** come "Procedure", con il nome della procedura e cosa è successo: **Started**, **Step 2 done**, **Step 3 done (yes)**, **Confirmation asked**, **Completed**, **Stopped** o **Stopped: procedure changed**. Le azioni chiamate da un passo compaiono come sempre. Vedi [Why this answer](/it/docs/conversations-and-dashboard#why-this-answer).
- In una trascrizione, l'intestazione elenca ogni procedura seguita dalla chat e fin dove è arrivata, per esempio "On step 2 of 6 (Ask the visitor)", "Completed" o "Stopped" con il motivo. Fai clic per vedere le risposte date dal visitatore.

## Limiti

- 15 passi per procedura. Nomi fino a 80 caratteri, **When to use** fino a 500, istruzioni e messaggi di chiusura fino a 1.000, domande, condizioni e valori degli input fino a 500.
- Ogni risposta può arrivare a 500 caratteri. All'agente vengono mostrate fino a 20 risposte di una procedura.
- Le procedure per agente dipendono dal tuo piano, fino a 50. Vedi [Piani](#piani).
- Le procedure non vengono usate nelle chat temporanee, perché lì non viene salvato nulla.
- Nel **Playground**, una chat salvata segue le procedure come la chat sul tuo sito e **chiama le tue azioni reali**. Fai le prove con un ordine di test o un endpoint di test.
- Anche le chat tramite la [REST API](/it/docs/rest-api) seguono le procedure.
- Un [agente duplicato](/it/docs/quick-start) riceve una copia delle procedure, con i passi di azione che puntano alle azioni della copia. Le conversazioni che le hanno seguite restano con l'originale.

## Consigli

- Tieni ogni passo piccolo: una domanda per ogni passo **Ask the visitor**.
- Metti una **Condition** subito dopo la ricerca da cui dipende, e descrivila in base a ciò che restituisce l'azione.
- Chiudi ogni ramo con un passo **End** che dica cosa deve sentirsi dire il visitatore.
- Attiva **Only inside procedures** e **Ask the visitor to confirm first** per tutto ciò che modifica dati, e compila tutti gli input con le risposte del visitatore, così conferma esattamente ciò che verrà eseguito.
- Prova la procedura nel **Playground**, poi apri **Why this answer** per vedere ogni passo.

## Esempio: una richiesta di rimborso

Con un'azione "Look up order" e un'azione "Refund order" contrassegnata con **Only inside procedures**, entrambe con un input di dati `orderId`:

1. **Ask the visitor**: "Qual è il tuo numero d'ordine?" Salva la risposta come `order_number`.
2. **Call an action**: Look up order. Compila `orderId` con `{{order_number}}`.
3. **Condition**: "L'ordine è stato trovato, è stato consegnato meno di 30 giorni fa e non è ancora stato rimborsato." Se sì, vai a **Next step**; se no, vai a **Step 6**.
4. **Call an action**: Refund order. Compila `orderId` con `{{order_number}}`. Seleziona **Ask the visitor to confirm first**.
5. **End**: "Comunica al visitatore che il rimborso è stato avviato e che il denaro arriva entro 5-10 giorni."
6. **Instruction**: "Spiega perché questo ordine non può essere rimborsato, usando ciò che ha restituito la ricerca, e offri di passare la conversazione al team."

**When to use**: "Il visitatore chiede la restituzione dei soldi per un ordine che ha effettuato. Non per domande generali sulla politica dei rimborsi."

A un visitatore che scrive "Voglio un rimborso per il mio ordine" viene chiesto il numero d'ordine. L'agente cerca l'ordine, lo controlla e dice al visitatore che rimborserà l'ordine 1042, chiedendogli di confermare. Il rimborso viene eseguito solo dopo la sua risposta.

## Passi successivi

- Configura le azioni chiamate dai tuoi passi: [Azioni API](/it/docs/api-actions).
- Raccogli invece più dati in una volta: [Moduli in chat](/it/docs/chat-forms).
- Passa una chat al tuo team: [Passaggio via email](/it/docs/handoff).
- Guarda cosa ha fatto l'agente: [Conversazioni e statistiche](/it/docs/conversations-and-dashboard).