View a markdown version of this page

使用 AI 編碼助理診斷 AgentCore 評估問題 - Amazon Bedrock AgentCore
技能診斷的內容先決條件複製技能將技能載入 AI 編碼助理執行診斷互動範例故障診斷技能本身相關文件

使用 AI 編碼助理診斷 AgentCore 評估問題

如果您的 AgentCore 評估組態未產生結果，或者您看到 LogEventMissingException、 AgentSpanMappingException或空白評估分數等錯誤，您可以使用 AgentCore 評估診斷技能來自行疑難排解問題。

技能是一種 Markdown 檔案，可與任何 AI 編碼助理搭配使用。您可以將它載入您的助理，提供您的 AWS 區域、部署類型和選用的工作階段 ID，助理會逐步引導您完成 step-by-step 診斷。此技能適用於部署在 AgentCore 執行期的代理程式，以及託管在第三方基礎設施 (Amazon ECS、Amazon EKS、 AWS Lambda 或任何其他環境） 上的代理程式。助理會查詢您自己的 Amazon CloudWatch 日誌群組，以識別根本原因並建議修正。

技能診斷的內容

此技能涵蓋最常見的評估問題：

  • 空的評估結果 — 即使啟用評估組態，也不會顯示任何分數。

  • LogEventMissingException — 評估報告跨度遺失其對應的日誌事件。

  • AgentSpanMappingException 或 ToolSpanMappingException — 評估無法從跨度擷取使用者查詢或工具輸出。

  • SpanEventParsingException — 評估無法剖析事件的內文。

  • Gateway Timeout (504) — 評估逾時。

  • ValidationException on evaluatorId — 評估器 ID 格式不正確。

  • 多客服人員評估範圍問題 — 評估者以多客服人員追蹤中的錯誤客服人員為目標。

先決條件

  • AWS CLI 已設定代理程式執行所在帳戶的登入資料。登入資料需要下列許可：

    • logs:DescribeLogGroups、logs:DescribeLogStreams、logs:StartQuery、 logs:GetQueryResults — 查詢 CloudWatch Logs

    • bedrock-agentcore:GetOnlineEvaluationConfig、 bedrock-agentcore:ListOnlineEvaluationConfigs — 讀取評估組態 （僅限線上評估）

  • 建議使用具有程式boto3庫的 Python 3.9 或更新版本，但並非嚴格要求 – 診斷查詢也可以直接透過 CLI AWS 執行。

  • 支援客服人員技能標準或可接受 Markdown 指示的 AI 編碼助理。

  • 已調用至少一次並啟用可觀測性的代理程式。

複製技能

技能來源可在診斷技能來源中使用。從該主題複製整個程式碼區塊，並將其儲存為agentcore-eval-diagnostic/電腦上名為 SKILL.md 的新資料夾。

技能是純標記檔案。它只包含公開資訊，並且只會針對您自己的帳戶執行 - 不需要服務端存取。

將技能載入 AI 編碼助理

將診斷技能來源的技能來源儲存為機器agentcore-eval-diagnostic/上名為 的資料夾SKILL.md內，然後將該資料夾移動或複製到 AI 編碼助理的技能目錄中。技能遵循開放的客服人員技能標準，因此每個工具都會從自己的專用技能資料夾中探索，而不會將技能內容附加到一般指令檔案，例如 AGENTS.md、 CLAUDE.md或 GEMINI.md。

Kiro CLI

將技能資料夾放在專案.kiro/skills/agentcore-eval-diagnostic/中的 ，或放在 ~/.kiro/skills/agentcore-eval-diagnostic/ ，讓所有工作區都能使用。如需設定詳細資訊，請參閱 Kiro CLI 技能文件。

Claude 程式碼

將技能資料夾放在您的專案.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/ ，讓所有儲存庫都能使用。如需設定詳細資訊，請參閱 Codex CLI 技能文件。

游標

游標使用規則而非技能。將技能內容儲存為 中的專案規則.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 執行期，或者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。我的評估不會產生結果。您可以進行診斷嗎？

AI 助理：

## 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 小時內已叫用代理程式。

主題