# Como funciona
<a name="insights-how-it-works"></a>

AgentCore O Insights responde a três perguntas sobre o comportamento de produção do seu agente: **Por que ele está falhando**? **O que os usuários estão pedindo?** e **como está resolvendo problemas?** 

## O que você ganha
<a name="insights-what-you-get"></a>

Ao executar insights, você recebe:
+  **Uma lista priorizada de padrões de falha** — não erros individuais, mas problemas recorrentes agrupados por causa raiz. Cada padrão mostra o que está errado e por quê. O Insights é integrado aos recursos de [AgentCore recomendação](optimization-recommendations.md) para gerar correções para os padrões de falha.
+  **Um mapa das intenções do usuário** — as coisas mais comuns que seus usuários estão tentando realizar, classificadas por frequência.
+  **Um resumo dos padrões de comportamento do agente** — como seu agente normalmente aborda os problemas e quais resultados ele alcança.

Eles correspondem a três tipos de insights que você pode configurar:
+  `Builtin.Insight.FailureAnalysis`— Detecção de padrões de falha e análise da causa raiz
+  `Builtin.Insight.UserIntent`— Extração e agrupamento da intenção do usuário
+  `Builtin.Insight.ExecutionSummary`— Resumo e agrupamento do comportamento do agente

## Como a análise funciona
<a name="insights-how-analysis-works"></a>

O Insights examina os rastreamentos de sessão do seu agente — o registro completo das mensagens do usuário, do raciocínio do agente, das chamadas de ferramentas e das respostas — e produz descobertas em dois níveis:

### Session-level análise
<a name="insights-session-level"></a>

Cada sessão é analisada individualmente para determinar:
+ Se o agente encontrou falhas durante a execução — incluindo falhas ocultas em rastreamentos que podem não estar visíveis para o usuário final, mesmo quando a sessão parece bem-sucedida
+ Qual categoria de falha ocorreu (erro da ferramenta, alucinação, escolha errada da ferramenta etc.)
+ Qual etapa específica na execução do agente causou a falha
+ Qual foi a causa raiz
+ O que o usuário estava tentando realizar
+ Qual abordagem o agente adotou e o resultado final

### Descoberta de padrões
<a name="insights-pattern-discovery"></a>

Depois que as sessões individuais são analisadas, o serviço identifica padrões recorrentes em todas as sessões agrupando descobertas semelhantes. Para análise de falhas, isso produz uma hierarquia de três níveis:

1.  **Categorias de falha:** agrupamentos amplos, como “erros de execução”, “alucinações” ou “ações incorretas”.

1.  **Subcategorias:** tipos de falha mais específicos, como “limitação de taxa” ou “erros no esquema da ferramenta”.

1.  **Clusters de causas raiz:** dentro de cada subcategoria, as causas-raiz recorrentes específicas. Cada cluster informa:
   + Qual é a causa raiz
   + Quantas sessões são afetadas
   + Quais sessões você pode inspecionar para obter detalhes

Para intenções do usuário e resumos de execução, o serviço produz clusters planos classificados por frequência.

## Quando é executado
<a name="insights-when-it-runs"></a>

Você controla quando os insights são executados:
+  **One-time:** Ligue `StartBatchEvaluation` com insights sempre que quiser fazer uma análise, por exemplo, após uma implantação, após um aumento nas reclamações de usuários ou como parte de uma revisão semanal.
+  **Recorrente:** configure uma frequência de agrupamento (`DAILY``WEEKLY`, ou`MONTHLY`) e o serviço será executado automaticamente, fornecendo relatórios periódicos sem intervenção manual.

## Categorias de falha
<a name="insights-failure-categories"></a>

O Insights reconhece uma ampla taxonomia dos tipos de falha do agente:


| Categoria | Exemplos | 
| --- | --- | 
| Erros de execução | Falhas de autenticação, recurso não encontrado, erros de serviço, limitação de taxa, tempos limite, violações do esquema da ferramenta | 
| Problemas de instrução de tarefas | Non-compliance com instruções, falhas na identificação de problemas | 
| Ações incorretas | Seleção incorreta de ferramentas, recuperação deficiente de informações, solicitações de esclarecimento inadequadas | 
| Tratamento de contexto | Falhas de tratamento de contexto em todos os turnos | 
| Alucinações | Capacidades fabricadas, mal-entendidos, uso incorreto, histórico de fabricação, alucinação de parâmetros, saídas de ferramentas fabricadas | 
| Comportamento repetitivo | Repetição de chamada de ferramenta, repetição de solicitação de informações, repetição de etapas | 
| Erros de orquestração | Incompatibilidade de raciocínio, desvio de meta, rescisão prematura, rescisão inconsciente | 
| Problemas de saída do LLM | Saídas sem sentido | 
| Incompatibilidade de configuração | Incompatibilidades na definição da ferramenta | 
| Coding-specific | Descuidos de casos extremos, problemas de dependência |