AgentCore Observability の使用を開始する

Amazon Bedrock Amazon Bedrock AgentCore Observability は、本番環境でのエージェントパフォーマンスのトレース、デバッグ、モニタリングに役立ちます。このガイドは、エージェントアプリケーションにオブザーバビリティ機能を実装するのに役立ちます。

前提条件

開始する前に、以下を確認してください。

Amazon Bedrock AgentCore Observability には、さまざまなインフラストラクチャニーズに合わせてモニタリングを設定する方法が 2 つあります。

AWS アカウントごとに 1 回限りの設定として、ユーザーが初めて Amazon CloudWatch でトランザクション検索を有効にする必要があります。これを行うには、API と CloudWatch コンソールの 2 つの方法があります。

ステップ 1: CloudWatch でトランザクション検索を有効にする

トランザクション検索を有効にすると、スパンが検索と分析に使用できるようになるまでに 10 分かかる場合があります。以下のいずれかのオプションを選択します。

オプション 1: API を使用してトランザクション検索を有効にする

API を使用してトランザクション検索を有効にするには

オプション 2: CloudWatch コンソールでトランザクション検索を有効にする

CloudWatch コンソールでトランザクション検索を有効にするには

次に、オブザーバビリティを設定する 2 つの方法を見てみましょう。

ステップ 2: Amazon Bedrock AgentCore ランタイムホストエージェントのオブザーバビリティを有効にする

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 ランタイムで実行され、OpenTelemetry を使用して自動的に計測されます。エージェントを呼び出し、Amazon CloudWatch の GenAI Observability ダッシュボードでトレース、セッション、メトリクスを表示します。

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: Amazon Bedrock AgentCore でホストされていないエージェントのオブザーバビリティを有効にする

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 Observability ダッシュボードとログでこのエージェントを識別します。

ローカルでエージェントを作成する

# 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)

自動計測コマンドを使用してエージェントを実行する

requirements.txt aws-opentelemetry-distroの では、 opentelemetry-instrument コマンドは次のようになります。

次のコマンドを使用して、自動計測でエージェントを実行します。

opentelemetry-instrument python agent.py

AWS Lambda でエージェントをホストする場合は、 AWS Distro AWS for OpenTelemetry ウェブサイトの Lambda Layer for OpenTelemetry を使用します。関数に Layer を追加し、AWS_LAMBDA_EXEC_WRAPPER環境変数を に設定します/opt/otel-instrument。次に、レイヤーは関数を自動計測します。この方法では、aws-opentelemetry-distroパッケージを追加したり、前述のopentelemetry-instrumentコマンドを実行したりする必要はありません。

環境変数で設定した YOUR-AGENT-NAME の値を使用して、Amazon CloudWatch の GenAI Observability Dashboard でトレース、セッション、メトリクスを表示できるようになりました。

複数のエージェント実行にまたがるトレースを関連付けるには、OpenTelemetry パーティクルを使用してセッション ID をテレメトリデータに関連付けることができます。

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

ステップ 4: Amazon CloudWatch で GenAI オブザーバビリティを使用してエージェントを監視する

オブザーバビリティを実装したら、CloudWatch で収集されたデータを表示できます。

エージェントを監視する

CloudWatch のログを表示

CloudWatch でログを表示するには

トレースとスパンを表示します

トレースとスパンを表示するには

メトリクスの表示

メトリクスを表示するには

ベストプラクティス