# 工作原理
<a name="insights-how-it-works"></a>

AgentCore insights 回答了有关代理生产行为的三个问题：**为什么会失败？** **用户要求什么？** 以及**它是如何解决问题的？** 

## 你会得到什么
<a name="insights-what-you-get"></a>

当你运行见解时，你会收到：
+  **按优先顺序排列的故障模式列表** ——不是单个错误，而是按根本原因分组的反复出现的问题。每种模式都会告诉你出了什么问题以及原因。Insights 与[AgentCore 推荐](optimization-recommendations.md)功能集成，可针对故障模式生成修复程序。
+  **用户意图地图** — 用户想要完成的最常见的事情，按频率排序。
+  **代理行为模式摘要** ——您的代理通常如何处理问题以及它会取得什么结果。

它们对应于您可以配置的三种洞察类型：
+  `Builtin.Insight.FailureAnalysis`— 故障模式检测和根本原因分析
+  `Builtin.Insight.UserIntent`— 用户意图提取和聚类
+  `Builtin.Insight.ExecutionSummary`— 代理行为汇总和集群

## 分析的工作原理
<a name="insights-how-analysis-works"></a>

Insights 会检查您的代理的会话跟踪（用户消息、代理推理、工具调用和响应的完整记录），并在两个层面上得出调查结果：

### Session-level 分析
<a name="insights-session-level"></a>

对每个会话进行单独分析，以确定：
+ 代理在执行过程中是否遇到故障，包括跟踪中隐藏的故障，即使会话显示成功，最终用户也可能看不到这些故障
+ 发生了哪类故障（刀具错误、幻觉、刀具选择错误等）
+ 代理执行中的哪个具体步骤导致了失败
+ 根本原因是什么
+ 用户想要完成的任务
+ 代理人采取了什么方法以及最终结果

### 模式发现
<a name="insights-pattern-discovery"></a>

在对单个会话进行分析后，该服务通过将相似的发现组合在一起来识别所有会话的重复模式。对于失效分析，这将生成一个三级层次结构：

1.  **失败类别：**广泛的分组，例如 “执行错误”、“幻觉” 或 “错误的行为”。

1.  **子类别：**更具体的故障类型，例如 “速率限制” 或 “工具架构错误”。

1.  **根本原因聚类：**在每个子类别中，具体的反复出现的根本原因。每个集群都会告诉你：
   + 根本原因是什么
   + 有多少会话受到影响
   + 您可以查看哪些会话以了解详细信息

对于用户意图和执行摘要，该服务会生成按频率排名的扁平集群。

## 它何时运行
<a name="insights-when-it-runs"></a>

您可以控制何时运行见解：
+  **One-time：**无论何时需要分析，都可以致电`StartBatchEvaluation`获取见解，例如，在部署之后、用户投诉激增之后，或者作为每周评估的一部分。
+  **重复：**配置集群频率（`DAILY``WEEKLY`、或`MONTHLY`），服务会自动运行，无需人工干预即可为您提供定期报告。

## 失败类别
<a name="insights-failure-categories"></a>

Insights 认可代理故障类型的广泛分类：


| 类别 | 示例 | 
| --- | --- | 
| 执行错误 | 身份验证失败、未找到资源、服务错误、速率限制、超时、工具架构违规 | 
| 任务指令问题 | Non-compliance 附带说明，问题识别失败 | 
| 操作不正确 | 工具选择错误、信息检索不佳、澄清请求不当 | 
| 上下文处理 | 跨回合上下文处理失败 | 
| 幻觉 | 捏造的能力、误解、错误的用法、历史编造、参数幻觉、伪造的工具输出 | 
| 重复行为 | 工具调用重复、信息请求重复、步骤重复 | 
| 编排错误 | 推理不匹配、目标偏差、提前终止、无意识终止 | 
| LLM 输出问题 | 荒谬的输出 | 
| 配置不匹配 | 工具定义不匹配 | 
| Coding-specific | 边缘案例疏忽、依赖问题 |