Debugging production agents with Amazon Bedrock AgentCore Observability

AWS Machine Learning Blog

AWS Machine Learning Blog2026年6月29日

Debugging production agents with Amazon Bedrock AgentCore Observability

6.9内容质量

TL;DR · AI 摘要

Debugging production agents with Amazon Bedrock AgentCore Observability Artificial Intelligence Debugging production age...

核心要点

主题聚焦：Debugging production agents with Amazon Bedrock
来源：AWS Machine Learning Blog，建议结合原文判断细节。
AI 分析暂不可用，本条为保底评分与摘要。

#AI#编程#后端#云计算#安全

打开原文

使用 Amazon Bedrock AgentCore 可观测性调试生产环境代理 | 人工智能

使用 Amazon Bedrock AgentCore 可观测性调试生产环境代理

生产环境的人工智能（AI）代理可能会静默失败。它们可能返回看似合理但错误的答案、陷入无限推理循环，或在不触发错误警报的情况下选择错误的工具。这些故障使得调试生产环境代理行为变得困难，因为标准日志和指标无法捕捉决策过程。

Amazon Bedrock AgentCore 可观测性通过提供代理执行的三层可见性（指标、追踪和结构化日志）来解决这些调试挑战。您可以跟踪每个推理步骤、检查工具调用，并准确识别执行与预期偏离的具体位置。这种可见性使您从检测到故障发生转变为理解故障原因。即使未触发显式错误，您也可以追踪代理的推理过程、所选工具以及工作流中断的位置。本文将介绍如何使用内置的可观测性功能调试生产环境代理故障。我们将逐步演示常见故障模式，展示如何通过追踪和指标分析代理行为，并提供解决无限循环和工具调用失败等问题的结构化工作流程。这是两部分系列文章的第一部分。第二部分将介绍性能优化和内存管理。

先决条件

在遵循本文的演练之前，请确保已具备必要的访问权限和工具。

您需要拥有已启用 Amazon Bedrock AgentCore 访问权限的 AWS 账户，熟悉 Amazon CloudWatch 仪表板和基础日志查询，以及对 AWS 身份和访问管理（IAM）角色和策略的实用理解。您还需要为账户启用 CloudWatch 事务搜索（请参阅“启用可观测性”部分），并已部署 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，无需额外仪器化即可将相同遥测数据导出到这些后端。

每个追踪记录完整执行流程：推理步骤、工具调用、内存检索和最终输出。这种细粒度可视性可精准定位执行偏离预期行为的位置，并展示导致问题的决策序列。

需监控的关键指标

重点关注三个指标类别：性能、资源使用和可靠性。

#### 性能指标

跟踪 50th、95th 和 99th 百分位延迟。更高延迟通常表明下游瓶颈。分别测量内存检索时间和工具响应时间。这有助于隔离导致执行变慢的组件。

#### 资源指标

会话时长揭示使用模式。短会话可能表明用户挫败感。长会话可能表明循环或复杂工作流。并发会话显示系统支持的活跃交互数量。令牌使用直接影响成本。分别监控输入和输出令牌以识别低效环节。

#### 可靠性指标

错误率显示执行失败的频率。

按类型分类如下：

认证错误。
授权错误。
验证错误。
超时错误。

任何类别中出现激增都表明需要调查特定领域。

启用可观测性

在开始调试之前，请为您的账户启用 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.9K，错误率为 0%。高令牌使用量结合无错误是无限循环的关键指标——代理正在运行但无法完成任务。

#### 诊断提示工程问题

首先识别有问题的会话。在 CloudWatch Logs Insights 中运行以下查询，查找令牌使用量异常高的会话：

code

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

选择使用量最高的会话并记录其 SessionId。然后检查该会话中代理的推理模式：

code

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

会话详情显示一个包含 177 个跨度的单个跟踪，平均延迟为 85,590 毫秒（约 85 秒）。正常代理响应的完成时间在 1-5 秒之间。跨度数量和执行时间共同确认代理进入了循环。

查找代理推理中的重复模式。以下日志序列是循环的明确标志：

code

"尝试使用计算器工具，输入25"
"结果：24.95"
"这不正确，请再试一次"
"尝试使用计算器工具，输入25"
"结果：24.95"
"这不正确，请再试一次"

OpenTelemetry 跟踪瀑布流揭示了根本原因：系统提示指令要求代理"永不放弃"且"持续尝试直到得到确切答案"，但没有终止条件。这种提示设计缺陷直接导致了图2中显示的177个跨度的循环。

修复提示设计问题时，请在代理的系统提示中添加明确的终止条件。包含类似这样的指令："如果尝试相同操作三次仍未成功，请停止并向用户解释无法完成任务的原因"。为每会话设置最大令牌限制（通常为5,000到10,000个令牌），并实施10到15步的推理步骤硬性限制，无论内部逻辑如何。

#### 诊断循环检测失败

运行以下查询检查工具调用序列：

code

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

结果中的以下模式确认了循环检测失败：

code

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 结果显示 calculate_percentage 工具被重复调用86次，输入几乎相同，返回值如24.954%和25.049%——永远达不到提示要求的精确25.00%。整列中重复的近似值确认了循环检测失败。

修复循环检测失败时，请在代理框架中添加循环检测功能。跟踪工具调用和推理步骤，在三次相同重复操作后强制终止。设置CloudWatch警报，当每会话平均令牌使用量显著增加时通知您。这能早期发现循环问题，帮助防止成本失控。

#### 诊断工具选择错误

检查跟踪事件中的代理工具选择推理。以下日志模式表明代理选择了错误工具：

code

"用户想计算100的25%"
"我应该使用网络搜索工具来查找答案"
[网络搜索返回无关结果]
"让我尝试用不同关键词再次进行网络搜索"

修复工具选择问题时，请在代理配置中提供更清晰的工具描述，并包含明确的使用示例：

code

{
  "tools": [
    {
      "name": "calculator",
      "description": "用于数学计算的工具，包括百分比、算术和数值运算。
      示例：计算100的25%。"
    },
    {
      "name": "web_search",
      "description": "用于在互联网上查找信息的工具。
      不要用于数学计算。"
    }
  ]
}

情景2：工具调用失败

工具调用失败会在CloudWatch仪表板中生成明确错误和升高的错误率。与无限循环不同，用户会收到清晰的失败信息。挑战在于快速识别根本原因。

五种错误类型导致大多数工具调用失败，每种错误都指向不同的解决方案。认证错误（401）发生在凭证过期、缺失或使用了错误的认证方式时。授权错误（403）出现在代理附加的IAM角色缺少必要策略时。验证错误（400）发生在代理的输入与工具预期的模式不匹配时。资源未找到错误（404）表明工具名称错误、资源ID无效或工具已被删除。工具执行错误（500）表示工具本身因内部错误、超时或速率限制而失败。

工具调用失败会生成明确的错误信息。您的CloudWatch仪表板会显示错误率升高，代理会话无法完成，用户报告代理无法访问信息或执行操作。

#### 诊断认证和授权错误

首先确定哪个工具最常失败。在CloudWatch Logs Insights中运行以下查询：

code

fields @timestamp, ToolName, StatusCode, ErrorMessage
| filter Operation like /InvokeTool/
| filter StatusCode like /4[0-9][0-9]|5[0-9][0-9]/
| stats count(*) by ToolName, StatusCode
| sort count desc

CloudWatch Logs Insights查询按类型分解工具调用错误：Exception（45次）、PermissionError（6次）和RuntimeError（6次）。Exception错误占主导地位，表明验证失败是首要的根因需要优先调查。

对于认证和授权错误，请检查附加到代理网关的网关服务角色。在Amazon Bedrock AgentCore中，工具通过网关访问，网关服务角色必须具有调用下游资源的权限：

code

fields @timestamp, AgentId, ExecutionRoleArn, ErrorMessage
| filter StatusCode = 401 or StatusCode = 403
| limit 100

将网关服务角色的策略与失败工具所需的权限进行对比。例如，如果代理通过网关调用AWS Lambda函数工具并收到403错误，请更新网关服务角色以包含以下权限：

code

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowGatewayToInvokeLambdaTool",
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeFunction"
      ],
      "Resource": [
        "arn:aws:lambda:us-east-1:123456789012:function:my-tool-function"
      ]
    }
  ]
}

对于凭证问题，请使用AWS Secrets Manager自动存储和轮换凭证。为工具错误率设置CloudWatch警报。如果任何工具的错误率超过5%，请立即调查。

#### 诊断验证错误

对于验证错误，请检查代理提供的工具输入：

code

fields @timestamp, ToolName, ToolInput, ErrorMessage
| filter StatusCode = 400
| limit 50

将代理的输入与工具预期的模式进行对比。查找缺失的必填字段、数据类型错误或格式错误的值：

code

工具预期：{"customer_id": "string", "amount": number}
代理提供：{"customer_id": 12345, "amount": "100.00"}

修复验证错误需要更新工具模式以匹配工具当前的API。在部署到生产环境之前，独立测试工具调用。创建集成测试，使用各种输入（包括边缘情况）调用每个工具。

#### 诊断资源和执行错误

对于资源未找到错误（404）和工具执行错误（500），请首先检查工具自身的日志和指标。问题可能并不在您的代理上。查询特定错误模式：

code

fields @timestamp, ToolName, ToolInput, ErrorMessage
| filter StatusCode = 404 or StatusCode = 500
| limit 50

当工具发生故障时，您的代理应记录包含工具名称、输入负载和错误信息的完整上下文错误。对于瞬时故障应使用指数退避策略重试，当工具不可用时应通过尝试替代方案优雅降级，并在工具无法访问时明确通知用户。

从调试到主动监控

前面场景中的查询帮助您在问题发生后进行诊断。要提前发现用户报告之前的问题，请将诊断查询转换为持久仪表板和警报，并使用AgentCore Evaluators进行持续工具评估。

从日志洞察创建CloudWatch警报

指标过滤器可以持续监控代理日志组中的失败模式，通过附加CloudWatch警报，您的团队可以自动收到通知。

这为您提供了一个无需手动运行日志洞察查询即可检测无限循环的预警系统。

构建CloudWatch仪表板

将关键诊断查询添加为CloudWatch仪表板小部件，以保持持续可见性。这使运维团队能够通过单一视图查看代理健康状态，无需手动重新运行查询。可视化有助于识别更多异常值。

使用AgentCore Evaluators实现工具准确性自动化

对于大规模工具准确性监控，Amazon Bedrock AgentCore Evaluators提供持续的自动化代理行为评估。无需在出现问题时手动检查追踪记录，Evaluators会实时检查代理会话并根据质量标准进行评分，从而实现大规模代理性能评估。

清理资源

完成演练后，请删除或禁用创建的资源以避免持续计费。

要禁用CloudWatch查询和警报，请打开Amazon CloudWatch控制台，导航到日志 -> 日志洞察并删除创建的任何保存查询，然后导航到警报 > 所有警报并删除为令牌使用率或错误率阈值创建的任何警报。如果您仅为此次演练启用了CloudWatch事务搜索，请在CloudWatch控制台的设置下将其关闭。

注意：关闭CloudWatch事务搜索将停止所有未来的追踪收集。在关闭之前请确保不再需要可观测性数据。您可以根据需要重新启用它。

如果您为此次演练部署了测试代理，请导航到Amazon Bedrock控制台，选择您的代理，然后选择删除以移除它及其相关资源。

结论

您现在拥有了一个用于调试生产代理的实际框架。您了解代理失败的三类情况：Bedrock AgentCore的CloudWatch仪表板和OpenTelemetry追踪如何呈现每种失败类型，以及如何遵循结构化诊断流程解决无限循环和工具调用失败。

关键收获：结构化可观测性将数小时的猜测工作转化为几分钟的针对性调查。本文中的CloudWatch日志洞察查询今天即可在您的生产环境中使用。

下一步

继续阅读本系列的第二部分文章《Optimizing Production Agents: Performance and Memory Management with Bedrock AgentCore》，该文章将探讨性能瓶颈和内存泄漏问题。要为特定代理工作流构建自定义查询，请查阅Amazon CloudWatch Logs Insights文档。在AWS Machine Learning Community Forums社区论坛中分享您的调试经验并获取帮助。

About the authors

'"`