Passaggi e trasferimenti degli agenti

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?#

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. 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.

Campi del passaggio#

Il grafico stesso è {"start_step": "<step id>", "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": <collected name or dotted path>, "op": <op>, "target": <literal>}:

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 è 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.

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.

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 <tool>_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:

Instrada in base a un campo del corpo con lookup_account_result.response.<field> 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:

[{"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 e il webhook di completamento della chiamata (telephony.complete / web.complete) includono gli stessi dati in steps_trace e collected_values. Entrambi sono assenti nelle chiamate senza passaggi.

"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:

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, incluse le sessioni per un agente salvato;
• le configurazioni inline restituite da un webhook di configurazione dinamica della chiamata. Un webhook che restituisce un agent_id usa i passaggi di quell'agente.

Limiti#

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 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.

{
  "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.

{
  "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à.

[
  {
    "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:

{
  "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:

{
  "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:

{
  "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#