Credencial — Observabilidade de Agentes de IA

Credencial — Monitoramento de Falhas dos Agentes de IA

A aba Credencial do Dashboard do Intelbras Agentes de IA permite acompanhar falhas relacionadas às credenciais utilizadas pelos agentes para acessar provedores de modelos de linguagem, como OpenAI ou Google Gemini.

O recurso foi criado para facilitar a identificação de problemas de autenticação, chave inválida ou revogada, indisponibilidade de modelo e esgotamento de cota da conta, ajudando a reduzir o tempo de diagnóstico e a identificar rapidamente quando uma falha de credencial está impactando agentes e conversas.

Para acessar, utilize o menu Dashboard e selecione a aba Credencial.

Visão geral da aba Credencial

Na parte superior da tela, é possível selecionar o período de análise. O Dashboard apresenta indicadores resumidos e, abaixo, detalhamentos por agente, tipo de erro e orientações sobre o que fazer em cada situação.

Indicadores principais

Erros de credencial

O indicador Erros de credencial contabiliza as respostas de falha devolvidas pelo provedor quando um agente tenta gerar uma resposta e ocorre algum problema relacionado à credencial.

Entre os exemplos considerados estão:

• chave inválida ou revogada;
• modelo não liberado para a chave;
• cota da conta esgotada.

Esse indicador não considera falhas como timeout, queda de rede ou limite de velocidade da OpenAI quando o erro está relacionado a throughput e não à credencial.

Benefício: permite dimensionar o volume de falhas relacionadas às credenciais. Como uma mesma credencial pode gerar várias tentativas com erro, o número deve ser analisado em conjunto com os demais indicadores para entender o impacto real.

Agentes afetados

O indicador Agentes afetados mostra quantos agentes apresentaram ao menos um erro de credencial no período selecionado.

Testes realizados no Playground não entram nessa contagem.

Benefício: ajuda a identificar a abrangência da falha. Um único agente afetado tende a indicar um problema pontual naquele agente, enquanto vários agentes afetados ao mesmo tempo podem indicar uma credencial compartilhada com problema.

Credenciais com falha ativa

O indicador Credenciais com falha ativa apresenta credenciais que possuem ao menos um agente cuja última chamada falhou e que ainda não apresentou uma chamada bem-sucedida depois disso.

Credenciais que apresentaram erro no período, mas voltaram a funcionar, não entram nesse indicador.

Benefício: mostra o que exige atuação no momento da consulta, separando falhas históricas de incidentes que ainda permanecem ativos.

Conversas interrompidas

O indicador Conversas interrompidas contabiliza atendimentos distintos em que ao menos uma mensagem do cliente ficou sem resposta do agente por causa de erro de credencial.

Se houver várias tentativas sem resposta dentro da mesma conversa, elas são contabilizadas como uma única conversa interrompida.

Não são considerados nesse indicador atendimentos encerrados ou interrompidos por outros motivos, como transbordo, encerramento pelo cliente ou erro de fluxo.

Benefício: traduz o problema técnico em impacto no atendimento, ajudando a medir quantas conversas foram efetivamente afetadas.

Erros por agente

A seção Erros por agente apresenta uma linha para cada combinação de agente e credencial utilizada, ordenada pelo volume de erros no período.

Clique em uma linha quando precisar consultar os tipos de erro registrados, a mensagem original devolvida pelo provedor e quando cada erro ocorreu.

Quando uma mesma credencial é utilizada por vários agentes, o mesmo incidente pode aparecer em mais de uma linha. Por isso, a leitura deve considerar tanto o agente quanto a credencial apresentada.

Entre as colunas disponíveis estão:

• Agente e credencial: apresenta o nome do agente e o apelido da credencial utilizada. A chave nunca é exibida;
• Provedor e modelo: mostra o provedor e o modelo utilizados pelo agente no momento do último erro;
• Erro predominante: mostra o tipo de erro com maior quantidade de ocorrências naquele agente;
• Erros: apresenta o total de respostas de falha de credencial recebidas por aquele agente no período;
• Conversas: apresenta a quantidade de conversas relacionadas aos erros;
• Último erro: informa quando ocorreu a falha mais recente, considerando o horário de Brasília;
• Situação: indica se o problema está Falhando agora ou Normalizada.

Situação da credencial

Falhando agora: a última chamada do agente utilizando aquela credencial falhou e não houve uma chamada bem-sucedida posteriormente.

Normalizada: o agente apresentou uma chamada bem-sucedida após o último erro. O histórico permanece disponível para consulta, mas não existe uma ação pendente relacionada àquela falha.

Erros por tipo

A seção Erros por tipo agrupa as falhas conforme o código devolvido pelo provedor e apresenta a participação de cada tipo em relação ao total de erros do período.

Entre os tipos apresentados estão:

• Chave inválida ou revogada;
• Cota da conta esgotada;
• Modelo não liberado para a chave.

Benefício: ajuda a entender a natureza predominante do problema antes de analisar agente por agente. Por exemplo, predominância de chave inválida indica uma tratativa diferente de cota esgotada.

O que fazer

A seção O que fazer apresenta orientações associadas aos principais tipos de falha.,

Entre os encaminhamentos exibidos na tela estão:

• Gerar nova chave no provedor e atualizar em Configurações: indicado para chave revogada, apagada ou copiada de forma incompleta;
• Recarregar crédito ou revisar o limite de gasto na conta do provedor: indicado quando a chave continua válida, mas o saldo ou limite da conta foi atingido;
• Liberar o modelo para a chave ou trocar o modelo do agente: indicado quando o agente tenta utilizar um modelo que não está habilitado no projeto ou conta do provedor.

Benefício: reduz o tempo entre a identificação da falha e sua correção, direcionando o usuário para o tipo de ação mais adequado ao problema encontrado.

Como utilizar a aba Credencial

1. Acesse Dashboard.
2. Selecione a aba Credencial.
3. Defina o período que deseja analisar.
4. Verifique primeiro os indicadores Credenciais com falha ativa e Conversas interrompidas para identificar problemas que ainda estão impactando a operação.
5. Consulte Agentes afetados para entender a abrangência do problema.
6. Analise a tabela Erros por agente para localizar qual agente e credencial estão relacionados à falha.
7. Utilize Erros por tipo para identificar a natureza predominante do problema.
8. Consulte a seção O que fazer para orientar a correção.

Principais benefícios

• Diagnóstico mais rápido: reúne em uma única tela os principais sinais de falha de credencial;
• Priorização de incidentes ativos: diferencia problemas históricos de credenciais que continuam falhando;
• Visibilidade de impacto: mostra quantos agentes e conversas foram afetados;
• Identificação da causa: organiza os erros por tipo, agente, provedor e modelo;
• Orientação para correção: apresenta encaminhamentos de acordo com a natureza da falha;
• Apoio à operação: permite identificar rapidamente quando uma credencial compartilhada pode estar afetando vários agentes ao mesmo tempo.

A aba Credencial deve ser utilizada como apoio ao monitoramento das integrações com os provedores de IA, ajudando a manter os agentes disponíveis e a reduzir interrupções causadas por falhas de autenticação ou configuração.