开始使用可 AgentCore 观察性

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

先决条件

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

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

作为每个 AWS 账户一次性设置，首次使用的用户需要在 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 CLI 创建新项目。这将设置您的项目文件夹、虚拟环境和依赖关系：

npm install -g @aws/agentcore
agentcore create --name StrandsClaudeGettingStarted

在项目的代理目录中，用您自己的代理逻辑替换默认代理代码。以下是使用 Strands Agents 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")
    response = agent(user_input)
    return response.message['content'][0]['text']

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

部署并调用您的代理

将代理部署到 AgentCore 运行时。 AgentCore CLI 负责打包、部署和自动化 OTEL 工具：

cd StrandsClaudeGettingStarted
agentcore deploy

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

agentcore invoke

或者，您可以使用 AWS 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 上的代理示例。

配置 AWS 环境变量

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

<YOUR-AGENT-NAME>替换为唯一的名称，以便在 GenAI 可观察性控制面板和日志中识别此代理。

在本地创建代理

# 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

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

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

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

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

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

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

观察你的经纪人

查看日志 CloudWatch

要查看登录信息 CloudWatch

查看跟踪数据与跨度信息

查看轨迹和跨度

查看指标

查看指标

最佳实践