Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

开始使用 AgentCore 可观测性

Amazon Bedrock 可 AgentCore 观测性可帮助您跟踪、调试和监控生产环境中的代理性能。本指南可帮助您在代理应用程序中实现可观察性功能。

先决条件

在开始之前，请确保你有：

Amazon Bedrock AgentCore 可观测性提供了两种配置监控以满足不同的基础设施需求的方法：

作为每个 Amazon 账户的一次性设置，首次使用的用户需要在亚马逊上启用交易搜索 CloudWatch。有两种方法可以做到这一点，即通过 API 和通过 CloudWatch 控制台。

步骤 1：启用交易搜索 CloudWatch

启用 Transaction Search 后，可能需要十分钟才能使用跨度进行搜索和分析。选择以下选项之一：

选项 1：使用 API 启用交易搜索

使用 API 启用交易搜索

选项 2：在 CloudWatch 控制台中启用交易搜索

在 CloudWatch 控制台中启用交易搜索

现在让我们继续探索配置可观测性的两种方法。

第 2 步：为 Amazon Bedrock AgentCore Runtime 托管的代理启用可观察性

Amazon Bedrock AgentCore Runtime-hosted 代理直接在 Amazon Bedrock AgentCore 环境中部署和执行，以最少的配置提供自动检测。当您使用 AgentCore CLI 部署代理时，运行时会自动为您的代理进行检 OpenTelemetry 测，无需额外的 OTEL 库或配置。

有关完整示例，请参阅上的可AgentCore 观测性示例 GitHub

创建您的代理项目

使用 AgentCore CLI 创建新项目。这将设置您的项目文件夹、虚拟环境和依赖关系：

npm install -g @aws/agentcore
agentcore create \
  --project-name StrandsObservability \
  --name StrandsClaudeGettingStarted \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none
cd StrandsObservability/app/StrandsClaudeGettingStarted
uv add strands-agents-tools
cd ../..

在项目的代理目录中，用您自己的代理逻辑替换默认代理代码。以下是使用 Strands 代理 SDK 的示例：

## app/StrandsClaudeGettingStarted/main.py
from strands import Agent, tool
from strands_tools import calculator
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands.models import BedrockModel

app = BedrockAgentCoreApp()

@tool
def weather():
    """Get weather"""
    return "sunny"

model = BedrockModel(
    model_id="us.anthropic.claude-3-7-sonnet-20250219-v1:0",
)
agent = Agent(
    model=model,
    tools=[calculator, weather],
    system_prompt="You're a helpful assistant. You can do simple math calculation, and tell the weather."
)

@app.entrypoint
def strands_agent_bedrock(payload):
    """Invoke the agent with a payload"""
    user_input = payload.get("prompt")
    if not isinstance(user_input, str) or not user_input:
        return "Error: 'prompt' must be a non-empty string"
    response = agent(user_input)
    return response.message['content'][0]['text']

if __name__ == "__main__":
    app.run()

部署和调用您的代理

将代理部署到 AgentCore 运行时。 AgentCore CLI 处理打包、部署和自动 OTEL 仪器：

agentcore deploy

部署后，您的代理在 AgentCore Runtime 上运行，并使用 OpenTelemetry自动进行检测。调用您的代理并在亚马逊的 GenAI 可观察性控制面板上查看跟踪、会话和指标： CloudWatch

agentcore invoke

或者，您可以使用 Amazon SDK 以编程方式调用代理：

import boto3, json

client = boto3.client('bedrock-agentcore')

response = client.invoke_agent_runtime(
    agentRuntimeArn="YOUR_AGENT_RUNTIME_ARN",
    runtimeSessionId="my-observability-session-001",
    payload=json.dumps({"prompt": "What is 2 + 2?"}),
    qualifier="DEFAULT"
)

print(json.loads(response['response'].read()))

第 3 步：为非亚马逊 Bedrock 代理启用可观察性 AgentCore-hosted

对于在 Amazon Bedrock AgentCore 运行时之外运行的代理，您可以为部署在自己的基础设施上的代理提供相同的监控功能。无论您的代理在何处运行，这都可实现一致的可观察性。使用以下步骤配置观察代理所需的环境变量。

有关完整示例，请参阅 GitHub 网站上的 Amazon EKS 上的代理示例。

配置 Amazon 环境变量

export AWS_ACCOUNT_ID=<account id>
export AWS_DEFAULT_REGION=<default region>
export AWS_REGION=<region>
export AWS_ACCESS_KEY_ID=<access key id>
export AWS_SECRET_ACCESS_KEY=<secret key>

配置 CloudWatch 日志

为您的代理在 Amazon 中创建日志组和日志流 CloudWatch ，您可以使用它来配置以下环境变量。

配置 OpenTelemetry 环境变量

export AGENT_OBSERVABILITY_ENABLED=true # Activates the ADOT pipeline
export OTEL_PYTHON_DISTRO=aws_distro # Uses AWS Distro for OpenTelemetry
export OTEL_PYTHON_CONFIGURATOR=aws_configurator # Sets AWS configurator for ADOT SDK
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf # Configures export protocol
export  OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-LOG-STREAM>,x-aws-metric-namespace=<YOUR-NAMESPACE>
# Directs logs to CloudWatch groups
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-TRACES-LOG-STREAM>
# (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
export OTEL_RESOURCE_ATTRIBUTES=service.name=<YOUR-AGENT-NAME> # Identifies your agent in observability data
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
export OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
export OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

在 GenAI <YOUR-AGENT-NAME> 可观测性仪表板和日志中替换为唯一名称以标识此代理。

在本地创建代理

# Create agent.py -  Strands agent that is a weather assistant
from strands import Agent
from strands_tools import http_request

# Define a weather-focused system prompt
WEATHER_SYSTEM_PROMPT = """You are a weather assistant with HTTP capabilities. You can:

1. Make HTTP requests to the National Weather Service API
2. Process and display weather forecast data
3. Provide weather information for locations in the United States

When retrieving weather information:
1. First get the coordinates or grid information using https://api.weather.gov/points/{latitude},{longitude} or https://api.weather.gov/points/{zipcode}
2. Then use the returned forecast URL to get the actual forecast

When displaying responses:
- Format weather data in a human-readable way
- Highlight important information like temperature, precipitation, and alerts
- Handle errors appropriately
- Convert technical terms to user-friendly language

Always explain the weather conditions clearly and provide context for the forecast.
"""

# Create an agent with HTTP capabilities
weather_agent = Agent(
    system_prompt=WEATHER_SYSTEM_PROMPT,
    tools=[http_request],  # Explicitly enable http_request tool
)

response = weather_agent("What's the weather like in Seattle?")
print(response)

使用自动检测命令运行代理

aws-opentelemetry-distro在你的 requirements.txt 中，该opentelemetry-instrument命令将：

使用以下命令使用自动工具运行代理：

opentelemetry-instrument python agent.py

如果您在 Amazon Lambda 上托管代理，请在 Amazon 发行版 OpenTelemetry网站上使用 Amazon Lambda 层。 OpenTelemetry 将该层添加到您的函数，然后将AWS_LAMBDA_EXEC_WRAPPER环境变量设置为/opt/otel-instrument。然后，该层会自动整理您的函数。使用这种方法，您无需添加aws-opentelemetry-distro软件包或运行前面描述的opentelemetry-instrument命令。

现在，您可以使用您在环境变量中配置的值在亚马逊 CloudWatch 的 GenAI 可观测性控制面板上查看您的跟踪、会话和指标。 YOUR-AGENT-NAME

要关联多个代理运行中的跟踪，您可以使用行李将会话 ID 与您的遥测 OpenTelemetry 数据关联起来：

from opentelemetry import baggage, context
ctx = baggage.set_baggage("session.id", session_id)

第 4 步：在亚马逊上使用 GenAI 可观察性观察您的代理 CloudWatch

实现可观测性后，可以在以下位置查看收集的数据： CloudWatch

观察你的经纪人

查看日志 CloudWatch

查看登录信息 CloudWatch

查看跟踪数据与跨度信息

查看轨迹和跨度

查看指标

查看指标

最佳实践