使用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%。整列中重複的接近值確認了循環檢測失敗。

要修復循環檢測失敗，請在代理框架中添加循環檢測。跟蹤工具調用和推理步驟。