AWS AgentCore：统一监控多云/本地AI Agent

当您使用 Strands Agents、LangGraph 和 CrewAI 等框架构建 AI 智能体并部署后，需要对其性能进行可观测性监控。无论这些智能体运行在 Amazon Elastic Kubernetes Service（Amazon EKS）、Amazon Elastic Container Service（Amazon ECS）、AWS Lambda、本地环境，还是 Google Cloud Platform（GCP）或 Microsoft Azure 等其他云服务商，都是如此。

Amazon Bedrock AgentCore 是一个用于大规模构建、连接和优化智能体的平台，支持任意框架或模型。虽然 Amazon Bedrock AgentCore 的一项能力——Amazon Bedrock AgentCore Observability——提供了本地云监控工具开箱即用所不具备的原生追踪、监控和分析功能，但它仅原生支持部署在 AWS Cloud 中 AgentCore 运行时上的智能体。如果您的智能体运行在其他环境，则需要额外配置才能将遥测数据发送到仪表板。

在本文中，我们将展示如何为在 AWS 以外运行的智能体设置可观测性。您将学习如何在非 AWS 环境中配置 AWS Distro for OpenTelemetry（ADOT）自动插桩、将遥测数据路由到 AgentCore Observability 仪表板，以及端到端验证设置。

下图展示了端到端可观测性管道以及遥测数据如何从智能体流向 AgentCore Observability 仪表板。

图 1：端到端可观测性管道，从智能体到 AgentCore Observability 仪表板

该解决方案使用与智能体应用程序进程内运行的 AWS Distro for OpenTelemetry（ADOT）。ADOT 自动插桩智能体框架并捕获生成式 AI 语义约定跨度，然后使用 AWS Identity and Access Management（IAM）凭证通过 SigV4 身份验证将遥测数据直接导出到 Amazon CloudWatch OpenTelemetry Protocol（OTLP）端点。

将遥测数据从 AI 智能体发送到 Amazon Bedrock AgentCore Observability 需要三个核心组件：

• ADOT 自动插桩：AWS Distro for OpenTelemetry 处理从非 AWS 环境导出遥测数据的复杂性。
• IAM 凭证：ADOT 使用这些访问密钥向 CloudWatch 进行身份验证，并将智能体的遥测数据（追踪、指标和日志）转发到 AgentCore Observability 仪表板。
• 环境变量：这些变量包含与路由和身份验证相关的特定 OpenTelemetry 设置。

如下图所示，这种跨平台可观测性解决方案集成了多个 AWS 服务。Amazon CloudWatch 作为基础，负责遥测数据摄取和存储。Amazon Bedrock AgentCore Observability 为 AI 智能体添加了专用监控仪表板。AWS Distro for OpenTelemetry（ADOT）提供跨平台插桩能力。IAM 保护您的外部环境与 AWS 之间的身份验证安全。

图 2：跨平台可观测性架构及涉及的 AWS 服务

可观测性是负责任 AI 的基础支柱。通过将遥测数据路由到 AgentCore Observability，您可以深入了解智能体的推理链、工具调用和模型输出。这使您能够检测幻觉、监控有害或离题的响应、跟踪 Token 用量以进行成本治理，以及跨环境审计智能体行为。这对于在 AWS 以外运行的智能体尤为重要，因为在没有集中可观测性的情况下，有问题的输出可能会被忽视。

在开始之前，请确认您已具备：

• 一个 AWS 账户：已配置 Amazon Bedrock 模型访问权限（本文使用 Claude Haiku 进行演示）。有关各 AWS 区域的模型可用性，请参阅 Amazon Bedrock 按 AWS 区域划分的支持模型。

• 已为 AgentCore Observability 和指定日志组配置必要的权限。

• CloudWatch Transaction Search 已在您的账户中开启（一次性设置）

• 在您的非 AWS 环境中已安装 Python 3.10 或更高版本。

• IAM 用户凭证（访问密钥 ID 和秘密访问密钥），具有以下权限：

  • bedrock:InvokeModel
  • logs:CreateLogGroup、logs:CreateLogStream、logs:PutLogEvents
  • xray:PutTraceSegments、xray:PutTelemetryRecords、xray:GetSamplingRules 和 xray:GetSamplingTargets
  • cloudwatch:PutMetricData

• 您的环境能够向外访问 AWS 端点的 HTTPS 出站流量

开启 CloudWatch Transaction Search

如果您尚未开启 Transaction Search，请运行以下命令（每个账户一次性操作）：

aws xray update-trace-segment-destination --destination CloudWatchLogs --region us-east-1

aws xray get-trace-segment-destination --region us-east-1
# 预期输出：{"Destination": "CloudWatchLogs", "Status": "ACTIVE"}

ADOT 自动插桩（aws-opentelemetry-distro）处理从非 AWS 环境将遥测数据导出到 CloudWatch 的复杂性：

• 自动插桩：opentelemetry-instrument 命令将 ADOT 注入 Python 运行时。它自动修补 boto3（用于 Amazon Bedrock 调用）和 Strands 框架（用于智能体推理跨度）以发出 OpenTelemetry 追踪。
• SigV4 身份验证：aws_configurator 使用 boto3 凭证链对 OTLP 导出请求进行 SigV4 签名。从非 AWS 环境时，这使用 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 环境变量。
• CloudWatch OTLP 端点：ADOT 将追踪和日志导出到 CloudWatch 原生 OTLP 摄取端点。OTEL_EXPORTER_OTLP_LOGS_HEADERS 头将日志定向到特定的 AgentCore 日志组，这是 CloudWatch 在生成式 AI 可观测性仪表板下为数据建立索引的方式。有关 CloudWatch OTLP 端点 URL 的确定和配置方式的详细信息，请参阅 CloudWatch OTLP 端点。
• 生成式 AI 语义约定：Strands [otel] 包按照 OpenTelemetry 生成式 AI 语义约定发出跨度，包括智能体推理步骤、工具调用和带有 Token 用量的模型调用。

下图展示了通过 ADOT 自动插桩从非 AWS 环境到 CloudWatch 的遥测导出工作原理。

图 3：通过 ADOT 自动插桩从非 AWS 环境到 CloudWatch 的遥测导出

按照以下步骤在非 AWS 环境中配置和运行 Strands 智能体，并将遥测数据路由到 AgentCore Observability。

步骤 1：安装依赖

在您的非 AWS 环境（本地服务器、GCP VM、Azure VM 或具有互联网访问权限的计算环境）上：

pip install "aws-opentelemetry-distro>=0.10.0" boto3 "strands-agents[otel]"

aws-opentelemetry-distro 包包含带有针对 AWS 的 OTLP 导出器的 ADOT 自动插桩，以及处理 SigV4 身份验证的 aws_configurator。strands-agents[otel] 包提供来自 Strands 框架的 OpenTelemetry 追踪发射。

步骤 2：配置 AWS 凭证

将您的 IAM 用户凭证设置为环境变量：

export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export AWS_REGION=us-east-1

安全提示：对于生产部署，请考虑使用 IAM Roles Anywhere 而不是长期存在的访问密钥。使用 IAM Roles Anywhere，本地工作负载可以使用 X.509 证书获取临时凭证。

步骤 3：设置 OpenTelemetry 环境变量

这些环境变量配置 ADOT 将遥测数据路由到 AgentCore Observability 仪表板：

export AGENT_OBSERVABILITY_ENABLED=true
export OTEL_PYTHON_DISTRO=aws_distro
export OTEL_PYTHON_CONFIGURATOR=aws_configurator
export OTEL_RESOURCE_ATTRIBUTES="service.name=my-external-agent,aws.log.group.names=/aws/bedrock-agentcore/runtimes/my-external-agent"
export OTEL_EXPORTER_OTLP_LOGS_HEADERS="x-aws-log-group=/aws/bedrock-agentcore/runtimes/my-external-agent,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp

关键配置详情：

• AGENT_OBSERVABILITY_ENABLED=true 在 ADOT 中激活生成式 AI 特定的遥测处理。
• OTEL_PYTHON_DISTRO=aws_distro 和 OTEL_PYTHON_CONFIGURATOR=aws_configurator 激活特定于 AWS 的 OpenTelemetry 配置，包括 CloudWatch OTLP 端点的 SigV4 签名。
• OTEL_RESOURCE_ATTRIBUTES 中的 aws.log.group.names 告诉 CloudWatch 在 AgentCore Observability 仪表板下为遥测数据建立索引。没有此配置，追踪将进入通用的 Amazon CloudWatch Logs。
• OTEL_EXPORTER_OTLP_LOGS_HEADERS 中的 x-aws-metric-namespace=bedrock-agentcore 将嵌入式指标格式的指标路由到正确的 CloudWatch 命名空间。

步骤 4：创建智能体应用程序

创建一个名为 agent_test.py 的文件，包含一个 Strands 智能体：

from strands import Agent
from strands.models.bedrock import BedrockModel
from opentelemetry import baggage
from opentelemetry.context import attach
import time

# Configure the Bedrock model
model = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    region_name="us-east-1"
)
# Create the agent
agent = Agent(
    model=model,
    system_prompt="You are a helpful travel assistant."
)

# Set session ID for AgentCore session tracking
# All agent calls after attach() share same session ID for multiple requests/responses
session_id = f"external-session-{int(time.time())}"
ctx = baggage.set_baggage("session.id", session_id)
attach(ctx)

# Run the agent
response = agent("What are the top 3 things to do in Tokyo?")
print(response)

步骤 5：使用 ADOT 自动插桩运行

opentelemetry-instrument 命令将 Python 进程包装上 ADOT，自动对 Amazon Bedrock 调用和 Strands 框架操作进行插桩：

opentelemetry-instrument python3.12 agent_test.py

智能体的响应将显示在终端中。在后台，ADOT 捕获追踪、跨度（span）和日志，并将其导出到 CloudWatch。

步骤 6：在 AgentCore Observability 中验证

执行后两到三分钟内即可看到遥测数据。打开 Amazon CloudWatch 控制台：

选择 GenAI Observability，然后选择 Bedrock AgentCore。

在 Agents（智能体）标签页中，查找 my-external-agent。

选择该智能体以查看会话、追踪和跨度指标。

以下截图展示了在 CloudWatch 的 AgentCore Observability 仪表板中看到的、在非 AWS 环境中运行的 Strands 智能体（my-external-agent）的遥测数据。

Figure 4: The my-external-agent telemetry in the AgentCore Observability dashboard

智能体名称：my-external-agent。

会话：至少一个会话。

追踪：追踪跨度，展示智能体的推理过程和 Amazon Bedrock 模型调用。

跨度详情：invoke_agent、chat、execute_event_loop_cycle 和 chat.us.anthropic.claude-haiku 跨度，包含延迟和令牌指标。

以下截图展示了 AgentCore Observability 仪表板中 Strands 智能体（my-external-agent）的一个成功追踪，包含四个跨度、模型信息以及延迟和令牌详情。

Figure 5: Trace detail for my-external-agent with span, latency, and token metrics

在 Google Cloud Platform 上验证

为确认该方案在第三方云服务商上正常工作，我们在 Google Cloud Shell（运行在 GCP 基础设施上的基于浏览器的终端）中测试了相同的设置。

在 Google Cloud Shell 上设置环境：

# Create a virtual environment
python3.12 -m venv venv
source venv/bin/activate
# Install dependencies
pip install "aws-opentelemetry-distro" boto3 "strands-agents[otel]"
# Set AWS credentials
export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export AWS_REGION=us-east-1
# Set ADOT environment variables
export AGENT_OBSERVABILITY_ENABLED=true
export OTEL_PYTHON_DISTRO=aws_distro
export OTEL_PYTHON_CONFIGURATOR=aws_configurator
export OTEL_RESOURCE_ATTRIBUTES="service.name=gcp-hosted-agent,aws.log.group.names=/aws/bedrock-agentcore/runtimes/gcp-hosted-agent"
export OTEL_EXPORTER_OTLP_LOGS_HEADERS="x-aws-log-group=/aws/bedrock-agentcore/runtimes/gcp-hosted-agent,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp

从 GCP 运行智能体：

cat > agent_test.py << 'EOF'
from strands import Agent
from strands.models.bedrock import BedrockModel
from opentelemetry import baggage
from opentelemetry.context import attach
import time

model = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    region_name="us-east-1"
)
agent = Agent(model=model, system_prompt="You are a helpful assistant.")

# Set session ID for AgentCore session tracking
# All agent calls after attach() share same session ID for multiple requests/responses
session_id = f"gcp-session-{int(time.time())}"
ctx = baggage.set_baggage("session.id", session_id)
attach(ctx)

response = agent("What are the top 3 things to do in Paris?")
print(response)
EOF
opentelemetry-instrument python3.12 agent_test.py

以下截图展示了在 Google Cloud Shell（GCP）上运行并返回成功响应的 Strands 智能体（gcp-hosted-agent）。

Figure 6: The gcp-hosted-agent running in Google Cloud Shell

验证跨云遥测

执行后两到三分钟内，gcp-hosted-agent 会出现在 AgentCore Observability 仪表板上，与运行在 AgentCore 运行时或其他环境中的智能体并列。

以下截图展示了在 AgentCore Observability 仪表板中看到的、在 GCP 上运行的 Strands 智能体（gcp-hosted-agent）的一个成功追踪，包含四个跨度、模型信息以及延迟和令牌详情。

Figure 7: Trace detail for gcp-hosted-agent running on GCP

遥测数据与 AgentCore 运行时托管的智能体产生的遥测数据完全一致。无论智能体运行在何处，会话、追踪、跨度指标、令牌使用量和延迟都可在同一仪表板中查看。

尽管本教程使用的是 Strands Agents，但相同的基于 ADOT 的模式也适用于其他 OpenTelemetry 兼容的智能体框架。

在为 AI 智能体选择部署方式时，了解不同运行时环境之间可观测性的权衡有助于你做出正确的架构决策。直接部署在 Amazon Bedrock AgentCore 运行时上的智能体受益于自动的可观测性配置。在非 AWS 环境中运行的智能体需要额外的手动设置，但提供了更大的部署灵活性。以下对比重点介绍了遥测收集、凭证管理和用例方面的主要差异，帮助你确定满足需求的最佳方法。

已验证的环境

我们已在两个非 AWS 环境中测试了 ADOT 自动插桩方法：

基于我们的测试，在设置跨平台 AgentCore Observability 时建议如下：

使用一致的命名：OTEL_RESOURCE_ATTRIBUTES 中的 service.name 成为仪表板上的智能体名称。使用描述性名称来标识环境（例如，prod-onprem-support-agent 和 staging-gcp-research-agent）。

首先使用 get-caller-identity 验证：在运行智能体之前，通过运行 python -c "import boto3; print(boto3.client('sts').get_caller_identity())" 确认凭证是否有效。如果此命令失败，ADOT 也会静默失败。

使用 Python 3.10 或更高版本：ADOT 需要 Python 3.10 或更高版本。我们建议使用 Python 3.12 以获得与所有依赖项的最佳兼容性。

为多轮对话设置会话 ID：使用 OpenTelemetry baggage API 传播会话 ID：

from opentelemetry import baggage
from opentelemetry.context import attach
ctx = baggage.set_baggage("session.id", "my-session-123")
attach(ctx)

定期轮换凭证：对于生产部署，避免使用长期有效的访问密钥。考虑为本地工作负载使用 IAM Roles Anywhere，或使用云提供商的身份联合来代入 AWS IAM 角色。

删除本教程期间创建的资源：

# Delete the IAM access key (if created for testing)
aws iam delete-access-key --user-name <your-user> --access-key-id <your-key-id>
# Optionally delete the auto-created CloudWatch log groups
aws logs delete-log-group --log-group-name /aws/bedrock-agentcore/runtimes/my-external-agent --region us-east-1
aws logs delete-log-group --log-group-name /aws/bedrock-agentcore/runtimes/gcp-hosted-agent --region us-east-1

本教程使用 Amazon Bedrock、Amazon CloudWatch 和 AWS X-Ray，会产生费用。具体信息请参阅各自的定价页面。

Amazon Bedrock AgentCore Observability 并非仅限于运行在 AgentCore 运行时或 AWS 内的智能体。使用带有 IAM 凭证和正确 OpenTelemetry 环境变量的 ADOT 自动插桩，你可以从具有互联网访问权限的任何环境发送遥测数据。你的智能体可以运行在本地、GCP、Azure 或任何其他地方，仍能向同一个 AgentCore Observability 仪表板上报。

设置只需一次 pip install 和一组环境变量。生成的遥测数据与 AgentCore 运行时托管的智能体产生的遥测数据完全一致：会话、追踪、跨度指标和令牌使用量，全部在同一统一视图中。

要开始使用，请从 GitHub 克隆示例代码，并按照 README 中的说明在你的环境中配置和运行智能体。

对于运行在 AWS 上但位于 AgentCore 运行时之外的智能体（EKS、ECS、Lambda），请参阅 AgentCore Observability for EKS-hosted agents 教程。对于位于 AgentCore 运行时上的智能体，可观测性是自动配置的。请参阅 Add observability to your AgentCore resources。