Avvisi

Panoramica

Gli avvisi ti informano quando qualcosa non funziona con gli agenti nel tuo workspace. ElevenLabs monitora continuamente l’attività delle conversazioni e genera un avviso quando un tasso di errore supera una soglia configurata o aumenta bruscamente rispetto al suo recente valore di riferimento. Gli avvisi non richiedono configurazione per iniziare a funzionare: i monitor vengono eseguiti automaticamente con soglie predefinite e puoi modificarle o aggiungere notifiche quando necessario.

Gli avvisi vengono visualizzati e gestiti nella dashboard di ElevenLabs, dove le impostazioni sono configurate a livello di workspace e di agente. Le impostazioni a livello di agente possono essere impostate anche in modo programmatico tramite il campo platform_settings.alerting quando crei o aggiorni un agente con l’API Aggiorna agente, gli SDK o i file di configurazione della CLI Agents. Le impostazioni a livello di workspace e la cronologia degli avvisi sono disponibili solo nella dashboard.

I seguenti monitor vengono valutati per ogni agente:

Ogni avviso ha uno dei seguenti stati:

• Attivo: la condizione è attualmente attiva.
• Risolto: la condizione ha smesso di attivarsi e l’avviso è stato risolto automaticamente dopo un periodo di inattività.
• Ignorato: un utente ha ignorato manualmente l’avviso.

Visualizzare gli avvisi

Vai a Sviluppatori > Avvisi per vedere gli avvisi di monitoraggio recenti degli agenti nel tuo workspace. La pagina mostra una timeline dell’attività degli avvisi e una tabella con timestamp, durata, stato, tipo e agente di ciascun avviso. Puoi filtrare per stato, agente o strumento e modificare l’intervallo temporale, fino a 90 giorni.

Fai clic su un avviso per aprire le conversazioni interessate oppure usa il menu della riga per Esaminare le conversazioni nella cronologia delle conversazioni. Gli avvisi attivi possono essere ignorati dallo stesso menu.

Gli avvisi attivi compaiono anche come schede ad alta priorità in Spotlight, la dashboard panoramica nella pagina di ciascun agente, e un banner nella dashboard Agents rimanda alla pagina Avvisi ogni volta che il tuo workspace ha avvisi attivi.

Configurare le soglie

Le soglie degli avvisi possono essere configurate a livello di workspace e sostituite per singolo agente. I valori non impostati usano la configurazione del workspace e i valori non impostati nel workspace usano le impostazioni predefinite del sistema.

Nella pagina Sviluppatori > Avvisi, fai clic su Impostazioni avvisi e seleziona Configura soglie. Per sostituire le soglie per un singolo agente, apri invece la sezione Avvisi nella scheda delle impostazioni Avanzate dell’agente e fai clic su Configura soglie.

Ogni monitor può essere attivato o disattivato e dispone dell’impostazione Soglia: il tasso di errore, espresso come percentuale tra 0% e 100%, che attiva un avviso. Puoi anche impostare Risoluzione automatica dopo inattività (minuti) per controllare per quanto tempo un avviso può rimanere inattivo prima di risolversi automaticamente.

Notifiche

Gli avvisi possono notificare sistemi esterni tramite webhook del workspace, Slack e PagerDuty. Quando un avviso si attiva, si risolve o viene ignorato, ElevenLabs notifica ogni notificatore configurato. I notificatori possono essere collegati a livello di workspace e per singolo agente; quelli a livello di agente si aggiungono ai notificatori del workspace anziché sostituirli. Puoi configurare fino a 10 notificatori per livello.

Per configurare un notificatore, fai clic su Impostazioni avvisi > Configura notifiche nella pagina Sviluppatori > Avvisi oppure, per un singolo agente, su Configura notifiche nella sezione Avvisi della scheda delle impostazioni Avanzate dell’agente. Ogni notificatore dispone dell’azione Invia test per verificare la consegna prima che si attivi un avviso.

Webhook

Seleziona un webhook esistente del workspace oppure creane uno nuovo con un URL callback HTTPS. ElevenLabs invia una richiesta POST per ogni evento del ciclo di vita dell’avviso. Il tuo endpoint deve verificare la firma della richiesta e restituire rapidamente HTTP 200; i webhook che falliscono ripetutamente vengono disattivati automaticamente, secondo le stesse regole degli altri webhook del workspace.

Payload della notifica

Le notifiche degli avvisi usano il tipo di evento convai_alerting_notification. Il campo event.name indica cosa è successo: triggered quando l’avviso diventa attivo, auto_resolved quando si risolve dopo un periodo di inattività e resolved quando un utente lo ignora, nel qual caso was_resolved_by_user è true. Il campo text contiene un riepilogo leggibile formattato con markup Slack, quindi la notifica può essere inoltrata direttamente a un webhook in entrata di Slack.

{
  "type": "convai_alerting_notification",
  "event_timestamp": 1739537297,
  "text": ":rotating_light: *New agent alert - High tool failure rate*\n*Agent:* <https://elevenlabs.io/app/agents/agents/agent_7101k5zvyjhmfg983brhmhkd98n6|Support agent>\n*Status:* Triggered\n*Started at:* 14 February at 12:48 UTC",
  "event": {
    "name": "triggered",
    "was_resolved_by_user": false
  },
  "alert": {
    "id": "alert_2601k5zvyjhmfg983brhmhkd98n6",
    "tool_name": "get_order_status",
    "monitor": "elevated_tool_failure_rate",
    "metric_name": "tool_failure_rate",
    "status": "active",
    "first_triggered_at_unix_secs": 1739537297,
    "last_triggered_at_unix_secs": 1739537897
  }
}

Il campo monitor è uno tra elevated_conversation_failure_rate, elevated_tool_failure_rate, webhook_error_spike, guardrail_trigger_spike, call_initiation_error_spike o low_evaluation_success_score. Il campo tool_name viene impostato solo per gli avvisi di errore dello strumento.

Slack

I notificatori Slack pubblicano le notifiche degli avvisi direttamente in un canale Slack. Collega l’integrazione Slack al tuo workspace, quindi aggiungi la connessione come notificatore e inserisci l’ID del canale in cui pubblicare. Per trovare l’ID del canale in Slack, apri il canale, fai clic sul nome del canale nell’intestazione, quindi scorri fino in fondo alla scheda Informazioni e copia l’ID del canale, ad esempio C0123456789. Aggiungi l’app Slack collegata al canale; l’app richiede lo scope chat:write oppure chat:write.public per pubblicare nei canali pubblici a cui non ha aderito. Viene pubblicato un messaggio quando un avviso si attiva e di nuovo quando si risolve.

PagerDuty

I notificatori PagerDuty inviano gli avvisi come incidenti PagerDuty tramite l’API Events. Collega l’integrazione PagerDuty nella pagina Integrazioni usando una chiave di integrazione Events API v2 del servizio PagerDuty che deve ricevere gli avvisi, quindi aggiungi la connessione come notificatore. Un incidente viene attivato quando un avviso diventa attivo e risolto automaticamente quando l’avviso si risolve; le attivazioni ripetute dello stesso avviso vengono deduplicate in un unico incidente. Sono supportate entrambe le regioni di servizio PagerDuty, Stati Uniti e UE.

Risorse correlate