View a markdown version of this page

使用 AI 编码助手诊断 AgentCore 评估问题 - 亚马逊基岩 AgentCore
该技能可以诊断什么先决条件复制技能将技能加载到你的 AI 编程助手中进行诊断示例互动对技能本身进行故障排除相关文档

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

使用 AI 编码助手诊断 AgentCore 评估问题

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

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

该技能可以诊断什么

该技能涵盖了最常见的评估问题：

  • 空评估结果 — 尽管启用了评估配置，但仍未显示任何分数。

  • LogEventMissingException— 评估报告跨度缺少相应的日志事件。

  • AgentSpanMappingException或者 ToolSpanMappingException — 评估无法从跨度中提取用户查询或工具输出。

  • SpanEventParsingException— 评估无法解析事件的正文。

  • Gateway Timeout (504)— 评估超时。

  • ValidationExceptionon evaluatorId — 评估者 ID 格式不正确。

  • Multi-agent 评估范围问题 — 评估人员在多代理跟踪中瞄准了错误的代理。

先决条件

  • AWS CLI 使用运行代理的帐户的凭证进行配置。证书需要以下权限：

    • logs:DescribeLogGroups,logs:DescribeLogStreams,logs:StartQuery, logs:GetQueryResults — 用于查询 CloudWatch 日志

    • bedrock-agentcore:GetOnlineEvaluationConfig，bedrock-agentcore:ListOnlineEvaluationConfigs— 读取评估配置（仅限在线评估）

  • 建议使用该boto3库的 Python 3.9 或更高版本，但不是严格要求的——诊断查询也可以直接通过 AWS CLI 运行。

  • 支持代理技能标准或可以接受降价指令的人工智能编码助手。

  • 在启用了可观察性的情况下至少被调用过一次的代理。

复制技能

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

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

将技能加载到你的 AI 编程助手中

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

Kiro CLI

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

Claude Code

将技能文件夹放置.claude/skills/agentcore-eval-diagnostic/在项目中，或将其置于~/.claude/skills/agentcore-eval-diagnostic/使其在所有项目中可用。有关设置的详细信息，请参阅 Claude Code 技能文档。

openAI Codex CLI

将技能文件夹放在您的存储库.agents/skills/agentcore-eval-diagnostic/中，或~/.agents/skills/agentcore-eval-diagnostic/将其放置在所有存储库中。有关设置的详细信息，请参阅 C odex CLI 技能文档。

Cursor

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

双子座 CL

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

任何其他 AI 助手

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

进行诊断

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

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

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

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

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

该助手会查询您的 CloudWatch 日志组，确定故障的根本原因，并生成结构化诊断报告。该报告包括：

  • 根本原因摘要。

  • 显示哪些诊断检查通过或失败的发现表。

  • 受影响的跨度和事件的列表。

  • 相关 AWS 文档的链接。

  • 建议的后续步骤。

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

示例互动

你：我的地区是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'.

对技能本身进行故障排除

如果助手无法查询您的日志组，请检查：

  • 您的 AWS 证书具有所需的权限。

  • 您提供的区域与代理的部署位置相匹配。

  • 会话 ID 正确（将其从代理跟踪中复制）。

  • 在过去 24 小时内已调用该代理。

主题