本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 AI 编码助手诊断 AgentCore 评估问题
<a name="diagnose-evaluation-issues"></a>

如果你的 AgentCore 评估配置没有产生结果，或者你看到的错误或评估分数为空 `LogEventMissingException``AgentSpanMappingException`，你可以自己使用**AgentCore 评估诊断技能**来解决问题。

该技能是一个降价文件，适用于任何 AI 编码助手。您将其加载到您的助手中，提供您的 Amazon 区域、部署类型以及可选的会话 ID，助手会引导您完成分步诊断。该技能适用于部署在 AgentCore 运行时上的代理和托管在第三方基础设施（亚马逊 ECS、亚马逊 EKS、 Amazon Lambda 或任何其他环境）上的代理。该助手会查询您自己的亚马逊 CloudWatch 日志组，以确定根本原因并提出修复建议。

## 该技能可以诊断什么
<a name="what-the-skill-diagnoses"></a>

该技能涵盖了最常见的评估问题：
+  **空评估结果 ** — 尽管启用了评估配置，但仍未显示任何分数。
+  **`LogEventMissingException`**— 评估报告跨度缺少相应的日志事件。
+  **`AgentSpanMappingException`**或者 ** `ToolSpanMappingException` ** — 评估无法从跨度中提取用户查询或工具输出。
+  **`SpanEventParsingException`**— 评估无法解析事件的正文。
+  **`Gateway Timeout (504)`**— 评估超时。
+  **`ValidationException`**on `evaluatorId` — 评估者 ID 格式不正确。
+  **Multi-agent 评估范围问题 ** — 评估人员在多代理跟踪中瞄准了错误的代理。

## 先决条件
<a name="diagnostic-skill-prerequisites"></a>
+  Amazon CLI 使用运行代理的帐户的凭证进行配置。证书需要以下权限：
  +  `logs:DescribeLogGroups`,`logs:DescribeLogStreams`,`logs:StartQuery`, `logs:GetQueryResults` — 用于查询 CloudWatch 日志
  +  `bedrock-agentcore:GetOnlineEvaluationConfig`，`bedrock-agentcore:ListOnlineEvaluationConfigs`— 读取评估配置（仅限在线评估）
+ 建议使用该`boto3`库的 Python 3.9 或更高版本，但不是严格要求的——诊断查询也可以直接通过 Amazon CLI 运行。
+ 支持[代理技能](https://agentskills.io)标准或可以接受降价指令的人工智能编码助手。
+ 在启用了可观察性的情况下至少被调用过一次的代理。

## 复制技能
<a name="copy-the-skill"></a>

技能来源可在[诊断技能来源中找到](diagnose-evaluation-skill-source.md)。复制该主题中的整个代码块并将其另存为`SKILL.md`在计算机`agentcore-eval-diagnostic/`上命名的新文件夹中。

该技能是一个普通的降价文件。它仅包含公共信息，并且仅针对您自己的帐户运行，无需服务端访问权限。

## 将技能加载到你的 AI 编程助手中
<a name="load-the-skill"></a>

将[诊断技能源中的技能源另存](diagnose-evaluation-skill-source.md)为`SKILL.md`计算机`agentcore-eval-diagnostic/`上命名的文件夹中，然后将该文件夹移动或复制到您的 AI 编码助手的技能目录中。该技能遵循开放的 [ Agent Skills ](https://agentskills.io) 标准，因此每个工具都会从自己的专用技能文件夹中发现该技能——不要将技能内容附加到通用说明文件中`AGENTS.md`，例如`CLAUDE.md`、或。`GEMINI.md`

### Kiro CLI
<a name="load-kiro"></a>

将技能文件夹放在项目`.kiro/skills/agentcore-eval-diagnostic/`中，或将其置于`~/.kiro/skills/agentcore-eval-diagnostic/`使其在所有工作空间中可用。有关设置的详细信息，请参阅 [ Kiro CLI 技能文档](https://kiro.dev/docs/skills)。

### Claude Code
<a name="load-claude-code"></a>

将技能文件夹放置`.claude/skills/agentcore-eval-diagnostic/`在项目中，或将其置于`~/.claude/skills/agentcore-eval-diagnostic/`使其在所有项目中可用。有关设置的详细信息，请参阅 [ Claude Code 技能文档](https://docs.anthropic.com/en/docs/claude-code/skills)。

### openAI Codex CLI
<a name="load-codex"></a>

将技能文件夹放在您的存储库`.agents/skills/agentcore-eval-diagnostic/`中，或`~/.agents/skills/agentcore-eval-diagnostic/`将其放置在所有存储库中。有关设置的详细信息，请参阅 C [ odex CLI 技能文档](https://developers.openai.com/codex/skills)。

### Cursor
<a name="load-cursor"></a>

Cursor 使用规则而不是技能。将技能内容另存为项目规则`.cursor/rules/agentcore-eval-diagnostic.md`。有关设置的详细信息，请参阅[光标规则文档](https://cursor.com/docs/context/rules)。

### 双子座 CL
<a name="load-gemini-cli"></a>

将技能文件夹置于`~/.gemini/skills/agentcore-eval-diagnostic/`使其在所有工作空间中可用，或者放在项目的技能目录中以供项目范围内使用。有关设置的详细信息，请参阅 [ Gemini CLI 技能文档](https://geminicli.com/docs/cli/skills/)。

### 任何其他 AI 助手
<a name="load-other"></a>

如果您的助手支持[代理技能](https://agentskills.io)标准，请将该技能文件夹放在助手用于发现技能的目录中。如果您的助手不支持代理技能，请将的内容粘贴`SKILL.md`到系统提示、用户消息或上下文文件中来加载技能。该技能是独立的，不依赖于任何特定工具的功能。

## 进行诊断
<a name="run-a-diagnosis"></a>

加载技能后，与你的 AI 助手开始新的聊天并提供：

1. 您 Amazon 所在的地区（例如，`us-west-2`）。

1. 您的部署类型 — `agentcore-runtime` 如果您的代理在 AgentCore Runtime 上部署，或者`3p-managed`您的代理托管在 Amazon ECS、Amazon EKS、 Amazon Lambda 或任何其他非AgentCore 环境上。

1. 您的评估类型 —`online`（使用带抽样的评估配置）或`on-demand`（直接评估 API 调用）。

1. （可选）来自代理跟踪的会话 ID（`session.id`属性）。如果您没有，助手可以自动发现您的日志组中的近期会话。

该助手会查询您的 CloudWatch 日志组，确定故障的根本原因，并生成结构化诊断报告。该报告包括：
+ 根本原因摘要。
+ 显示哪些诊断检查通过或失败的发现表。
+ 受影响的跨度和事件的列表。
+ 相关 Amazon 文档的链接。
+ 建议的后续步骤。

该助手会针对您自己的 CloudWatch 日志组运行您自己 Amazon 账户中的所有查询。它不访问任何 Amazon 服务端日志或内部数据。

## 示例互动
<a name="example-interaction"></a>

 **你：**我的地区是`us-west-2`，我正在使用 AgentCore 运行时进行在线评估，我的会话 ID 是`my-session-abc123`。我的评估没有产生结果。你能诊断出来吗？

 **人工智能助手：**

```
## AgentCore Evaluation Diagnostic Report

Session: my-session-abc123
Region: us-west-2

Summary: Service name mismatch — spans are emitted under
'my_agent.DEFAULT' but the evaluation configuration expects
'wrong_name.DEFAULT'.

Findings:
| Check                | Status | Details |
| -------------------- | ------ | ------- |
| Eval config status   | OK     | ENABLED, 100% sampling |
| Spans found          | OK     | 15 spans for this session |
| Scope support        | OK     | strands.telemetry.tracer found |
| Service name match   | FAIL   | Config expects wrong_name.DEFAULT |

Recommended fix: Update the evaluation configuration's serviceNames to
match 'my_agent.DEFAULT'.
```

## 对技能本身进行故障排除
<a name="troubleshooting-the-skill"></a>

如果助手无法查询您的日志组，请检查：
+ 您的 Amazon 证书具有所需的权限。
+ 您提供的区域与代理的部署位置相匹配。
+ 会话 ID 正确（将其从代理跟踪中复制）。
+ 在过去 24 小时内已调用该代理。

## 相关文档
<a name="diagnose-related-docs"></a>
+  [支持的代理框架 ](supported-frameworks.md) 
+  [创建在线评估 ](create-online-evaluations.md) 
+  [按需评估入门 ](getting-started-on-demand.md) 

**Topics**