Procedure | ElevenLabs Documentation

Panoramica

Una procedura contiene istruzioni per un’attività specifica. Ogni procedura ha un trigger che descrive quando si applica e un contenuto che descrive cosa fare. Quando una conversazione corrisponde al trigger, l’agente carica la procedura.

Usa le procedure quando l’agente deve gestire molte attività distinte. Un esempio è un agente di assistenza clienti, in cui ogni procedura copre un tipo di richiesta: rimborsi, verifica dell’identità, recupero dell’account o risoluzione dei problemi di connessione.

Scheda Procedure nella dashboard
dell'agente

Tipi di procedure

Esistono due tipi di procedure:

Le procedure in forma libera sono scritte come istruzioni in linguaggio naturale che l’agente interpreta e adatta alla situazione.
Le procedure strutturate sono un elenco ordinato di passaggi tipizzati che l’agente esegue sempre nello stesso modo.

Puoi usare entrambi i tipi sullo stesso agente. L’agente sceglie la procedura pertinente in base al relativo trigger, indipendentemente dal tipo.

Le procedure possono richiamarsi tra loro. Una procedura in forma libera richiama un’altra procedura con un riferimento inline, mentre una procedura strutturata richiama un’altra procedura strutturata con un passaggio Sottoprocedura. Un modello comune consiste nel mantenere la gestione aperta in una procedura in forma libera e delegare a una procedura strutturata le parti che devono essere eseguite sempre nello stesso modo.

Un agente può avere procedure, un workflow o entrambi. Quando sono presenti entrambi, ogni procedura è disponibile da ogni punto del workflow; una procedura non può essere limitata a nodi specifici del workflow. La maggior parte degli agenti si basa su un approccio o sull’altro, ma i due possono essere combinati.

Quando usare le procedure

Ogni agente dispone di un system prompt. Procedure e workflow sono due modi per aggiungere struttura, e un agente può usare entrambi. Scegli un punto di partenza in base a quanto può variare la conversazione.

Requisito	Usa	Perché
Semplice agente proof of concept	Solo system prompt	È il modo più rapido per configurare e iterare, ma un unico prompt diventa difficile da gestire man mano che l’ambito dell’agente si amplia.
Attività in cui l’agente può adattare formulazione e ordine	Procedura in forma libera	Mantiene l’intera conversazione nel contesto di un unico LLM, così l’agente adatta formulazione e ordine e può gestire sviluppi imprevisti. Usa una parte maggiore della finestra di contesto.
Attività i cui passaggi devono essere eseguiti sempre nello stesso modo	Procedura strutturata	Ogni passaggio viene eseguito nell’ordine impostato, sempre nello stesso modo, e puoi definirlo come un breve elenco di passaggi.
Controllo completo su ramificazioni complesse e casi limite	Workflow	Viene eseguito come un grafo di sottoagenti che progetti e colleghi tu, con controllo completo sulle ramificazioni e sul modello usato in ogni passaggio.

Le procedure in forma libera sono la scelta predefinita. Sono le più rapide da scrivere, si leggono come un documento quindi possono essere gestite anche da team non tecnici e l’agente può riprendersi quando una conversazione esce dal copione. Scegli una procedura strutturata quando il costo di un passaggio saltato o riordinato è elevato, ad esempio per autenticazione, escalation o una transazione finanziaria. Scegli un workflow quando ti serve una logica di instradamento o il controllo del modello per singolo passaggio, che nessuno dei due tipi di procedura offre.

Gestire le procedure

La dashboard è il modo consigliato per creare procedure. Usa la CLI o l’API per gestire le procedure a livello programmatico o integrarle negli strumenti di deployment.

Crea dalla dashboard

Gestisci dalla CLI

Gestisci tramite l'API

Apri l’agente nella dashboard, quindi seleziona Procedure. Usa + per creare una procedura in forma libera o strutturata. Puoi raggruppare le procedure in cartelle dallo stesso menu. Consulta le procedure in forma libera e le procedure strutturate per indicazioni sulla creazione.

Scegliere le procedure per conversazione

Per impostazione predefinita, ogni conversazione può usare tutte le procedure dell’agente e l’agente carica una procedura soltanto dopo che la conversazione corrisponde al relativo trigger. Spesso la tua applicazione sa già di più prima dell’inizio della conversazione: chi è l’utente, in quale regione si trova o per quale motivo ha chiamato. Passa gli ID delle procedure nei dati client di avvio della conversazione per usare queste informazioni. Decidi quali procedure può usare l’agente e quali deve seguire fin dal primo turno.

Campo	Cosa fa	Perché usarlo
`procedure_ids`	Limita la conversazione a queste procedure. Un array vuoto disabilita tutte le procedure dell’agente.	Fornisci a ogni utente soltanto le procedure che gli si applicano, ad esempio nascondi le procedure dell’account a un utente che non ha effettuato l’accesso. Usalo anche quando le procedure hanno trigger simili che non puoi evitare, ad esempio una procedura di rimborso per regione. Passa soltanto la regione dell’utente, così l’agente non potrà seguire la procedura di un’altra regione.
`start_procedure_ids`	Avvia queste procedure in forma libera insieme alla conversazione, così l’agente le segue fin dal primo turno. Accetta fino a cinque ID.	Rispondi più rapidamente quando conosci già l’attività dell’utente, ad esempio dalla scelta in un menu IVR, dalla pagina che ospita il widget o dai dati CRM.

Una procedura in start_procedure_ids è già caricata quando l’utente parla per la prima volta, quindi l’agente salta la chiamata LLM che la caricherebbe. Qualsiasi procedura attiva resta nel prompt a ogni turno, indipendentemente dal fatto che sia stata avviata dall’agente o dalla tua applicazione. Una procedura avviata di cui la conversazione non ha mai bisogno aggiunge comunque il proprio contenuto a ogni turno, quindi avvia soltanto le procedure che è probabile vengano usate nella conversazione.

Consenti la selezione delle procedure

L’override Procedure è disattivato per impostazione predefinita. Abilitalo su ogni agente che deve accettare ID delle procedure dal client.

Dashboard

CLI

SDK

Apri l’agente nella dashboard, seleziona la scheda Sicurezza e abilita l’override Procedure.

Passa gli ID all’avvio della conversazione

Se l’agente non ha l’override Procedure abilitato, oppure se un ID non è valido, la conversazione non si avvia.

Ottieni gli ID delle procedure da Elenca procedure. Aggiungi procedure_ids, start_procedure_ids o entrambi ai dati client di avvio della conversazione:

Payload di avvio della conversazione

{
  "type": "conversation_initiation_client_data",
  "procedure_ids": [
    "agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b",
    "agtprc_2301k8f3xq9zfa7tkrqs6m4bdn5e",
    "agtprc_7801k8f3yt4mfzh2xbq9d0vcpw1r"
  ],
  "start_procedure_ids": ["agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b"]
}

L’agente avvia la conversazione con la prima procedura già in esecuzione. Può comunque avviare le altre due quando la conversazione corrisponde ai relativi trigger.

Gli SDK di conversazione Python e JavaScript non inviano procedure_ids né start_procedure_ids. Per usare questi campi, invia autonomamente il messaggio di avvio tramite WebSocket.

Entrambi i campi seguono queste regole:

Ogni ID in procedure_ids deve appartenere all’agente. Se una procedura selezionata richiama sottoprocedure, includi anche queste ultime.
Ogni ID in start_procedure_ids deve essere una procedura in forma libera. Quando passi anche procedure_ids, ogni ID deve trovarsi anche in quell’elenco.
procedure_ids si applica soltanto all’agente con cui inizia la conversazione. Non si applica dopo un trasferimento dell’agente.
Le procedure avviate contano ai fini delle cinque procedure attive indicate nelle Limitazioni. La cronologia della conversazione registra ciascuna come chiamata allo strumento start_procedure.

Limitazioni

Il contenuto di una procedura è limitato a 50.000 caratteri.
L’agente mantiene nel contesto le cinque procedure avviate più di recente. Quando ne vengono avviate di più in una conversazione, il contenuto, gli strumenti inline e i documenti della knowledge base delle procedure in forma libera meno recenti vengono rimossi dal prompt. Mantieni le procedure mirate e usa sottoprocedure affinché poche siano attive contemporaneamente.
Non puoi modificare il tipo di una procedura dopo averla creata. Per convertire tra forma libera e strutturata, crea una nuova procedura e aggiorna tutti i riferimenti a essa.
Le procedure appartengono a un singolo agente. Non possono essere condivise tra agenti né archiviate come risorse a livello di workspace.
La duplicazione di un agente ne copia le procedure anziché condividerle. Le copie ricevono nuovi ID procedura, quindi i riferimenti nell’agente duplicato devono usare quei nuovi ID.
Le procedure non possono essere limitate a nodi specifici del workflow. Quando un agente ha entrambi, ogni procedura è disponibile da ogni nodo.
Le procedure strutturate non possono fare riferimento a documenti della knowledge base.