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

为您的亚马逊 Bedro AgentCore ck 资源添加可观察性

Amazon Bedrock AgentCore 提供了许多内置指标，用于监控 AgentCore 运行时、内存、网关、内置工具和身份资源类型的资源性能。此默认数据可在亚马逊上找到 CloudWatch。要在 CloudWatch 控制台中查看全部可观测性数据，或输出代理的自定义运行时指标，您需要使用开放遥测 AWS 发行版 (ADOT) SDK 对代码进行检测。

要在中查看可观测性控制面板 CloudWatch，请打开亚马逊 CloudWatch GenAi 可观测性页面。

请参阅以下部分，详细了解如何配置资源以在 CloudWatch 控制台生成式 AI 可观测性页面和日志中查看可观测性指标。 CloudWatch

启用可 AgentCore 观察性

要查看该 AgentCore 服务生成的指标、跨度和跟踪，您首先需要完成一次性设置才能开启亚马逊 CloudWatch 交易搜索。要查看服务提供的内存资源跨度，还需要在创建内存时启用跟踪。要了解更多信息，请参阅为 AgentCore 运行时、内存、网关、内置工具和身份资源启用可观察性。

以下各节介绍如何执行这些设置操作以及如何在代理代码中启用可观察性。

启用 CloudWatch 交易搜索

您可以使用 CloudWatch 控制台启用 CloudWatch 交易搜索，也可以通过 AWS 命令行接口 (AWS CLI) 或其中一个 AWS 软件开发工具包使用 API 来启用事务搜索。

使用以下过程之一启用事务搜索。

亚马逊 Bedrock AgentCore 运行时中托管的代理的跨度目的地

借 AgentCore 助 Amazon Bedrock 的运行时功能 AgentCore，您可以配置代理将其跨度传送到与代理 CloudWatch 日志相同的亚马逊日志组。使用此配置，跨度将转到spans日志流中/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>，而不是共享aws/spans日志组。您可以将跨度、结构化日志和标准输出一起保存在一个每个代理的日志组中，将访问控制和加密范围限制为单个代理，并从单个位置导出遥测数据。

在支持的 AWS 区域中，新创建的代理使用代理的日志组作为默认跨度目标。在区域支持统一 span 目标之前创建的代理会将共享aws/spans日志组保留为其默认值。

您可以在代理运行时使用UNIFIED_TRACES_DESTINATION_ENABLED环境变量覆盖单个代理的默认值：

AgentCore 要将跨度传送到代理的日志组，必须满足以下条件：

更改跨度目标不会移动现有的跨度数据。 AgentCore 已经交付的 Span 仍保留在其原始日志组中。

在代理代码中为 AgentCore-hosted 代理启用可观察性

除了服务生成的指标外， AgentCore 您还可以收集跨度和跟踪数据以及代理代码发出的自定义指标。

当您将 Strand s或 CreWAI等代理框架与支持的第三方工具库一起使用时，该框架本身内置了对OTEL和GenAI语义约定的支持，也可以使用诸如以下的自动仪器包进行检测。 LangChain opentelemetry-instrument-langchain还可以通过定义自定义跟踪器来发送生成式 AI 语义约定遥测和跨度。 AgentCore 支持在代理框架中使用以下仪器库：

要在 CloudWatch 控制台生成式 AI 可观测性页面和亚马逊中查看这些数据 CloudWatch，您需要将开放遥测 AWS 发行版 (ADOT) SDK 添加到代理代码中。

要添加 ADOT 支持并启用 AgentCore 可观察性，请按照以下过程中的步骤操作。

为您的 AgentCore 代理添加可观察性

为托管在外部的代理启用可观察性 AgentCore

要为 AgentCore 运行时之外托管的代理启用可观察性，请首先按照前几节中的步骤启用 CloudWatch 交易搜索并将 ADOT SDK 添加到您的代码中。

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

对于在运行时之外 AgentCore 运行的代理，您还需要创建一个代理日志组，将其包含在环境变量中。

配置您的 AWS 环境变量，然后设置 Open Telemetry 环境变量，如下所示。

AWS 环境变量

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

OTEL 环境变量

AGENT_OBSERVABILITY_ENABLED=true
AWS_GENAI_CONTENT_EXTRACTION_OPT_OUT=true # Keeps model payloads and tool request/response data on spans. Requires ADOT >=0.18.0.
OTEL_PYTHON_DISTRO=aws_distro
OTEL_PYTHON_CONFIGURATOR=aws_configurator # required for ADOT Python only
OTEL_RESOURCE_ATTRIBUTES=service.name=<agent-name>,aws.log.group.names=/aws/bedrock-agentcore/runtimes/<agent-id>,cloud.resource_id=<AgentEndpointArn:AgentEndpointName> # endpoint is optional
OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=spans # (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

<agent-name>替换为您的代理人的姓名<agent-id>和代理人的唯一标识符。

会话 ID 支持

要传播会话 ID，您需要在 OTEL 行李中使用会话标识符进行调用：

from opentelemetry import baggage

ctx = baggage.set_baggage("session.id", session_id) # Set the session.id in baggage
attach(ctx) # Attach the context to make it active token

为 AgentCore 运行时、内存、网关、内置工具和身份资源启用可观察性

创建 AgentCore 运行时资源（代理）时，默认情况下， AgentCore 运行时会为服务提供的 CloudWatch 日志创建一个日志组。但是，对于内存、网关和内置工具资源， AgentCore 不会自动为您配置日志目的地。

对于内存和网关资源，您可以在控制台中或使用 AWS SDK 配置日志目的地。如果您使用控制台配置 CloudWatch 日志目标，则内存和网关资源的默认日志组名称的格式/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}{resource-type}为memory或gateway。

对于内存和网关日志，您还可以使用 AgentCore 控制台在 Amazon S3 日志或 Firehose 流日志中配置日志目的地。要了解有关在 Amazon S3 或 Firehose 中存储日志的更多信息，请参阅在 Amazon S3 中上传、下载和处理对象和创建亚马逊数据 Firehose 传输流。

要详细了解内存和网关资源输出的 AgentCore 日志数据，请参阅提供的日志数据（内存）或提供的日志数据（网关）。

对于内置工具资源，该 AgentCore 服务默认不提供日志，但您可以从代码中输出自己的日志。如果您提供自己的日志输出，则需要手动配置日志目标以存储这些数据。

要查看每种资源类型默认 AgentCore 提供的可观测性数据，请参阅 Amazon Bedrock AgentCore 生成的可观测性数据。

使用控制台配置日志目的地

要在 AgentCore 控制台中配置内存或网关日志的日志目的地，请使用以下步骤。

CloudWatch 使用控制台将跟踪交付配置为

本节介绍如何启用跟踪交付 CloudWatch 以跟踪应用程序中的交互流程，从而使您能够可视化请求、识别性能瓶颈、排除错误和优化性能。

使用配置 CloudWatch 资源 AWS SDK

为日志和跟踪配置传送源 (SDK)

import boto3

def enable_observability_for_resource(resource_arn, resource_id, account_id, region='us-east-1'):
    """
    Enable observability for a Bedrock AgentCore resource (e.g., Memory Store)
    """
    logs_client = boto3.client('logs', region_name=region)

    # Step 0: Create new log group for vended log delivery
    log_group_name = f'/aws/vendedlogs/bedrock-agentcore/{resource_id}'
    logs_client.create_log_group(logGroupName=log_group_name)
    log_group_arn = f'arn:aws:logs:{region}:{account_id}:log-group:{log_group_name}'

    # Step 1: Create delivery source for logs
    logs_source_response = logs_client.put_delivery_source(
        name=f"{resource_id}-logs-source",
        logType="APPLICATION_LOGS",
        resourceArn=resource_arn
    )

    # Step 2: Create delivery source for traces
    traces_source_response = logs_client.put_delivery_source(
        name=f"{resource_id}-traces-source",
        logType="TRACES",
        resourceArn=resource_arn
    )

    # Step 3: Create delivery destinations
    logs_destination_response = logs_client.put_delivery_destination(
        name=f"{resource_id}-logs-destination",
        deliveryDestinationType='CWL',
        deliveryDestinationConfiguration={
            'destinationResourceArn': log_group_arn,
        }
    )

    # Traces required
    traces_destination_response = logs_client.put_delivery_destination(
        name=f"{resource_id}-traces-destination",
        deliveryDestinationType='XRAY'
    )

    # Step 4: Create deliveries (connect sources to destinations)
    logs_delivery = logs_client.create_delivery(
        deliverySourceName=logs_source_response['deliverySource']['name'],
        deliveryDestinationArn=logs_destination_response['deliveryDestination']['arn']
    )

    # Traces required
    traces_delivery = logs_client.create_delivery(
        deliverySourceName=traces_source_response['deliverySource']['name'],
        deliveryDestinationArn=traces_destination_response['deliveryDestination']['arn']
    )

    print(f"Observability enabled for {resource_id}")
    return {
        'logs_delivery_id': logs_delivery['id'],
        'traces_delivery_id': traces_delivery['id']
    }

# Usage example
resource_arn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/my-memory-id"
resource_id = "my-memory-id"
account_id = "123456789012"

delivery_ids = enable_observability_for_resource(resource_arn, resource_id, account_id)

使用自定义 AgentCore 标头增强运行时可观察性

您可以使用其他 HTTP 标头来调用代理，以提供增强的可观察性选项。以下示例显示了调用，包括对运行时托管的代理的可选附加标头请求。 AgentCore

Boto3 调用示例

def invoke_agent(agent_id, payload, session_id=None):
    client = boto3.client("bedrock-agentcore", region="us-west-2")
    response = client.invoke_agent_runtime(
        agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test_agent_boto2-nIg2xk3VSR",
        runtimeSessionId="12345678-1234-5678-9abc-123456789012",
        payload='{"query": "Plan a weekend in Seattle"}',
    )

在调用代理以增强可观察性和跟踪能力时，可以包含以下可选标头：

使用自定义标头增强 AgentCore 内置工具的可观察性

您可以使用其他 HTTP 标头来调用您的 Built-in 工具，以提供增强的可观察性选项。在集成以下 T Build-in ools API 时，您可以添加以下可选标头以增强可观察性和跟踪能力：

以下 API 支持自定义标头：

使用自定义标头增强 AgentCore 身份可观察性

您可以使用其他 HTTP 标头来调用您的身份资源，以提供增强的可观察性选项。在集成以下身份 API 时，您可以添加以下可选标头以增强可观察性和跟踪能力：

以下 API 支持自定义标头：

可观测性最佳实践

在中实现代理的可观察性时，请考虑以下最佳实践： AgentCore

使用其他可观测性平台

要将 AgentCore 运行时中托管的代理与其他可观测性平台集成以捕获和查看遥测输出，请设置以下环境变量：

DISABLE_ADOT_OBSERVABILITY=true

将此变量设置为true取消设置 AgentCore 运行时的默认 ADOT 环境变量，从而确保未设置任何默认 ADOT 配置。