使用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%。整列中重复的接近值确认了循环检测失败。

要修复循环检测失败，请在代理框架中添加循环检测。跟踪工具调用和推理步骤。