Amazon Bedrock AgentCore リソースにオブザーバビリティを追加する

Amazon Bedrock AgentCore には、AgentCore ランタイム、メモリ、ゲートウェイ、組み込みツール、および ID リソースタイプのリソースのパフォーマンスをモニタリングするための組み込みメトリクスが多数用意されています。このデフォルトデータは Amazon CloudWatch で使用できます。CloudWatch コンソールでオブザーバビリティデータの全範囲を表示したり、エージェントのカスタムランタイムメトリクスを出力したりするには、 AWS Distro for Open Telemetry (ADOT) SDK を使用してコードを計測する必要があります。

CloudWatch でオブザーバビリティダッシュボードを表示するには、Amazon CloudWatch GenAi Observability ページを開きます。

CloudWatch コンソールの生成 AI オブザーバビリティページと CloudWatch Logs でオブザーバビリティメトリクスを表示するようにリソースを設定する方法の詳細については、以下のセクションを参照してください。

AgentCore オブザーバビリティの有効化

AgentCore サービスによって生成されたメトリクス、スパン、トレースを表示するには、まず 1 回限りのセットアップを完了して Amazon CloudWatch トランザクション検索を有効にする必要があります。メモリリソースのサービスが提供するスパンを表示するには、メモリの作成時にトレースを有効にする必要もあります。詳細については、AgentCore ランタイム、メモリ、ゲートウェイ、組み込みツール、および ID リソースのオブザーバビリティを有効にする」を参照してください。

以下のセクションでは、これらのセットアップアクションを実行し、エージェントコードでオブザーバビリティを有効にする方法について説明します。

CloudWatch トランザクション検索の有効化

CloudWatch トランザクション検索を有効にするには、CloudWatch コンソールを使用するか、コマンドラインインターフェイス (AWS CLI) またはいずれかの AWS SDKs AWS を介して API を使用します。

トランザクション検索を有効にするには、次のいずれかの手順を使用します。

Amazon Bedrock AgentCore ランタイムでホストされるエージェントのスパン送信先

Amazon Bedrock AgentCore の一機能である AgentCore ランタイムを使用すると、エージェントのログと同じ Amazon CloudWatch ロググループにスパンを配信するようにエージェントを設定できます。この設定では、スパンは共有spansロググループではなく /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>のaws/spansログストリームに移動します。スパン、構造化ログ、標準出力をエージェントごとに 1 つのロググループにまとめ、アクセスコントロールと暗号化の範囲を個々のエージェントに設定し、テレメトリを 1 つの場所からエクスポートできます。

サポートされている AWS リージョンでは、新しく作成されたエージェントはエージェントのロググループをデフォルトのスパン送信先として使用します。リージョンが統合スパン送信先をサポートする前に作成されたエージェントは、共有aws/spansロググループをデフォルトとして保持します。

個々のエージェントのデフォルトを、エージェントのランタイムの UNIFIED_TRACES_DESTINATION_ENABLED環境変数で上書きできます。

AgentCore がエージェントのロググループにスパンを配信するには、次の条件が満たされている必要があります。

スパン送信先を変更しても、既存のスパンデータは移動されません。AgentCore が既に配信したスパンは、元のロググループに残ります。

AgentCore がホストするエージェントのエージェントコードでオブザーバビリティを有効にする

AgentCore では、サービス生成メトリクスに加えて、エージェントコードから出力されるカスタムメトリクスだけでなく、スパンとトレースデータを収集することもできます。

サポートされているサードパーティーの計測ライブラリで Strands 、LangChain 、または CrewAI などのエージェントフレームワークを使用する場合、フレームワーク自体には OTEL および GenAI セマンティック規則のサポートが組み込まれており、 opentelemetry-instrument-langchain などの自動計測パッケージを使用して計測することもできます。カスタムトレーサーを定義することで、生成 AI セマンティック規則のテレメトリとスパンを送信することもできます。AgentCore は、エージェントフレームワークでの次の計測ライブラリの使用をサポートしています。

このデータを CloudWatch コンソールの生成 AI オブザーバビリティページと Amazon CloudWatch AWS で表示するには、Distro for Open Telemetry (ADOT) SDK をエージェントコードに追加する必要があります。

ADOT サポートを追加し、AgentCore オブザーバビリティを有効にするには、以下の手順に従います。

AgentCore エージェントにオブザーバビリティを追加する

AgentCore の外部でホストされているエージェントのオブザーバビリティを有効にする

AgentCore ランタイムの外部でホストされているエージェントのオブザーバビリティを有効にするには、まず前のセクションの手順に従って CloudWatch トランザクション検索を有効にし、コードに ADOT SDK を追加します。

AWS Lambda でエージェントをホストする場合は、 AWS Distro AWS for OpenTelemetry ウェブサイトの Lambda Layer for OpenTelemetry を使用します。関数に Layer を追加し、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
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 ランタイム、メモリ、ゲートウェイ、組み込みツール、および ID リソースのオブザーバビリティを有効にする

AgentCore ランタイムリソース (エージェント) を作成すると、デフォルトで、AgentCore ランタイムはサービスが提供するログの CloudWatch ロググループを作成します。ただし、メモリ、ゲートウェイ、組み込みツールリソースの場合、AgentCore はログ送信先を自動的に設定しません。

メモリおよびゲートウェイリソースの場合、コンソールまたは AWS SDK を使用してログの送信先を設定できます。コンソールを使用して CloudWatch Logs の送信先を設定する場合、メモリとゲートウェイリソースのデフォルトのロググループ名は /aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id} の形式になります。ここで、 {resource-type} は memoryまたは ですgateway。

メモリログとゲートウェイログの場合、AgentCore コンソールを使用して Amazon S3 ログまたは Firehose ストリームログのログ送信先を設定することもできます。Amazon S3 または Firehose にログを保存する方法の詳細については、Amazon S3」および「Amazon Data Firehose 配信ストリームの作成」を参照してください。

AgentCore によるメモリおよびゲートウェイリソースのログデータ出力の詳細については、「提供ログデータ (メモリ)」または「提供ログデータ (ゲートウェイ)」を参照してください。

組み込みツールリソースの場合、AgentCore サービスはデフォルトでログを提供しませんが、コードから独自のログを出力できます。独自のログ出力を指定する場合は、このデータを保存するようにログの送信先を手動で設定する必要があります。

AgentCore がリソースタイプごとにデフォルトで提供するオブザーバビリティデータを確認するには、「Amazon Bedrock AgentCore が生成したオブザーバビリティデータ」を参照してください。

コンソールを使用してログの送信先を設定する

AgentCore コンソールでメモリまたはゲートウェイログのログ送信先を設定するには、次の手順を使用します。

コンソールを使用して CloudWatch へのトレース配信を設定する

このセクションでは、CloudWatch へのトレース配信を有効にして、アプリケーションを介したインタラクションの流れを追跡し、リクエストの視覚化、パフォーマンスのボトルネックの特定、エラーのトラブルシューティング、パフォーマンスの最適化を行う方法について説明します。

AWS SDK を使用して CloudWatch リソースを設定する

ログとトレースの配信ソースを設定するには (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 ヘッダーで呼び出して、オブザーバビリティオプションを強化できます。次の組み込みツール APIs を統合するときに、次のオプションのヘッダーを含めて、オブザーバビリティとトレース機能を強化できます。

次の APIsカスタムヘッダーをサポートしています。

カスタムヘッダーによる AgentCore ID オブザーバビリティの強化

追加の HTTP ヘッダーを使用して ID リソースを呼び出し、オブザーバビリティオプションを強化できます。次の ID APIs を統合するときに、次のオプションのヘッダーを含めて、オブザーバビリティとトレース機能を強化できます。

次の APIsカスタムヘッダーをサポートしています。

オブザーバビリティのベストプラクティス

AgentCore でエージェントのオブザーバビリティを実装するときは、次のベストプラクティスを考慮してください。

他のオブザーバビリティプラットフォームの使用

AgentCore ランタイムでホストされているエージェントを他のオブザーバビリティプラットフォームと統合してテレメトリ出力をキャプチャして表示するには、次の環境変数を設定します。

DISABLE_ADOT_OBSERVABILITY=true

この変数を に設定すると、AgentCore ランタイムのデフォルトの ADOT 環境変数の設定trueが解除され、デフォルトの ADOT 設定が設定されなくなります。