> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Procedure in formato libero ## Panoramica Una procedura in forma libera descrive un'attività in linguaggio semplice e naturale. L'agente interpreta le istruzioni e adatta la formulazione e l'ordine alla situazione. Una procedura in forma libera può chiamare strumenti (inclusi strumenti di sistema come terminare una chiamata), consultare documenti della knowledge base e concatenarsi ad altre procedure. ## Quando usare una procedura in forma libera Usa una procedura in forma libera quando l'agente può adattare formulazione e ordine alla situazione e vuoi crearla rapidamente in linguaggio naturale. Per scoprire come si confronta con procedure strutturate, workflow e prompt di sistema, consulta [Quando usare le procedure](/docs/it/eleven-agents/customization/procedures#when-to-use-procedures). ## Anatomia di una procedura Ecco una procedura di rimborso nell'editor: ![Esempio di procedura di rimborso](/docs/_fern-img/e1264b7a4f94403453087d30ef0894e72d412ba69378e6b8cb1b675e53e887b7.webp) Una procedura ha due parti principali: un trigger e il contenuto. Entrambe possono contenere riferimenti inline ad altre risorse, mostrati nello screenshot sopra come tag con icone a forma di chiave inglese. Ogni procedura ha anche un nome visualizzato nella dashboard. ### Nome Una breve etichetta che identifica la procedura nella dashboard. Il nome non viene mai inviato all'LLM, quindi non influisce sul comportamento dell'agente. ### Trigger Una descrizione di quando l'agente deve usare questa procedura, ad esempio *Quando l'utente chiede di rimborsare un ordine*. Lascia vuoto il trigger solo quando crei una [sottoprocedura](#sub-procedures). ### Contenuto Il corpo della procedura, scritto in markdown. Il contenuto descrive cosa deve fare l'agente: porre una domanda, cercare un ordine, chiamare uno strumento o terminare la chiamata. Può essere una sequenza numerata di passaggi da seguire oppure una guida generale per la situazione. Ogni passaggio o indicazione può essere una singola frase (*Chiedi all'utente l'ID dell'ordine*) o un breve paragrafo che spiega cosa fare e perché. Usa passaggi numerati per azioni sequenziali ed elenchi puntati per requisiti o sottoelementi all'interno di un passaggio. ### Riferimenti inline Le procedure possono fare riferimento inline a diversi tipi di risorse: * Strumenti (ad esempio cercare un ordine, addebitare una carta, terminare la chiamata, trasferire a un operatore) * Documenti della knowledge base * Altre procedure Usa riferimenti inline ogni volta che un passaggio richiede all'agente di usare uno strumento, un documento della knowledge base o un'altra procedura. I riferimenti collegano automaticamente la risorsa alla procedura, così l'agente può usarla. Anche le menzioni in testo normale (come *usa qui lo strumento calcolatrice*) funzionano, ma solo se la risorsa è già collegata all'agente. Inserisci un riferimento digitando `/` nel trigger o nel contenuto e scegliendo la risorsa dal menu slash. I riferimenti vengono visualizzati come tag selezionabili nell'editor. Fai clic su un tag per aprire la risorsa sottostante e verificarne la configurazione. Quando scrivi contenuti in forma libera tramite l'API, inserisci i riferimenti con la seguente sintassi: ```text focus={1-5} [tool id="tool_abc123"] [kb id="kb_abc123"] [procedure id="agtprc_abc123"] [system_tool id="end_call"] {{customer_id}} ``` Un riferimento inline a una procedura deve usare una procedura dello stesso agente. Consulta [Limitazioni](/docs/it/eleven-agents/customization/procedures#limitations) per informazioni sull'ambito dell'agente e sul comportamento della duplicazione. Un riferimento nel trigger consente alla procedura di attivarsi in base all'output di una risorsa, ad esempio *Quando `get_user` restituisce il livello 'gold'*. Un riferimento nel contenuto indica all'agente di richiamare o consultare la risorsa in quel passaggio. ![Menu slash nell'editor delle procedure](/docs/_fern-img/8625ffec0f5584619e6ccb97720fd86f2e8d3cd0061308ad87b57f176e5535e3.webp) Se una risorsa a cui viene fatto riferimento viene eliminata in seguito, oppure se il tuo account perde l'accesso, il tag viene visualizzato come non valido. Il badge **Errori** nella parte superiore dell'editor elenca questi riferimenti: *non valido* se la risorsa non esiste più oppure *non disponibile* se esiste ma il tuo account non ha accesso. Apri il badge per vedere quale passaggio è interessato e correggi o rimuovi il riferimento. ![Finestra di dialogo Errori che elenca i riferimenti non validi](/docs/_fern-img/e9ec6b19be2992da80a726883baf53265a5d5b38621373cd7e60375c944674cd.webp) ## Sottoprocedure Una sottoprocedura ha un trigger vuoto. L'agente può eseguirla solo da un'altra procedura che vi fa riferimento. Usa le sottoprocedure per [condividere passaggi](#composing-procedures) all'interno di un agente e ridurre il numero di procedure disponibili contemporaneamente. Assegna un trigger alla procedura di ingresso, fai riferimento alle sottoprocedure correlate dal suo contenuto e lascia vuoti i relativi trigger. Una sottoprocedura di escalation può contenere i passaggi per trasferire la conversazione a un operatore. Fai riferimento a essa dalle procedure di rimborso e annullamento e lascia vuoto il suo trigger. L'agente può eseguire l'escalation come passaggio di entrambe le procedure, ma al di fuori di queste la sottoprocedura rimane non disponibile. ## Importare da un documento Puoi iniziare da una procedura operativa standard (SOP) esistente. Scegli **Da SOP** nel menu **+** dell'elenco delle procedure, quindi carica un file. Formati supportati: `PDF`, `DOCX`, `TXT`, `MD`, `HTML`, `EPUB`. I file devono avere dimensioni pari o inferiori a 20 MB. L'importatore analizza il documento, identifica fino a 10 procedure distinte e crea una bozza per ciascuna con nome, trigger e contenuto generati. Apri ogni bozza per perfezionarla. Se il documento contiene più di 10 SOP, suddividilo in file più piccoli prima di caricarlo. ![Finestra di dialogo per il caricamento di SOP](/docs/_fern-img/716601fc90dea757e23971e5aabe063e6a66fc0f75878247dc9f1fc3011f5197.webp) ## Gestire una procedura in forma libera #### Crea dalla dashboard Apri il tuo agente nella [dashboard](https://elevenlabs.io/app/agents), quindi seleziona **Procedure**. Usa **+** per creare una procedura in forma libera. Aggiungi un trigger e scrivi le istruzioni nell' editor dei contenuti, quindi pubblica le modifiche dell'agente. #### Gestisci tramite l'API Le procedure in forma libera archiviano il markdown in `content`. ### Prerequisiti * Una chiave API di ElevenLabs nella variabile d'ambiente `ELEVENLABS_API_KEY`. * `agent_id` e `branch_id` di destinazione. Consulta [Versionamento dell'agente](/docs/it/eleven-agents/operate/versioning) per le operazioni sui branch. * Versione `2.60.0` o successiva del pacchetto Python `elevenlabs` o del pacchetto JavaScript `@elevenlabs/elevenlabs-js`. Le bozze delle procedure sono [per utente, per branch](/docs/it/eleven-agents/operate/versioning#drafts). La pubblicazione salva le modifiche alle procedure in una nuova versione dell'agente su quel branch. Le bozze degli altri utenti non vengono modificate. ### Crea una bozza ```python focus={1,5-15} from elevenlabs import CreateProcedureRequestModel, ElevenLabs elevenlabs = ElevenLabs() procedure = elevenlabs.conversational_ai.agents.procedures.create( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t", request=CreateProcedureRequestModel( name="Refund request", type="free_form", trigger="When the user asks to refund, return, or get money back for an order", content="Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].", ), ) print(procedure.procedure_id) ``` ```typescript focus={5-15} import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); const procedure = await elevenlabs.conversationalAi.agents.procedures.create( "agent_7101k5zvyjhmfg983brhmhkd98n6", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", { name: "Refund request", type: "free_form", trigger: "When the user asks to refund, return, or get money back for an order", content: "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].", } ); console.log(procedure.procedureId); ``` ```bash focus={1-8} curl -X POST "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Refund request", "type": "free_form", "trigger": "When the user asks to refund, return, or get money back for an order", "content": "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"]." }' ``` La risposta include il nuovo `procedure_id`. Per aggiornare la bozza, chiama `PATCH /procedures/{procedure_id}/draft` con `name`, `content`, `type` e un `trigger` esplicito. Usa un `trigger` non vuoto per una procedura di ingresso. Per una [sottoprocedura](#sub-procedures), usa una stringa vuota. ### Pubblica le modifiche Aggiorna l'agente sul branch per pubblicare le bozze delle procedure in forma libera in una nuova versione. La richiesta non necessita di campi nel body; la pubblicazione usa le bozze così come sono. ```python focus={5-8} from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t", ) ``` ```typescript focus={5-7} import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { branchId: "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", }); ``` ```bash focus={1-5} curl -X PATCH \ "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6?branch_id=agtbranch_0901k4aafjxxfxt93gd841r7tv5t" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Consulta [Gestire le procedure](/docs/it/eleven-agents/customization/procedures#manage-procedures) per informazioni sulla rimozione e l'eliminazione delle bozze, oppure il [Riferimento API delle procedure](/docs/it/api-reference/agents/procedures/) per gli schemi completi degli endpoint. ## Best practice > **Tip** > > L'agente deve scegliere la procedura corretta in base al trigger e seguire il contenuto. I modelli più capaci > lo fanno in modo più affidabile all'aumentare del numero di procedure. Consulta > [Modelli](/docs/it/eleven-agents/customization/llm) per le opzioni disponibili. Scrivere bene le procedure significa scrivere bene due parti: un trigger che esegue la procedura quando necessario e contenuti che l'agente può seguire. ### Scrivere i trigger #### Mantieni i trigger concreti e distinti Trigger sovrapposti o vaghi possono causare l'esecuzione della procedura sbagliata. Preferisci *Quando l'utente chiede di annullare un abbonamento* rispetto a \_Quando l'utente ha una domanda sul proprio account \_. #### Scrivi dalla prospettiva dell'utente Descrivi ciò che l'utente sta chiedendo, non ciò che l'agente dovrebbe fare. I trigger formulati come azioni dell'agente sono meno affidabili. #### Copri il modo in cui gli utenti chiedono davvero Un trigger ristretto può non riconoscere richieste reali se l'utente formula le cose in modo diverso. Includi le variazioni che l'utente potrebbe usare. *Quando l'utente chiede di rimborsare, restituire o riavere i soldi per un ordine* funziona in modo più affidabile di \_Quando l'utente richiede un rimborso \_. ### Scrivere i contenuti #### Usa la forma imperativa Scrivi i passaggi come istruzioni per l'agente: *Cerca l'ultimo ordine del cliente* anziché \_Dovresti cercare l'ultimo ordine del cliente \_. Le istruzioni dirette sono più facili da seguire dei suggerimenti. #### Spiega perché un passaggio è importante Il ragionamento si applica anche ai casi limite che la procedura non elenca. Un breve *perché ci serve l'ID dell'ordine per emettere un rimborso* aiuta l'agente a gestire situazioni che i passaggi non avevano previsto. Evita i DEVE in maiuscolo e gli script rigidi quando una spiegazione di una riga svolgerebbe lo stesso lavoro. #### Mantieni ogni procedura focalizzata su un'attività Se una procedura inizia a diramarsi in risultati non correlati, suddividila in procedure più piccole e lascia che l'agente instradi tra loro. ### Comporre le procedure #### Estrai i passaggi condivisi in una procedura dedicata Se gli stessi passaggi compaiono in più procedure (verificare l'identità di un cliente, cercare un ordine, eseguire l'escalation a un operatore), estraili in una procedura dedicata e fai riferimento a essa da ciascuna procedura che ne ha bisogno tramite il menu slash. Gestire i passaggi condivisi in un unico punto mantiene coerenti tutte le procedure che li usano. #### Usa sottoprocedure per azioni reattive Usa una sottoprocedura per un'azione che l'agente dovrebbe eseguire solo quando un'altra procedura la richiede, come la verifica dell'identità o l'escalation. Senza un trigger, non entra in competizione con le procedure di ingresso all'inizio della conversazione. Meno scelte di trigger mantengono l'instradamento mirato. #### Usa il prompt di sistema per il comportamento globale Tono, identità, criteri di rifiuto e guardrail appartengono al [prompt di sistema](/docs/it/eleven-agents/best-practices/prompting-guide). Inserisci i passaggi specifici dell'attività nelle procedure. #### Le procedure vengono versionate con l'agente Le procedure fanno parte della configurazione dell'agente, quindi vengono salvate insieme quando pubblichi una nuova versione dell'agente. Per tornare a un insieme precedente di procedure, ripristina una versione precedente dell'agente. Consulta [Versionamento dell'agente](/docs/it/eleven-agents/operate/versioning). #### Inizia dalla documentazione esistente Se il tuo team dispone già di SOP, usa l'importatore per trasformarle in bozze e perfezionale da lì.