使用Amazon Bedrock AgentCore可觀測性除錯生產環境中的AI代理

生產環境中的人工智慧（AI）代理可能會靜默失敗。它們可能返回看似正確但實際錯誤的答案，陷入無限推理迴圈，或者選擇錯誤的工具而不觸發錯誤警報。這些故障使得除錯生產環境中的代理行為變得困難，因為標準日誌和指標無法捕捉決策過程。

Amazon Bedrock AgentCore可觀測性透過三個層面提供代理執行的可見性：指標、追蹤和結構化日誌。您可以跟蹤每個推理步驟，檢查工具呼叫，並精確定位執行偏離預期的位置。這種可見性使您從檢測到故障發生轉變為理解故障原因。即使沒有顯式錯誤提示，您也可以追蹤代理的推理過程、選擇的工具以及工作流中斷的位置。在本文中，您將學習如何使用內建的可觀測性功能除錯生產環境中的代理故障。我們將介紹常見的故障模式，展示如何使用追蹤和指標分析代理行為，並提供解決無限迴圈和工具呼叫失敗等問題的結構化工作流。本文是兩篇系列文章的第一篇。第二篇將涵蓋效能最佳化和記憶體管理。

前提條件

在按照本文進行實踐之前，請確保您擁有所需的訪問許可權和工具。

您需要擁有一個AWS賬戶，並啟用Amazon Bedrock AgentCore訪問許可權；熟悉Amazon CloudWatch儀表板和基本日誌查詢；瞭解AWS Identity and Access Management（IAM）角色和策略。此外，您還需要為賬戶啟用CloudWatch Transaction Search（請參見啟用可觀測性部分），並且已經部署或擁有許可權部署Amazon Bedrock AgentCore代理。

瞭解代理故障模式

AI代理的故障方式與傳統應用程式不同。您可能會看到執行成功但返回錯誤答案、工作流不完整或意外使用工具的情況。這些問題通常出現在生產環境中而不觸發標準錯誤警報，使得檢測和診斷更加困難。大多數生產問題分為三類：質量、可靠性和效率。瞭解這些模式有助於快速縮小調查範圍。

質量故障

質量故障發生在代理完成任務但返回錯誤結果時。監控系統通常顯示執行成功，而使用者則收到不準確的響應。幻覺和事實錯誤經常出現。代理可能引用不存在的策略或生成資料來填補空白。在多代理系統中，當一個代理的輸出成為另一個代理的輸入時，這些錯誤可能傳播。推理問題也可能出現。代理可能重複相同的錯誤計算或選擇不當的工具。此時，檢查執行追蹤有助於確定邏輯故障點。

可靠性問題

可靠性問題阻止代理完成其工作流。

工具呼叫失敗是常見原因。代理可能因缺少憑證而收到401錯誤，因角色許可權不足而收到403錯誤，或因輸入無效而收到400錯誤。每個錯誤指向不同的根本原因。

您還可能遇到上下文丟失的情況，即代理無法保留會話狀態，將後續請求視為新對話。這通常表明會話管理或記憶體配置存在問題。

效率問題

效率問題影響成本和效能，而非正確性。高延遲會拖慢響應時間，降低使用者參與度。當響應時間過長時，使用者可能放棄互動或重試請求。過多的令牌使用會增加成本而不改善結果。當代理生成過於冗長的響應、不必要地檢索完整文件或重複呼叫工具而不快取結果時，您可能會看到這種情況。

您的除錯工具箱

您可以透過三個可觀測性層面監控、追蹤和分析代理行為：用於系統級可見性的儀表板、用於執行級細節的追蹤以及用於報警和趨勢分析的指標。這些功能協同工作，幫助您從發現問題轉向找到根本原因。

Amazon CloudWatch儀表板

透過Amazon CloudWatch指標（包括會話量、延遲、令牌使用和錯誤率）即時監控代理效能。這些指標讓您跨代理、記憶體系統和工具整合獲得可見性。

GenAI可觀測性儀表板在一個統一檢視中顯示會話量、呼叫延遲、令牌使用和錯誤率。您可以按代理ID、會話ID或時間範圍過濾這些指標，以關注特定的效能模式。

當發現異常時，CloudWatch警報會在延遲超過可接受閾值或錯誤率飆升時自動通知您。

OpenTelemetry追蹤

儀表板顯示系統級行為。追蹤顯示每個請求如何逐步執行。

Amazon Bedrock AgentCore發出分散式追蹤、結構化跨度級日誌和指標，位於bedrock-agentcore CloudWatch名稱空間下。這些遙測資料遵循OpenTelemetry（OTEL）協議，並預設路由到Amazon CloudWatch。如果您的組織使用Datadog、Grafana Cloud或Elastic Observability，您可以將相同的遙測資料匯出到這些後端，無需額外儀表化。

每個追蹤捕獲完整的執行流程：推理步驟、工具呼叫、記憶體檢索和最終輸出。這種細粒度可見性可以精確指出執行偏離預期行為的位置，並顯示導致問題的決策序列。

要監控的關鍵指標

關注三個指標類別：效能、資源使用和可靠性。

效能指標

跟蹤第50、95和99百分位的延遲。較高的延遲通常表明下游瓶頸。分別測量記憶體檢索時間和工具響應時間。這有助於隔離哪個元件拖慢了執行。

資源指標

會話時長揭示使用模式。短會話可能表明使用者受挫。長會話可能表示迴圈或複雜工作流。併發會話顯示系統支援的活躍互動數量。令牌使用直接impact成本。分別監控輸入和輸出令牌以識別低效。

可靠性指標

錯誤率顯示執行失敗的頻率。

按型別分解：

身份驗證錯誤。

授權錯誤。

驗證錯誤。

超時錯誤。

任何類別的峰值都指向一個需要調查的特定領域。

啟用可觀測性

在開始除錯之前，請為您的賬戶啟用CloudWatch Transaction Search。這允許Amazon Bedrock AgentCore將追蹤和指標資料傳送到CloudWatch。啟用此設定後，服務將開始跨代理、記憶體系統和工具整合收集可觀測性資料。然後，您可以透過CloudWatch儀表板和Logs Insights查詢訪問這些資料。

逐步故障排除工作流

以下場景引導您診斷和解決兩個最常見的生產故障。每個場景展示您觀察到的症狀、執行的Amazon CloudWatch Logs Insights查詢（通常需要2-3分鐘）以及實施的修復。CloudWatch Logs Insights是一個完全託管的查詢服務，允許您即時搜尋和分析來自Bedrock AgentCore的結構化日誌資料。您可以透過CloudWatch控制台中的Logs選單訪問它。

場景1：除錯無限代理迴圈

無限迴圈發生在代理缺乏適當的終止條件或無法識別自己已犯錯時。在深入日誌之前，瞭解三個最常見的根本原因將加速診斷。

無限迴圈的常見原因

提示設計不佳：系統提示未建立清晰的終止條件。提示可能未指定合理的嘗試次數、何時宣告任務不可能完成或何時升級到人工。缺少迴圈檢測：代理的推理框架未識別重複操作。如果沒有明確的邏輯來跟蹤先前的嘗試，代理就無法檢測到“我已經嘗試了三次但沒成功”的模式。選錯工具：代理始終選擇錯誤的工具，例如試圖用網路搜尋工具解決問題而不是計算器。

需要注意的症狀

當代理進入迴圈時，令牌使用量顯著增加。會話時長也超出正常範圍。在某些情況下，代理在沒有使用者輸入的情況下生成多個響應。值得注意的是，錯誤率保持較低，因為代理沒有崩潰，只是無法完成任務。

CloudWatch GenAI可觀測性儀表板顯示總令牌消耗266,900，錯誤率為0%。高令牌使用結合無錯誤是無限迴圈的關鍵指標——代理在執行但無法完成任務。

診斷提示工程不佳

首先識別有問題的會話。在CloudWatch Logs Insights中執行以下查詢，查詢令牌使用異常高的會話：

fields @timestamp, SessionId, TokenUsage | filter TokenUsage > 10000 | sort TokenUsage desc | limit 20

選擇消耗最高的會話，記下其SessionId。然後檢查該會話中代理的推理模式：

fields @timestamp, @message, RequestId | filter SessionId = "" | filter Operation like /InvokeAgent/ | sort @timestamp asc | limit 1000

會話詳情顯示單個追蹤包含177個跨度，平均延遲85,590毫秒（約85秒）。正常代理響應在1-5秒內完成。跨度計數和執行時間共同確認代理進入了迴圈。

查詢代理推理中的重複模式。以下日誌序列是迴圈的明確指示：

"嘗試使用計算器工具，輸入25" "結果：24.95" "這是錯誤的，再試一次" "嘗試使用計算器工具，輸入25" "結果：24.95" "這是錯誤的，再試一次"

OpenTelemetry追蹤瀑布揭示了根本原因：系統提示指示代理“永不放棄”和“繼續嘗試直到獲得確切答案”，但沒有終止條件。這種提示設計缺陷直接導致了圖2中所示的177跨度迴圈。

要修復提示設計問題，請在代理的系統提示中新增顯式的終止條件。包括這樣的指令：“如果您嘗試同一操作三次未成功，請停止並向使用者解釋為什麼無法完成任務。”為每個會話設定最大令牌限制，通常為5,000到10,000個令牌（對於對話式代理），並實現推理步驟限制（10到15步作為硬停止）。

診斷迴圈檢測失敗

執行此查詢檢查工具呼叫序列：

fields @timestamp, ToolName, ToolInput, ToolOutput | filter SessionId = "" | filter Operation like /InvokeTool/ | sort @timestamp asc

結果中的以下模式確認迴圈檢測失敗：

2026-02-02 22:02:39 | calculate_percentage | {"value": 25, "total": 100} | 25.0 2026-02-02 22:02:45 | calculate_percentage | {"value": 25, "total": 100} | 25.0 2026-02-02 22:02:51 | calculate_percentage | {"value": 25, "total": 100} | 25.0 [重複40多次]

CloudWatch Logs Insights結果顯示了86次重複的calculate_percentage工具呼叫，輸入幾乎相同，返回值如24.954%和25.049%——從未達到提示要求的精確25.00%。整列中重複的接近值確認了迴圈檢測失敗。

要修復迴圈檢測失敗，請在代理框架中新增迴圈檢測。跟蹤工具呼叫和推理步驟。