---
title: "Passaggi e trasferimenti degli agenti"
description: "Suddividi un agente in passaggi con istruzioni, strumenti e valori raccolti propri e trasferisci le chiamate tra agenti durante la chiamata."
---
Un singolo prompt assegna al modello l'intero compito in una volta sola. I **passaggi** gli assegnano una fase della chiamata alla volta: ogni passaggio ha le proprie istruzioni, i propri strumenti, un'eventuale frase pronunciata parola per parola e i valori che deve raccogliere prima di proseguire. I **passaggi di consegna** consentono a un altro agente della tua organizzazione di subentrare a metà chiamata, con la trascrizione intatta, così il chiamante non deve mai ripetersi.
Ogni agente inizia come singolo prompt. Non cambia nulla finché non aggiungi passaggi o passaggi di consegna.
## Passaggi o singolo prompt?
| Usa i passaggi quando | Mantieni un singolo prompt quando |
| --- | --- |
| La chiamata ha fasi che devono avvenire in ordine: prima verifica, poi prenotazione. | La conversazione è aperta: FAQ, reception, assistenza generale. |
| È necessario acquisire un valore prima che l'agente prosegua. | Non è necessario raccogliere nulla in un ordine prestabilito. |
| Una regola non deve mai avere eccezioni, ad esempio "i chiamanti sotto i 18 anni vengono indirizzati a un tutore". | Il giudizio del modello è sufficiente per ogni diramazione. |
| Una ricerca deve essere eseguita in un punto preciso della chiamata. | Gli strumenti possono essere chiamati ogni volta che il chiamante lo richiede. |
| Una parte della chiamata appartiene a un agente diverso, con il proprio prompt e la propria voce. | Un'unica persona gestisce tutto. |
I passaggi non sono un albero telefonico con copione. All'interno di un passaggio, il modello gestisce la conversazione come farebbe con un singolo prompt. Il passaggio stabilisce su cosa sta lavorando, quali strumenti può usare e cosa gli serve prima di poterlo lasciare.
## Come viene creato un agente con passaggi
Quando un agente ha dei passaggi, il suo `prompt` contiene le **istruzioni condivise**: la persona e le regole applicabili a ogni passaggio. Ogni passaggio aggiunge le proprie istruzioni. A ogni turno, il modello vede le istruzioni condivise, il nome e le istruzioni del passaggio corrente e i valori raccolti finora.
Nel builder, passa l'agente da **Prompt singolo** a **Passaggi**. Otterrai una scheda per ogni passaggio con nome, istruzioni, frase da pronunciare, strumenti, valori raccolti e transizioni, un selettore di passaggi di consegna e un grafico di flusso in sola lettura dei passaggi. Tornando a un singolo prompt, viene proposto un prompt appiattito che unisce le istruzioni condivise e ogni passaggio.
Tramite l'API, `steps` e `handoffs` sono campi dell'[agente](/api-reference/agents). Come per ogni campo dell'agente, un `PATCH` li prepara nella bozza; `POST /v1/agents/{agent_id}/deploy` li pubblica. L'invio di `"steps": null` riporta l'agente a un singolo prompt. Le chiamate di test e **Parla** usano la bozza.
Il [copilot](/it/guides/ask-the-copilot) può creare passaggi a partire da una descrizione
("aggiungi un passaggio che verifica la data di nascita prima della prenotazione") e modificare un passaggio
senza toccare gli altri.
### Campi del passaggio
| Campo | Significato |
| --- | --- |
| `id` | Obbligatorio. Lettere minuscole, cifre e trattini bassi, deve iniziare con una lettera, fino a 40 caratteri. Univoco all'interno dell'agente. |
| `name` | Nome visualizzato obbligatorio, da 1 a 80 caratteri. |
| `instructions` | Obbligatorio, fino a 20.000 caratteri. Supporta le [variabili di chiamata](/it/guides/call-variables) `{{var}}`, come `prompt`. |
| `say` | Frase facoltativa pronunciata parola per parola quando si entra nel passaggio, fino a 1.000 caratteri. Supporta `{{var}}`. |
| `tools` | `null` assegna al passaggio ogni strumento collegato all'agente. Un elenco limita il passaggio a tali strumenti, per nome. Le azioni integrate come `end_call` e `transfer_call` seguono le impostazioni dell'agente in ogni passaggio. |
| `collect` | Fino a 20 valori raccolti dal passaggio. Ognuno ha un `name`, un `type`, una `description` e `required` (predefinito `true`). |
| `on_enter_tool` | Nome dello strumento facoltativo, chiamato automaticamente quando si entra nel passaggio. Vedi [Passaggi webhook](#webhook-steps). |
| `transitions` | Elenco ordinato delle possibili destinazioni successive del passaggio. Vedi [Transizioni](#transitions). |
| `global_when` | Facoltativo. Rende il passaggio raggiungibile da qualsiasi passaggio. Vedi [Passaggi globali](#global-steps). |
| `voice` | ID voce facoltativo per questo passaggio. Ignorato quando l'agente utilizza una configurazione vocale personalizzata. |
Il grafico stesso è `{"start_step": "", "steps": [...]}`. La chiamata
inizia in `start_step`.
## Transizioni
Ogni transizione ha `to`, un ID di passaggio, ed esattamente uno dei seguenti:
- **`when`**: linguaggio naturale, e **decide il modello**. L'agente riceve uno
strumento `go_to_step` integrato che elenca i passaggi verso cui può spostarsi, con ogni
`when` come motivo per sceglierlo.
- **`condition`**: una regola sui valori raccolti, e **decide il codice**. Il modello
non può ignorarla né aggirarla parlando.
- **`"always": true`**: prosegui senza un controllo. Il codice decide per primo: non appena
si entra in un passaggio, oppure quando i relativi valori obbligatori sono raccolti, prevale la prima
transizione `condition` o `always` corrispondente, prima che il modello possa scegliere
un `when`. Quindi inserisci `always` dopo le condizioni come alternativa,
oppure da solo per concatenare direttamente un passaggio a quello successivo. Un passaggio con `always` non
attende mai una scelta `when`.
Una `condition` è `{"value": , "op": , "target": }`:
| `op` | Vero quando il valore |
| --- | --- |
| `eq`, `ne` | è uguale o diverso da `target` |
| `lt`, `lte`, `gt`, `gte` | è minore di, al massimo, maggiore di o almeno `target` |
| `in`, `not_in` | è, o non è, uno dei valori nell'elenco `target` |
| `exists`, `missing` | è stato, o non è stato, raccolto (nessun `target`) |
`eq`, `ne`, `in` e `not_in` confrontano il testo senza distinzione tra maiuscole e minuscole dopo aver rimosso
gli spazi. I numeri vengono confrontati come numeri e le date come stringhe `YYYY-MM-DD`. Un valore
che non è mai stato raccolto rende ogni op falso, tranne `missing`.
Scrivi `when` e `global_when` come una condizione, ad esempio "Il chiamante vuole
prenotare un appuntamento", non come qualcosa da dire. L'agente li vede come note interne
di instradamento e riceve l'istruzione di non leggerli mai ad alta voce né menzionare che sta
cambiando passaggio.
Quando il modello chiama `go_to_step`:
1. Ogni valore `required` nel passaggio deve essere presente. Se ne manca uno, al
modello viene indicato quale e lo chiede al chiamante.
2. I valori vengono archiviati.
3. Le transizioni `condition` e `always` vengono controllate in ordine. Prevale la prima
corrispondenza.
4. Altrimenti l'agente passa al passaggio scelto dal modello.
5. Se non corrisponde nulla e il modello non ha indicato alcun passaggio, l'agente rimane dov'è.
Un salto a un [passaggio globale](#global-steps) è l'eccezione: il chiamante ha cambiato
argomento, quindi procede anche quando nel passaggio corrente mancano ancora valori obbligatori,
e prima che vengano controllate le condizioni di quel passaggio.
Le transizioni `condition` e `always` vengono controllate anche ogni volta che si entra in un passaggio,
quindi una sequenza di passaggi decisi dal codice viene eseguita tutta insieme. La catena si interrompe:
- in un passaggio già visitato in questa esecuzione;
- dopo 8 salti;
- in un passaggio che ha ancora valori obbligatori da raccogliere, a meno che il passaggio non abbia un
`on_enter_tool` (un passaggio webhook instrada sempre in base al proprio risultato).
Viene pronunciata solo la riga `say` del passaggio in cui la catena si interrompe.
Un passaggio senza transizioni è **terminale**. L'agente termina lì e chiude
o trasferisce la chiamata con le normali azioni integrate.
## Raccolta dei valori
Elenca ciò di cui un passaggio ha bisogno in `collect`. Il modello passa i valori quando chiama
`go_to_step` e restano disponibili per il resto della chiamata.
| `type` | Contiene |
| --- | --- |
| `string` | Qualsiasi testo |
| `number` | Un numero |
| `boolean` | `true` o `false` |
| `date` | Una data come `YYYY-MM-DD` |
I valori raccolti sono contenuto della chiamata. Vengono visualizzati nella chiamata accanto alla
trascrizione e seguono le stesse regole di conservazione, eliminazione e oscuramento. Quando la
registrazione delle chiamate dell'agente è disattivata, i valori raccolti non vengono né archiviati
né inviati nei webhook; la cronologia del passaggio rimane comunque disponibile. Vedi
[Dove visualizzarlo in una chiamata](#where-to-see-it-on-a-call).
## Frasi say
`say` viene pronunciato esattamente come scritto quando l'agente entra nel passaggio. Il modello prosegue quindi nel nuovo passaggio nella stessa risposta, sapendo che la frase è stata appena pronunciata, quindi non la ripete. Usa `say` per saluti, informative obbligatorie e formulazioni fisse, e lascia il resto della risposta al modello.
Il `say` del passaggio iniziale è la frase di apertura dell'agente quando parla per primo, dopo eventuali annunci di consenso. Quando chi chiama parla per primo, apre la prima risposta dell'agente a una persona, mai a un IVR o a un messaggio di segreteria telefonica.
Il `say` di un passaggio non viene pronunciato di nuovo quando la chiamata vi ritorna tramite `__previous__` o un passaggio di ritorno. Scrivilo come dovrebbe suonare: scrivi per esteso tutto ciò che la voce potrebbe interpretare erroneamente. Le frasi say supportano le variabili di chiamata `{{var}}`, ma non i valori raccolti.
## Passaggi webhook
Imposta `on_enter_tool` su uno degli strumenti dell'agente e verrà eseguito non appena si entra nel passaggio, senza attendere il modello. I suoi argomenti sono i valori raccolti i cui nomi corrispondono ai nomi dei parametri dello strumento. Il risultato viene memorizzato come valore raccolto denominato `_result`, troncato a 4 KB, e le transizioni `condition` e `always` del passaggio vengono controllate immediatamente, così la ricerca può instradare la chiamata in base al proprio risultato.
Il valore memorizzato contiene due campi:
| Campo | Contiene |
| --- | --- |
| `status` | Il codice di stato HTTP restituito dall'endpoint. |
| `response` | Il corpo della risposta. |
Instrada in base a un campo del corpo con `lookup_account_result.response.` e in base al codice di stato con `lookup_account_result.status`.
La ricerca viene eseguita per un massimo di 8 secondi, oppure per il timeout dello strumento se è più breve. Se richiede più di 3 secondi, l'agente pronuncia una breve frase affinché chi chiama non resti in silenzio. Se l'endpoint restituisce uno stato pari o superiore a 400, oppure non risponde in tempo, l'agente comunica a chi chiama che non ha potuto verificarlo in questo momento e prosegue con ciò che può fare.
## Passaggi globali
Un passaggio con `global_when` può essere raggiunto da qualsiasi passaggio ogni volta che quella descrizione è soddisfatta. Il modello decide, come con `when`. Usalo per argomenti che chi chiama può sollevare in qualsiasi momento: domande sulla fatturazione, una richiesta di parlare con una persona, un reclamo.
Una transizione con `"to": "__previous__"` in un passaggio globale riporta la chiamata al passaggio attivo prima di esso, così chi chiama riprende dal punto in cui si era interrotto. Il passaggio riprende: il relativo `on_enter_tool` non viene eseguito di nuovo, il relativo `say` non viene ripetuto e l'agente lo continua senza ricominciare da capo.
## Passaggi ad altri agenti
`handoffs` elenca gli altri agenti della tua organizzazione che possono prendere in carico la chiamata:
```json
[{"agent_id": 413, "when": "The caller asks about billing or a refund"}]
```
L'agente riceve uno strumento `hand_off` integrato con questi agenti e motivazioni. Come per le transizioni, ogni `when` è una nota interna di instradamento e non viene mai letta ad alta voce.
Quando passa la chiamata, l'agente pronuncia una breve frase per indicare al chiamante dove verrà indirizzato, ad esempio "Certo, la passo al nostro team di fatturazione", con la propria voce. Poi il prompt, i passaggi, gli strumenti e la voce dell'agente di destinazione prendono il controllo e la chiamata continua con la stessa trascrizione. Il nuovo agente si presenta brevemente e risponde all'ultima richiesta del chiamante; non annuncia un trasferimento. Da quel momento è disponibile la knowledge base dell'agente di destinazione.
La prima volta che una chiamata raggiunge un agente, inizia dal relativo `start_step`: viene eseguito `on_enter_tool` del passaggio e viene pronunciato il relativo `say`. Quando la chiamata torna a un agente già visitato, quell'agente riprende dal passaggio in cui si trovava, senza eseguire `on_enter_tool`, ripetere il proprio `say` o presentarsi di nuovo. I valori raccolti sono condivisi da tutti gli agenti della chiamata.
- Un agente di destinazione deve appartenere alla stessa organizzazione e un agente non può passare la chiamata a sé stesso.
- Tutto ciò che riguarda il livello della chiamata resta associato all'agente che ha risposto: prodotto, lingue, chi parla per primo, segreteria telefonica, annuncio del consenso e ogni altra impostazione della chiamata.
- Gli agenti di destinazione possono effettuare ulteriori passaggi, anche all'indietro. Una chiamata può raggiungere fino a 8 agenti.
- Una chiamata di test esegue la bozza dell'agente che stai testando. Gli agenti a cui passa la chiamata eseguono le loro versioni pubblicate.
- Se due agenti hanno uno strumento con lo stesso nome e definizioni diverse, per la chiamata ne viene mantenuto uno solo e prevale sempre quello dell'agente che ha risposto. Il builder ti avvisa quando salvi.
- Un agente può avere passaggi ad altri agenti senza passaggi. Viene usato l'intero prompt così com'è.
`go_to_step` e `hand_off` sono riservati agli agenti con passaggi o passaggi ad altri agenti, quindi i tuoi strumenti non possono usare questi nomi.
## Dove visualizzarlo in una chiamata
Apri la chiamata in **Cronologia chiamate**. Una cronologia dei passaggi accanto alla trascrizione mostra ogni passaggio in cui è entrata la chiamata e il motivo, insieme ai valori raccolti.
L'[oggetto chiamata](/api-reference/calls#retrieve-a-call) e il webhook di completamento della chiamata ([`telephony.complete` / `web.complete`](/it/webhooks/call-complete)) includono gli stessi dati in `steps_trace` e `collected_values`. Entrambi sono assenti nelle chiamate senza passaggi.
```json
"steps_trace": [
{"t_ms": 0, "agent": "a412", "step": "greet", "via": "start"},
{"t_ms": 51230, "agent": "a412", "step": "verify", "via": "model"},
{"t_ms": 98410, "agent": "a412", "step": "minor", "via": "condition"}
],
"collected_values": {"full_name": "Dana Reyes", "dob": "2010-04-02", "age": 15}
```
`agent` è `a` seguito dall'ID dell'agente. `via` indica cosa ha spostato la chiamata:
| `via` | Significato |
| --- | --- |
| `start` | La chiamata è iniziata in questo passaggio. |
| `model` | Il modello ha scelto il passaggio tramite `go_to_step`, un `when` o un `global_when`. |
| `condition` | Ha trovato corrispondenza una transizione `condition` o `always`. |
| `on_enter` | Ha trovato corrispondenza una transizione nel risultato di un passaggio webhook. |
| `handoff` | Un altro agente ha preso il controllo. |
## Dove vengono eseguiti i passaggi
I passaggi vengono eseguiti nativamente su **Spark**, **Bolt** e ogni prodotto **Storm**, nelle chiamate in entrata, in uscita e delle campagne, nelle chiamate di test e nelle chiamate web e widget.
Ovunque altro l'agente continua a funzionare, solo senza la struttura: esegue un prompt appiattito che unisce, nell'ordine, le istruzioni condivise e ogni passaggio. Questo include:
- i prodotti Bolt sperimentali;
- le sessioni [Realtime](/it/guides/use-with-openai-realtime), incluse le sessioni per un agente salvato;
- le configurazioni inline restituite da un webhook di [configurazione dinamica della chiamata](/it/guides/dynamic-call-config). Un webhook che restituisce un `agent_id` usa i passaggi di quell'agente.
## Limiti
| Limite | Valore |
| --- | --- |
| Passaggi per agente | 100 |
| Valori raccolti per passaggio | 20 |
| Destinazioni di handoff per agente | 8 |
| Agenti raggiungibili in una chiamata | 8 |
| Dimensione del JSON `steps` | 200 KB |
| `instructions` del passaggio | 20.000 caratteri |
| Riga `say` | 1.000 caratteri |
| Risultato `on_enter_tool` archiviato | 4 KB |
Un salvataggio che viola una regola restituisce `400` con il percorso del campo errato, ad esempio `steps.steps[2].transitions[0].to`. I nomi degli strumenti in `tools` e `on_enter_tool` devono corrispondere a strumenti collegati all'agente.
Le lingue per singolo passaggio, i passaggi con copione che saltano il modello e i valori raccolti all'interno delle righe say non sono supportati.
## Agenti importati
L'[importazione](/it/guides/import-agents) da Retell, Bland, Vapi o ElevenLabs
converte agenti multi-prompt, flussi, percorsi e workflow in passaggi, e
squadre e trasferimenti di agenti in handoff tra gli agenti importati. La
pagina di revisione mostra entrambi prima dell'importazione.
## Esempio: accettazione odontoiatrica
Tre passaggi in ordine: saluta, raccogli i dati del paziente, prenota.
```json
{
"prompt": "You are Ava, the front desk assistant at Acme Dental. Be warm and brief. Ask one question at a time.",
"steps": {
"start_step": "greet",
"steps": [
{
"id": "greet",
"name": "Greeting",
"instructions": "Greet the caller and ask how you can help.",
"say": "Thanks for calling Acme Dental, this is Ava. How can I help you today?",
"tools": null,
"collect": [],
"transitions": [
{"to": "details", "when": "The caller wants to book an appointment"}
]
},
{
"id": "details",
"name": "Patient details",
"instructions": "Ask for the caller's full name, date of birth and the reason for the visit. Read the date of birth back and ask the caller to confirm it.",
"tools": null,
"collect": [
{"name": "full_name", "type": "string", "description": "Caller's full name", "required": true},
{"name": "dob", "type": "date", "description": "Date of birth", "required": true},
{"name": "reason", "type": "string", "description": "Reason for the visit", "required": true},
{"name": "new_patient", "type": "boolean", "description": "First visit to the practice", "required": false}
],
"transitions": [
{"to": "book", "when": "The caller has confirmed their details"}
]
},
{
"id": "book",
"name": "Book",
"instructions": "Offer the two earliest open slots from book_slot and book the one the caller picks. Confirm the date and time, then say goodbye and end the call.",
"tools": ["book_slot"],
"collect": [],
"transitions": []
}
]
}
}
```
Preparalo con `PATCH /v1/agents/{agent_id}`, provalo con **Parla**, quindi distribuiscilo.
Il passaggio `details` non può passare alla prenotazione finché non vengono raccolti nome, data di nascita e motivo; `new_patient` è facoltativo.
## Esempio: un ramo con limite di età
Il modello può parlare con chiunque, ma il codice decide chi può prenotare. Raccogli l'età, quindi instrada in base a essa prima di considerare la scelta del modello.
```json
{
"id": "verify",
"name": "Verify age",
"instructions": "Ask for the caller's age.",
"tools": null,
"collect": [
{"name": "age", "type": "number", "description": "Caller's age in years", "required": true}
],
"transitions": [
{"to": "guardian", "condition": {"value": "age", "op": "lt", "target": 18}},
{"to": "book", "when": "The caller has given their age"}
]
}
```
Un chiamante che dice quindici passa a `guardian`, indipendentemente da ciò che decide il modello.
Tutti gli altri passano a `book`. Entrambi sono normali passaggi in altre parti del grafico.
## Esempio: passaggio webhook di ricerca dell'account
Il chiamante fornisce un numero di account, la ricerca viene eseguita entrando nel passaggio successivo
e il risultato seleziona il percorso. I passaggi `not_found`, `collections` e `support`
sono omessi per brevità.
```json
[
{
"id": "identify",
"name": "Identify",
"instructions": "Ask for the caller's account number and read it back digit by digit.",
"tools": null,
"collect": [
{"name": "account_number", "type": "string", "description": "Account number", "required": true}
],
"transitions": [
{"to": "lookup", "when": "The caller has confirmed their account number"}
]
},
{
"id": "lookup",
"name": "Look up account",
"instructions": "Tell the caller what you found on their account and ask how you can help.",
"tools": ["lookup_account"],
"collect": [],
"on_enter_tool": "lookup_account",
"transitions": [
{"to": "not_found", "condition": {"value": "lookup_account_result.response.found", "op": "eq", "target": false}},
{"to": "collections", "condition": {"value": "lookup_account_result.response.account_status", "op": "in", "target": ["past_due", "suspended"]}},
{"to": "support", "when": "The caller needs help with an active account"}
]
}
]
```
`lookup_account` riceve `account_number` perché il suo parametro ha quel
nome. Se il corpo della risposta contiene `"found": false`, la chiamata passa a
`not_found`. Se `account_status` è `past_due` o `suspended`, passa a
`collections`. Un account attivo rimane in `lookup`, dove il modello fornisce assistenza e
prosegue verso `support`. Per inviare una ricerca non riuscita a un passaggio dedicato, aggiungi
prima le condizioni sullo stato: una risposta di errore memorizza il relativo codice di stato, quindi
`{"value": "lookup_account_result.status", "op": "gte", "target": 400}`
lo intercetta, mentre un timeout o una mancata risposta memorizza `"error"`, quindi
`{"value": "lookup_account_result.status", "op": "eq", "target": "error"}`
intercetta quel caso.
## Esempio: dalla reception alla fatturazione
Due agenti. La reception (agente `412`) risponde a ogni chiamata e inoltra le domande
sulla fatturazione a un agente di fatturazione (agente `413`) con il proprio prompt, strumenti e voce.
Sulla reception:
```json
{
"handoffs": [
{"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"}
]
}
```
Sull'agente di fatturazione, affinché possa restituire il chiamante:
```json
{
"handoffs": [
{"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"}
]
}
```
La reception pronuncia una breve frase come "La metto in contatto con il nostro team di fatturazione",
quindi l'agente di fatturazione si presenta e riprende la conversazione
dal punto in cui l'aveva lasciata la reception. Quando la fatturazione restituisce la chiamata, la reception riprende
dal punto in cui si trovava, senza salutare nuovamente il chiamante. Il prodotto della chiamata,
le lingue, l'annuncio di consenso e le altre impostazioni della chiamata rimangono alla
reception, perché ha risposto lei.
Se la fatturazione necessita solo delle proprie istruzioni e non di un proprio agente, usa invece
un passaggio globale sulla reception. Quando la domanda riceve risposta, la chiamata torna
al passaggio in cui si trovava il chiamante:
```json
{
"id": "billing",
"name": "Billing questions",
"instructions": "Answer questions about bills and payments. Offer to send a payment link by email.",
"tools": null,
"collect": [],
"transitions": [
{"to": "__previous__", "when": "The billing question is answered"}
],
"global_when": "The caller asks about a bill or payment at any point"
}
```
## Passaggi successivi
Scrivi istruzioni condivise e istruzioni per i passaggi efficaci al telefono.
Crea gli strumenti chiamati dai tuoi passaggi e passaggi webhook.
Esegui gli stessi scenari su ogni ramo prima del deploy.
Ogni campo dell'agente, bozza e deploy.