Alertas

Visão geral

Os alertas notificam você quando algo dá errado com os agentes no seu workspace. A ElevenLabs monitora continuamente a atividade das conversas e gera um alerta quando uma taxa de erros excede um limite configurado ou aumenta muito acima da referência recente. Os alertas não exigem configuração para começar a funcionar: os monitores são executados automaticamente com limites padrão, e você pode ajustar os limites ou adicionar notificações quando necessário.

Os alertas são visualizados e gerenciados no painel da ElevenLabs, onde as configurações são definidas no nível do workspace e do agente. As configurações no nível do agente também podem ser definidas programaticamente pelo campo platform_settings.alerting ao criar ou atualizar um agente com a API, os SDKs ou os arquivos de configuração do Agents CLI Atualizar agente. As configurações no nível do workspace e o histórico de alertas estão disponíveis apenas no painel.

Os seguintes monitores são avaliados para cada agente:

Cada alerta tem um dos seguintes status:

• Ativo: A condição está sendo acionada no momento.
• Resolvido: A condição deixou de ser acionada e o alerta foi resolvido automaticamente após um período de inatividade.
• Descartado: Um usuário descartou manualmente o alerta.

Visualizando alertas

Acesse Desenvolvedores > Alertas para ver alertas de monitoramento recentes dos agentes no seu workspace. A página mostra uma linha do tempo da atividade dos alertas e uma tabela com o registro de data e hora, a duração, o status, o tipo e o agente de cada alerta. Você pode filtrar por status, agente ou ferramenta e ajustar o intervalo de tempo (até 90 dias).

Clique em um alerta para abrir as conversas afetadas ou use o menu da linha para Inspecionar conversas no histórico de conversas. Alertas ativos podem ser descartados no mesmo menu.

Alertas ativos também aparecem como cartões de alta prioridade no Spotlight, o painel de visão geral na página de cada agente, e um banner no painel de Agentes cria um link para a página de Alertas sempre que seu workspace tiver alertas ativos.

Configurando limites

Os limites de alerta podem ser configurados no nível do workspace e substituídos para cada agente. Valores não definidos usam a configuração do workspace, e valores não definidos no workspace usam os padrões do sistema.

Na página Desenvolvedores > Alertas, clique em Configurações de alertas e selecione Configurar limites. Para substituir os limites de um único agente, abra a seção Alertas na aba de configurações Avançadas do agente e clique em Configurar limites.

Cada monitor pode ser ativado ou desativado e tem uma configuração de Limite: a taxa de erros que aciona um alerta, como porcentagem entre 0% e 100%. Você também pode definir Resolver automaticamente após inatividade (minutos) para controlar por quanto tempo um alerta pode permanecer inativo antes de ser resolvido automaticamente.

Notificações

Os alertas podem notificar sistemas externos por webhooks do workspace, Slack e PagerDuty. Quando um alerta é acionado, resolvido ou descartado, a ElevenLabs notifica cada notificador configurado. Os notificadores podem ser associados no nível do workspace e por agente; os notificadores no nível do agente são adicionados aos notificadores do workspace, em vez de substituí-los. É possível configurar até 10 notificadores por nível.

Para configurar um notificador, clique em Configurações de alertas > Configurar notificações na página Desenvolvedores > Alertas ou, para um único agente, em Configurar notificações na seção Alertas da aba de configurações Avançadas do agente. Cada notificador tem uma ação Enviar teste para verificar a entrega antes que um alerta seja acionado.

Webhooks

Selecione um webhook existente do workspace ou crie um novo com uma URL de callback HTTPS. A ElevenLabs envia uma solicitação POST para cada evento do ciclo de vida do alerta. Seu endpoint deve verificar a assinatura da solicitação e retornar HTTP 200 rapidamente; webhooks que falham repetidamente são desativados automaticamente, seguindo as mesmas regras dos outros webhooks do workspace.

Payload da notificação

As notificações de alerta usam o tipo de evento convai_alerting_notification. O campo event.name indica o que aconteceu: triggered quando o alerta se torna ativo, auto_resolved quando é resolvido após inatividade e resolved quando um usuário o descarta (nesse caso, was_resolved_by_user é true). O campo text contém um resumo legível por humanos formatado com marcação do Slack, para que a notificação possa ser encaminhada diretamente para um webhook de entrada do 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
  }
}

O campo monitor é um de elevated_conversation_failure_rate, elevated_tool_failure_rate, webhook_error_spike, guardrail_trigger_spike, call_initiation_error_spike ou low_evaluation_success_score. O campo tool_name só é definido para alertas de falha de ferramenta.

Slack

Os notificadores do Slack enviam notificações de alerta diretamente para um canal do Slack. Conecte a integração do Slack ao seu workspace, depois adicione a conexão como um notificador e informe o ID do canal para o qual as mensagens serão enviadas. Para encontrar o ID do canal no Slack, abra o canal, clique no nome do canal no cabeçalho, role até o final da aba Sobre e copie o ID do canal (por exemplo, C0123456789). Adicione o app do Slack conectado ao canal; o app precisa do escopo chat:write ou de chat:write.public para publicar em canais públicos dos quais não participa. Uma mensagem é publicada quando um alerta é acionado e novamente quando ele é resolvido.

PagerDuty

Os notificadores do PagerDuty enviam alertas como incidentes do PagerDuty pela Events API. Conecte a integração do PagerDuty na página de Integrações com uma chave de integração da Events API v2 do serviço PagerDuty que deve receber os alertas e, em seguida, adicione a conexão como um notificador. Um incidente é acionado quando um alerta se torna ativo e é resolvido automaticamente quando o alerta é resolvido; acionamentos repetidos do mesmo alerta são desduplicados em um único incidente. Há suporte para as regiões de serviço do PagerDuty nos EUA e na UE.

Recursos relacionados