用 AgentCore 可观测性监控本地与多云 AI 智能体

#用 AgentCore 可观测性监控本地与多云 AI 智能体

当你部署用 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 Observability 作为 Amazon Bedrock AgentCore 的一项能力，提供本地云监控工具开箱即用不具备的原生追踪、监控和分析，但它原生只支持部署在 AWS 云中 AgentCore 运行时上的智能体。如果智能体运行在其他任何地方，你需要额外配置，才能把遥测发送到仪表板。

本文说明如何为运行在 AWS 之外的智能体建立可观测性。你将学习如何在非 AWS 环境中配置 AWS Distro for OpenTelemetry（ADOT）自动插桩，把遥测路由到 AgentCore Observability 仪表板，并端到端验证这套配置。

下图展示端到端可观测性流水线，以及遥测如何从智能体流向 AgentCore Observability 仪表板。

图 1：从智能体到 AgentCore Observability 仪表板的端到端可观测性流水线

方案概览

该方案使用与智能体应用在同一进程内运行的 AWS Distro for OpenTelemetry（ADOT）。ADOT 自动为智能体框架插桩，采集生成式 AI 语义约定跨度（span），然后使用 AWS Identity and Access Management（IAM）凭证，通过 SigV4 认证，把遥测直接导出到 Amazon CloudWatch 的 OpenTelemetry 协议（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。
• 你的环境能够通过出站 HTTPS 访问 AWS 端点。

开启 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
# Expected: {"Destination": "CloudWatchLogs", "Status": "ACTIVE"}

工作原理

ADOT 自动插桩（aws-opentelemetry-distro）负责把遥测从非 AWS 环境导出到 CloudWatch 的复杂过程：

1. 自动插桩：opentelemetry-instrument 命令把 ADOT 注入 Python 运行时。它会自动修补 boto3（用于 Amazon Bedrock 调用）和 Strands 框架（用于智能体推理跨度），以发出 OpenTelemetry 追踪。
2. SigV4 认证：aws_configurator 使用 boto3 凭证链，用 SigV4 为 OTLP 导出请求签名。在非 AWS 环境中，这使用 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 环境变量。
3. CloudWatch OTLP 端点：ADOT 把追踪和日志导出到 CloudWatch 原生 OTLP 接入端点。OTEL_EXPORTER_OTLP_LOGS_HEADERS 请求头把日志导向特定的 AgentCore 日志组，CloudWatch 据此把数据索引到生成式 AI 可观测性仪表板下。关于 CloudWatch OTLP 端点 URL 如何确定和配置，见 CloudWatch OTLP 端点。
4. 生成式 AI 语义约定：Strands 的 [otel] 包按照 OpenTelemetry 生成式 AI 语义约定 发出跨度，包括智能体推理步骤、工具调用，以及带令牌用量的模型调用。

下图展示遥测如何通过 ADOT 自动插桩，从非 AWS 环境导出到 CloudWatch。

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

演练

按以下步骤，在非 AWS 环境中配置并运行一个 Strands 智能体，并把遥测路由到 AgentCore Observability。

步骤 1：安装依赖

在你的非 AWS 环境（本地服务器、GCP 虚拟机、Azure 虚拟机，或任何能访问互联网的计算环境）上：

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

aws-opentelemetry-distro 包包含 ADOT 自动插桩、面向 AWS 的 OTLP 导出器，以及处理 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 签名。
• 带有 aws.log.group.names 的 OTEL_RESOURCE_ATTRIBUTES 告诉 CloudWatch 把遥测索引到 AgentCore Observability 仪表板下。没有这项设置，追踪会进入通用的 Amazon CloudWatch Logs。
• 带有 x-aws-metric-namespace=bedrock-agentcore 的 OTEL_EXPORTER_OTLP_LOGS_HEADERS 把 嵌入式指标格式 的指标路由到正确的 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 命令用 ADOT 包装你的 Python 进程，自动为 Amazon Bedrock 调用和 Strands 框架操作插桩：

opentelemetry-instrument python3.12 agent_test.py

智能体的响应会出现在终端中。在后台，ADOT 采集追踪、跨度和日志，并把它们导出到 CloudWatch。

步骤 6：在 AgentCore Observability 中验证

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

1. 选择 GenAI Observability，然后选择 Bedrock AgentCore。
2. 在 Agents 选项卡中，查找 my-external-agent。
3. 选择该智能体，查看会话、追踪和跨度指标。

下面的截图展示运行在非 AWS 环境中的 Strands 智能体（my-external-agent）的遥测，出现在 CloudWatch 的 AgentCore Observability 仪表板中。

图 4：AgentCore Observability 仪表板中的 my-external-agent 遥测

控制台显示：

• 智能体名称：my-external-agent。
• 会话：至少有一个会话。
• 追踪：展示智能体推理和 Amazon Bedrock 模型调用的追踪跨度。
• 跨度详情：invoke_agent、chat、execute_event_loop_cycle 和 chat.us.anthropic.claude-haiku 跨度，以及延迟和令牌指标。

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

图 5：my-external-agent 的追踪详情，包含跨度、延迟和令牌指标

从 Google Cloud Platform 验证

为确认该方案在第三方云上可用，我们在 Google Cloud Shell 上测试了同一套配置。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）返回成功响应。

图 6：在 Google Cloud Shell 中运行的 gcp-hosted-agent

验证跨云遥测

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

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

图 7：运行在 GCP 上的 gcp-hosted-agent 的追踪详情

这些遥测与 AgentCore 运行时托管的智能体所产生的遥测相同。无论智能体运行在哪里，会话、追踪、跨度指标、令牌用量和延迟都显示在同一个仪表板中。

虽然本演练使用 Strands Agents，同一套基于 ADOT 的模式也适用于其他兼容 OpenTelemetry 的智能体框架。

在选择如何部署 AI 智能体时，理解不同运行时环境之间的可观测性取舍，有助于做出正确的架构决策。直接部署在 Amazon Bedrock AgentCore 运行时上的智能体可以获得自动可观测性配置。运行在非 AWS 环境中的智能体需要额外的手工设置，但部署灵活性更高。下面的比较突出遥测采集、凭证管理和适用场景上的关键差异，帮助你按需求确定最合适的做法。

已验证的环境

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

最佳实践

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

1. 使用一致的命名：OTEL_RESOURCE_ATTRIBUTES 中的 service.name 会成为仪表板上的智能体名称。使用能标识环境的描述性名称（例如 prod-onprem-support-agent 和 staging-gcp-research-agent）。
2. 先用 get-caller-identity 验证：运行智能体之前，执行 python -c "import boto3; print(boto3.client('sts').get_caller_identity())"，确认凭证可用。如果这一步失败，ADOT 也会静默失败。
3. 使用 Python 3.10 或更高版本：ADOT 要求 Python 3.10 或更高版本。我们建议使用 Python 3.12，以便与全部依赖获得最好的兼容性。
4. 为多轮对话设置会话 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)

5. 定期轮换凭证：生产部署应避免长期访问密钥。本地工作负载可考虑 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 内部的智能体。使用 ADOT 自动插桩、IAM 凭证和正确的 OpenTelemetry 环境变量，你可以从任何能访问互联网的环境发送遥测。智能体可以运行在本地、GCP、Azure 或其他任何地方，仍然上报到同一个 AgentCore Observability 仪表板。

这套设置需要一次 pip install 和一组环境变量。得到的遥测与 AgentCore 运行时托管的智能体所产生的遥测相同：会话、追踪、跨度指标和令牌用量，都在同一个统一视图中。

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

对于已经运行在 AWS 上但位于 AgentCore 运行时之外的智能体（EKS、ECS、Lambda），请参阅 面向 EKS 托管智能体的 AgentCore Observability 教程。对于 AgentCore 运行时上的智能体，可观测性会自动配置。见 为 AgentCore 资源添加可观测性。

PRIMARY_SOURCE: https://aws.amazon.com/blogs/machine-learning/monitor-on-premises-and-multi-cloud-ai-agents-with-agentcore-observability