View a markdown version of this page

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

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

如果您的 AgentCore 评估配置未产生结果，或者您看到诸如LogEventMissingExceptionAgentSpanMappingException、或空的评估分数之类的错误，则可以使用AgentCore 评估诊断技能自行解决问题。

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

技能可以诊断什么

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

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

  • LogEventMissingException— 评估报告某个 span 缺少相应的日志事件。

  • 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 运行诊断查询。

  • 支持代理技能标准或可以接受 markdown 指令的 AI 编码助手。

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

复制技能

技能来源在诊断技能来源中可用。复制该主题中的整个代码块，并将其另存为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 代码技能文档。

OpenAI Codex Coldex CLI

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

Cursor

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

Gemini CLI

将技能文件夹放在~/.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（直接调用 Evaluate API）。

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

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

  • 根本原因摘要。

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

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

  • 相关 AWS 文档的链接。

  • 建议的后续步骤。

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

互动示例

你：我所在的地区是us-west-2，我正在使用带有在线评估功能的 AgentCore Runtime，我的会话 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 小时内被调用。

主题