Procedure strutturate

Panoramica

Una procedura strutturata è una procedura che esegue una sequenza fissa di passaggi. Una procedura in formato libero è una guida in linguaggio naturale che l’agente interpreta e adatta alla situazione. Una procedura strutturata è un elenco ordinato di passaggi tipizzati che l’agente esegue in ordine ogni volta che si applica la procedura.

Usa una procedura strutturata quando passaggi specifici devono avvenire allo stesso modo in ogni chiamata: verificare l’identità di chi chiama, inoltrare un ticket a un livello superiore o accettare un pagamento. La crei come un breve elenco di passaggi in linguaggio semplice.

Come ogni procedura, una procedura strutturata ha un trigger che descrive quando si applica. Quando una conversazione corrisponde al trigger, l’agente esegue in ordine i passaggi della procedura, quindi torna al resto della conversazione.

Quando usare una procedura strutturata

Usa una procedura strutturata quando passaggi specifici devono essere eseguiti sempre allo stesso modo, ma vuoi comunque creare rapidamente passaggi in linguaggio semplice. Le procedure strutturate sono più facili da scrivere di un workflow, ma meno espressive. Per scoprire come si confrontano con le procedure in formato libero, i workflow e il prompt di sistema, consulta Quando usare le procedure.

Anatomia di una procedura strutturata

Una procedura strutturata è composta da tre parti: un nome, un trigger e un elenco ordinato di passaggi.

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 in linguaggio naturale di quando l’agente deve eseguire questa procedura, ad esempio Quando l’utente chiede il rimborso di un ordine. L’agente confronta l’intento dell’utente con il trigger di ogni procedura ed esegue quella corrispondente, quindi i trigger devono essere concreti e distinti. L’agente vede solo il testo del trigger, mai il nome o l’ID della procedura. Un trigger funziona allo stesso modo di qualsiasi procedura; consulta Scrivere i trigger.

Lascia vuoto il trigger per rendere la procedura una sotto-procedura che viene eseguita solo quando un’altra procedura la chiama.

Passaggi

Il corpo della procedura è un elenco ordinato di passaggi tipizzati. Esistono vari tipi di passaggio, che puoi combinare per descrivere l’attività.

Non tutti i passaggi possono comparire ovunque. All’interno di un ramo Se, puoi usare qualsiasi passaggio tranne un altro Se o Riprova. Nel gestore degli errori di un passaggio Strumento, puoi usare qualsiasi passaggio tranne Se o un altro Strumento.

Riferimento dei passaggi API

Il content di una procedura strutturata è un documento con codifica JSON che contiene un array steps. Ogni passaggio è un oggetto identificato dal relativo type. Il trigger è un campo separato di livello superiore nella procedura, non fa parte di content. I payload di API e SDK usano type: "deterministic" per la procedura stessa.

Chiedi

Un passaggio Chiedi indica all’agente di richiedere informazioni e attendere finché l’utente non fornisce una risposta appropriata.

• Tipo API: ask
• instruction: Stringa obbligatoria e non vuota.

{
  "type": "ask",
  "instruction": "Ask the user for their order ID."
}

Comunica

Un passaggio Comunica indica all’agente di generare un singolo messaggio con parole proprie. Non attende una risposta dell’utente prima di continuare.

• Tipo API: tell
• instruction: Stringa obbligatoria e non vuota.

{
  "type": "tell",
  "instruction": "Explain that the refund normally takes five to ten business days."
}

Pronuncia

Un passaggio Pronuncia riproduce il testo fornito esattamente come è scritto, quindi continua. Fornisci message_translations per assegnare all’agente un messaggio esatto per ogni ulteriore lingua supportata, con chiave corrispondente al codice della lingua.

• Tipo API: say
• message: Stringa obbligatoria e non vuota.
• message_translations: Oggetto facoltativo che associa un codice lingua a { "value": "..." }.

{
  "type": "say",
  "message": "Your refund has been submitted.",
  "message_translations": {
    "es": { "value": "Su reembolso ha sido enviado." }
  }
}

Se, altrimenti se e altrimenti

Un passaggio Se contiene uno o più rami condizionali ordinati. Viene eseguito il primo ramo corrispondente. L’array fallback facoltativo è il ramo Altrimenti.

• Tipo API: branch
• branches: Elenco obbligatorio e non vuoto di rami condizionali.
• fallback: Elenco facoltativo di passaggi Altrimenti.
• Ogni ramo richiede un condition e un elenco steps non vuoto.

{
  "type": "branch",
  "branches": [
    {
      "condition": {
        "type": "llm",
        "condition": "The user is on an annual plan."
      },
      "steps": [
        {
          "type": "say",
          "message": "Your annual plan is eligible for a prorated refund."
        }
      ]
    }
  ],
  "fallback": [
    {
      "type": "tell",
      "instruction": "Explain that the account's plan could not be determined."
    }
  ]
}

Il comportamento è simile a if/else-if/else:

1. Le condizioni vengono valutate in ordine.
2. Viene eseguito il primo ramo corrispondente.
3. Se nessuna condizione corrisponde, viene eseguito fallback.
4. Dopo il completamento di un ramo, la procedura si riunisce alla sequenza principale.

L’esempio precedente usa una condizione testuale, che il modello valuta in linguaggio naturale. Le condizioni possono anche essere espressioni basate su variabili dinamiche:

{
  "type": "expression",
  "expression": {
    "type": "eq_operator",
    "left": {
      "type": "dynamic_variable",
      "name": "plan_tier"
    },
    "right": {
      "type": "string_literal",
      "value": "annual"
    }
  }
}

Una condizione di espressione verifica le variabili dinamiche, che vengono compilate dai risultati degli strumenti o impostate all’avvio della conversazione. Non può leggere la risposta più recente dell’utente. Per creare un ramo in base a ciò che ha detto l’utente, usa una condizione testuale.

Tutti i rami di uno stesso passaggio Se devono usare lo stesso tipo di condizione: llm oppure expression.

Strumento

Un passaggio Strumento chiama uno strumento specifico.

• Tipo API: tool_call
• tool_id: ID dello strumento obbligatorio e non vuoto. Lo strumento deve essere associato all’agente.
• tool_name: Nome dello strumento obbligatorio, corrispondente allo strumento.
• instruction: Istruzione facoltativa che descrive come chiamare lo strumento.
• schema_overrides: Valori fissi facoltativi per i parametri dello strumento.
• on_failure: Gestore degli errori facoltativo.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "instruction": "Look up the order using the order ID provided by the user."
}

Valori fissi dei parametri

Usa schema_overrides quando un parametro deve avere sempre un valore specifico. Il modello non vede né sceglie un parametro sostituito. Le chiavi sono path dei parametri nello schema dello strumento; ogni valore indica una sorgente:

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "update_ticket",
  "schema_overrides": {
    "request_body.status": { "source": "constant", "constant_value": "pending" },
    "request_body.ticket_id": { "source": "dynamic_variable", "dynamic_variable": "ticket_id" }
  }
}

Gestione degli errori

Senza on_failure, una chiamata allo strumento non riuscita termina la conversazione. Aggiungi invece on_failure per eseguire passaggi di ripristino.

• fallback: Elenco obbligatorio e non vuoto di passaggi eseguiti quando lo strumento non riesce.
• branches: Riservato alla gestione condizionale degli errori. Lascialo vuoto.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "on_failure": {
    "branches": [],
    "fallback": [
      {
        "type": "tell",
        "instruction": "Explain that the order could not be retrieved and offer to connect the user with support."
      }
    ]
  }
}

Un gestore degli errori può contenere passaggi Chiedi, Comunica, Pronuncia, Sotto-procedura, Strumento di sistema e Riprova. Non può contenere passaggi Strumento o Se. Dopo l’esecuzione del gestore, la procedura continua con il passaggio successivo al passaggio Strumento.

Riprova

Un passaggio Riprova riesegue il gestore degli errori che lo contiene, inclusa la chiamata allo strumento. Ogni tentativo chiama di nuovo lo strumento e, se fallisce di nuovo, riesegue ogni passaggio del gestore. Quando i tentativi sono esauriti, la conversazione termina.

• Tipo API: retry
• max_retries: Intero facoltativo da 1 a 3. Il valore predefinito è 1.
• Il valore conta i tentativi successivi alla chiamata allo strumento originale.
• Riprova è valido solo all’interno di on_failure.
• Riprova deve essere il passaggio finale del relativo gestore degli errori perché i passaggi successivi sarebbero irraggiungibili.

{
  "type": "retry",
  "max_retries": 2
}

Sotto-procedura

Un passaggio Sotto-procedura esegue un’altra procedura strutturata. Quando i passaggi di quella procedura sono completati, l’esecuzione torna al passaggio successivo al passaggio Sotto-procedura.

• Tipo API: sub_procedure
• procedure_id: ID della procedura obbligatorio e non vuoto.
• La destinazione deve esistere sullo stesso agente.
• La destinazione deve essere una procedura strutturata.
• Una procedura non può richiamare sé stessa.

{
  "type": "sub_procedure",
  "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
}

Strumento di sistema

Un passaggio Strumento di sistema esegue un’azione integrata di sistema.

• Tipo API: system_tool
• system_tool_name: Nome dello strumento di sistema obbligatorio.
• Al momento è supportato solo end_call. In futuro potrebbero essere aggiunti altri strumenti di sistema.
• Poiché end_call è terminale, deve essere il passaggio finale nella sequenza, nel ramo o nel gestore degli errori che lo contiene.

{
  "type": "system_tool",
  "system_tool_name": "end_call"
}

Regole di convalida

La pubblicazione dell’agente, oppure il salvataggio della bozza dell’agente, rifiuta una procedura strutturata che viola una di queste regole. L’errore indica il passaggio non valido tramite il relativo path.

• Non è possibile inserire due passaggi Se consecutivi.
• I passaggi Se non possono essere annidati.
• Un passaggio Se con condizioni di espressione non può seguire direttamente un passaggio Chiedi.
• Tutte le condizioni di uno stesso passaggio Se devono essere dello stesso tipo: llm o expression.
• Riprova può comparire solo all’interno di on_failure e deve essere l’ultimo passaggio al suo interno.
• end_call deve essere l’ultimo passaggio dell’elenco in cui compare.
• Il fallback di un gestore degli errori deve contenere almeno un passaggio.
• Una Sotto-procedura deve puntare a una procedura strutturata esistente sullo stesso agente e non a sé stessa.
• tool_id deve essere uno strumento dell’agente, tool_name deve corrispondere e schema_overrides deve corrispondere allo schema dello strumento.
• L’elenco steps, ogni instruction e ogni message devono essere non vuoti.

Per scoprire come ristrutturare una procedura che incontra una di queste regole, consulta le Best practice.

Esempio API completo

Questo esempio gestisce l’annullamento di un ordine in base allo stato della spedizione. Fissa un parametro dello strumento, gestisce una chiamata allo strumento non riuscita, richiama un’altra procedura strutturata e poi termina la chiamata.

{
  "steps": [
    {
      "type": "ask",
      "instruction": "Ask the user for their order ID."
    },
    {
      "type": "branch",
      "branches": [
        {
          "condition": {
            "type": "llm",
            "condition": "The user says the order has already shipped."
          },
          "steps": [
            {
              "type": "tell",
              "instruction": "Explain that shipped orders must be returned before they can be refunded."
            }
          ]
        },
        {
          "condition": {
            "type": "llm",
            "condition": "The user says the order has not shipped."
          },
          "steps": [
            {
              "type": "tool_call",
              "tool_id": "tool_abc123",
              "tool_name": "cancel_order",
              "instruction": "Cancel the order using the order ID provided by the user.",
              "schema_overrides": {
                "request_body.notify_customer": { "source": "constant", "constant_value": true }
              },
              "on_failure": {
                "branches": [],
                "fallback": [
                  {
                    "type": "tell",
                    "instruction": "Apologize that the cancellation did not go through and say you will try once more."
                  },
                  {
                    "type": "retry",
                    "max_retries": 1
                  }
                ]
              }
            }
          ]
        }
      ],
      "fallback": [
        {
          "type": "ask",
          "instruction": "Ask whether the order has already shipped."
        }
      ]
    },
    {
      "type": "sub_procedure",
      "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
    },
    {
      "type": "say",
      "message": "Thank you for contacting us. Goodbye.",
      "message_translations": {
        "es": { "value": "Gracias por contactarnos. Adiós." }
      }
    },
    {
      "type": "system_tool",
      "system_tool_name": "end_call"
    }
  ]
}

Come viene eseguita una procedura strutturata

La trasformazione dei passaggi di una procedura strutturata nel formato eseguito dall’agente è chiamata compilazione. La piattaforma compila ogni procedura strutturata quando viene salvata la bozza dell’agente o pubblicato l’agente; gli autori non devono compilare nulla.

Quando la richiesta dell’utente corrisponde al trigger di una procedura, la piattaforma accede alla procedura ed esegue i relativi passaggi in ordine. All’interno della procedura strutturata, l’agente si concentra su ogni singolo passaggio. Quando raggiunge la fine, la piattaforma restituisce il controllo al resto della conversazione.

I collegamenti del workflow non possono connettersi a una procedura strutturata né partire da essa. Usa un passaggio Sotto-procedura per concatenare procedure strutturate. La piattaforma gestisce l’accesso da un trigger corrispondente e il completamento, inclusa la restituzione del controllo al nodo del workflow in cui è iniziata la procedura.

Le seguenti regole descrivono il comportamento dei passaggi in fase di runtime.

Gestire una procedura strutturata

Best practice

Ogni tipo di passaggio applica già il proprio comportamento, quindi raramente devi esplicitarlo. Scrivi l’obiettivo di ogni passaggio e lascia che il tipo di passaggio faccia il resto. Le indicazioni seguenti coprono i casi che è importante gestire correttamente.

Per testare una procedura strutturata, segui Iterare su una procedura.

Scegliere i tipi di passaggio

Strutturare la procedura

Lavorare con gli strumenti

Scrivere le istruzioni

Comporre procedure

Le indicazioni generali per comporre procedure si applicano anche alle procedure strutturate; consulta Comporre procedure nella pagina delle procedure in formato libero.

Un modello è specifico della combinazione dei tipi: una procedura in formato libero può fare riferimento a una strutturata. Mantieni la gestione aperta in una procedura in formato libero e delega a una procedura strutturata le parti che devono essere eseguite sempre nello stesso modo, come la verifica dell’identità o l’escalation.

Limitazioni

• I passaggi If non possono essere annidati e due passaggi If non possono essere posizionati uno dopo l’altro.
• L’unico strumento di sistema supportato è end_call.
• Le procedure strutturate non possono fare riferimento a documenti della knowledge base.
• Non è possibile terminare il turno corrente al completamento di una procedura; l’agente mantiene il turno aperto e potrebbe continuare a parlare.
• Gli edge del workflow non possono connettersi a una procedura strutturata né partire da essa. Usa un passaggio Sub-procedure per concatenare procedure strutturate; l’avvio e il completamento sono gestiti dalla piattaforma.
• L’avvio di una procedura aggiunge latenza: l’agente effettua una chiamata allo strumento per accedervi e poi procede nel workflow generato.

Supporto dei provider di modelli

Le procedure strutturate forzano chiamate interne agli strumenti quando si accede a una sotto-procedura e quando si completa una procedura. Le principali famiglie di modelli OpenAI, Anthropic, Gemini e Grok supportano la scelta forzata dello strumento. Altri modelli o provider personalizzati potrebbero non garantirla, rendendo meno affidabili le transizioni tra sotto-procedure o il completamento della procedura. Quando usi un altro provider di modelli, verifica il supporto della scelta forzata dello strumento.

Consulta Procedure per i limiti applicabili a tutte le procedure, incluso il limite di dimensione dei contenuti e le differenze tra procedure strutturate e in formato libero.