Amazon Web Services ブログ

CloudWatch エージェントを用いたAI エージェントの監視方法

本記事は、2025 年 6 月 26 日に公開された Observing Agentic AI workloads using Amazon CloudWatch agent を翻訳したものです。翻訳はソリューションアーキテクトの鈴木が担当しました。

はじめに

AI エージェントアプリケーションの採用が拡大し続ける中、これらのシステムの信頼性、パフォーマンス、さらには全体的なオブザーバビリティを確保をすることがますます重要になってきています。大規模言語モデル（LLM）により駆動され、様々なデータソース、API と統合された AI エージェントアプリケーションは急速に複雑になる可能性があるため、その内部動作と全体的な健全性を観測することは困難になり得ます。

Strands Agents や Amazon Bedrock Agents、 LangChain などの AI エージェント開発のためのフレームワークは開発者に洗練された AI 駆動アプリケーションを構築・実行するためのツールを提供します。これらのフレームワークを用いることで LLM と必要なツールおよびデータソースとのシームレスな統合が可能となり、結果として開発者は複雑なタスクを自動化させ、より重要な仕事に集中することが可能となります。その一方で、AI エージェントアプリケーションが想定通りの顧客体験を生み出しているかを担保するためには包括的なオブザーバビリティが必須です。

このブログは Amazon CloudWatch によってどのように AI エージェントアプリケーションを監視し、インサイトを得ることができるかを解説します。具体的には三つのオブザーバビリティの柱であるメトリクス、トレース、ログについて、CloudWatch エージェントをどのように設定してこれらのテレメトリデータを取り込み、分析するかをデモします。

全体像

デモに先立ち、Strands Agents SDK を使用して Weather Forecaster というサンプルアプリケーションを作成します。

Weather Forecaster は Python で作成されたシンプルなエージェントアプリケーションで Amazon Bedrock 上の Claude Sonnet 3.7 モデルを使用しています。また、組み込みツールの http_request を使用して天気情報を National Weather Service API から取得します。

このアプリケーションは OpenTelemetry 仕様に準拠した Strands のトレース機能によって計装されます。そのため、LLM やリトリーバー、ツール、イベントループ処理などとエージェントとのあらゆるやりとりをキャプチャできます。

Strands Agents SDK は、エージェントの実行中に以下のような主要メトリクスを自動的に追跡します：

  • トークン使用量：入力トークン、出力トークン、消費された総トークン
  • パフォーマンスメトリクス：レイテンシと実行時間の測定
  • ツール使用量：各ツールの呼び出し回数、成功率、実行時間
  • イベントループサイクル：推論サイクルの数とその持続時間

この AI エージェントアプリケーションを観察しインサイトを得るために今回は Amazon CloudWatch を活用します。CloudWatch エージェントをインストール・設定して、Strands Agents SDK によって生成されるトレース、メトリクス、ログを含むテレメトリデータを収集します。

図1. サンプルアプリケーションの構成

CloudWatch エージェントによって収集されたトレースは、AWS X-Ray バックエンドに送信され、アプリケーション内でのリクエストの処理の流れを可視化します。メトリクスは埋め込みメトリクスフォーマット（EMF）ログとして収集され、CloudWatch Logs に送信されてバックエンドでカスタムメトリクスの生成に使用されます。さらに、CloudWatch エージェントはアプリケーションログを収集するように設定されており、CloudWatch Logs Insights を使用してクエリを実行することで、価値のある情報を抽出できます。

前提条件

この手順を進めるには、以下の条件を満たしている必要があります：

  • AI エージェントアプリケーションをデプロイしたいリージョン1に切り替え、以下を有効にします：
    1. Claude 3.7 Sonnet モデルのモデルアクセスを有効にする
    2. CloudWatch コンソールでトランザクション検索を有効にする。全体のトランザクション分析のため、全範囲をトレースサマリーとしてインデックス化する目的で、X-Ray trace indexing を100%に設定する

1原文では「デプロイしたいリージョン」とありますが、2025/08/18現在では US のリージョンのみでデプロイ可能であり、その他のリージョンでは Bedrock の権限の関係上、正常に動作しないことが確認されています。

デプロイ

アプリケーションコード、デプロイメントテンプレート、CloudWatch エージェントの設定ファイルは、GitHub リポジトリでホストされています。 サンプルアプリケーションをデプロイするためにAWS CloudFormation テンプレートを使用します。このテンプレートでは Amazon Elastic Cloud Compute（EC2）インスタンスを起動し、インスタンスのユーザーデータ内でセットアップスクリプトを実行します。このセットアップスクリプトは、必要なすべての依存関係をインストールし、提供された設定ファイルを使用して CloudWatch エージェントを設定し、アプリケーションによって生成されるテレメトリを収集します。

注意：このソリューションをデプロイすると、EC2、CloudWatch、X-Ray、Amazon Bedrock を含む使用される AWS サービスに対して料金が発生します。継続的なコストを避けるために、完了後はリソースをクリーンアップしてください。

EC2 インスタンスへのサンプルアプリケーションのデプロイ

  1. ec2-deployment.yaml という名前の CloudFormation をダウンロードします。
  2. サンプルアプリケーションをデプロイしたい AWS アカウントで AI エージェントアプリケーションをデプロイしたいリージョン2の CloudFormation コンソールに移動します。
  3. スタックの作成で、「新しいリソースを使用 (標準)」を選択します。
  4. テンプレートの指定で、「テンプレートファイルのアップロード」を選択します。ファイルを選択し、ステップ1でダウンロードしたテンプレートを選択します。
  5. 「次へ」を選択します。
  6. スタック名に、agentic-ai-python-appなどのスタック名を入力します。
  7. パラメータエリアで、図2に示すように以下のパラメータを入力します：
    1. EC2 InstanceType は、t3.medium 以上のスペックのインスタンスを選択することをお勧めします。
    2. LatestAmiId と GitHub Repository URL は、デフォルト値のままにします
    3. VPC ID と Subnet ID は、それぞれドロップダウンから VPC とサブネット ID を選択します。Weather API に到達するためのアウトバウンドインターネットアクセスが可能なサブネットを選択します

      図 2: CloudFormation stack のインプット

  8. 「次へ」を選択します。
  9. スタックオプションの設定ページで、「AWS CloudFormation によって IAM リソースが作成される場合があることを承認します。」オプションを受け入れて「次へ」を選択します。
  10. 確認して作成ページで「送信」を選択します。
  11. テンプレートがデプロイされた後、出力を選択し、InstanceId をメモします。

2原文では「デプロイしたいリージョン」とありますが、2025/08/18現在では US のリージョンのみでデプロイ可能であり、その他のリージョンでは Bedrock の権限の関係上、正常に動作しないことが確認されています。

サンプルアプリケーションとのやりとり

  1. EC2 コンソールに移動し、図3に示すように、AWS Systems Manager の機能である Session Managerを使用して、前のセクションでメモしたインスタンスに接続します。

    図 3: EC2 インスタンスにセッションマネージャーを用いて接続

  2. 以下のコマンドを実行して Python アプリケーションを実行します
    sudo -i bash -c "cd /home/ec2-user/agentic-ai-app && python app.py"
  3. 図4に示すように、エージェントと対話し、天気情報を取得するための質問をすることができます。

    図 4: Weather Forecaster エージェントとの会話

  4. Strands エージェントは、http_request ツールを使用して Weather API を呼び出し、私たちのプロンプトに対する最終的な応答を生成するループで、Claude Sonnet 3.7 と相互作用しました。

次のセクションでは、AWS CloudWatch コンソールでアプリケーションによって生成されたテレメトリデータを分析する方法を探ります。

CloudWatch コンソール上でのテレメトリデータ分析

トレース分析

  1. AWS マネジメントコンソールの CloudWatch コンソールに移動します。
  2. Application Signals（APM）セクションに移動し、トレースマップを選択します。Strands Agent がトレースマップ内に表示されます。
  3. 図5に示すように、トレースマップの Strands Agent をクリックして、サンプルアプリケーションによって生成されたトレースを表示します。

    図 5: トレースマップ

  4. 図6のトレースは、応答時間、所要時間、各トレースのステータスを含む、リクエストに関する詳細情報を提供します。

    図 6: CloudWatch 上でのトレース

  5. 特定のトレースをより深く掘り下げるには、図7に示すように、トレースをクリックしてリクエストの完全なタイムラインを表示します。

    図 7: スパンのタイムラインと相関づけられたログ

  6. トレースタイムラインは、サイクル、呼び出されたモデル、実行されたツールを含む、エージェントの実行に関するすべての詳細を明らかにします。さらに、実行トレースでキャプチャされたデータとアプリケーションログを相関させることができます。
  7. トレース内の特定のステップやスパンのメタデータを表示するには、図8に示すように、スパンをクリックしてプロンプト、完了、結果に関する完全な詳細を表示します。

    図 8: スパンのメタデータ

トランザクション検索

Application Signals コンソールのトランザクション検索機能を使用してスパンを分析するには、以下の手順に従います。

    1. Application Signals コンソール内のトランザクション検索セクションに移動します。
    2. 図9に示すように、その ID を持つユーザーによって行われたすべてのリクエストを表示するために、フィルタ attributes.user.id = demo@example.com を追加します。

      図 9: トランザクション検索上でのスパンのフィルター

    3. 各 traceId をクリックして、プロンプト、完了、スパンでキャプチャされたその他のメタデータなど、その特定のリクエストの詳細をより深く分析できます。これにより、サンプルアプリケーションと対話する個々のユーザーのアクティビティを簡単に追跡・調査できます。
    4. ビジュアルエディタに加えて、Log Insight QL を使用して aws/spans ログループに対して高度なクエリを実行し、詳細情報を抽出することもできます。例えば、図10に示すように、総トークン使用量が10,000 tokensを超えるすべてのプロンプトを取得するクエリを実行できます。
fields @timestamp, attributes.gen_ai.prompt, attributes.gen_ai.usage.total_tokens, attributes.user.id 
| filter attributes.gen_ai.usage.total_tokens > 10000
| sort attributes.gen_ai.usage.total_tokens desc 
| limit 10

図 10: CloudWatch Logs Insights 上でのクエリの実行

アプリケーションログとメトリクス

  1. アプリケーションログにアクセスするには、CloudWatch Log グループ の strands-agent-logs ロググループに移動します。
  2. 図11に示すように、サンプルアプリケーションによって生成されたログを表示するために、最新のログストリームを選択します。

    図 11: CloudWatch Logs 上でのアプリケーションのログ

  3. レイテンシ、入力・出力トークン、ToolCallCount、ErrorCount、SuccessRate、TotalCycles などのアプリケーション固有のメトリクスは、別のロググループ strands-agent-metrics で EMF ログとしてCloudWatch に送信されます。
  4. CloudWatch コンソールで、メトリクスセクションに移動すると、図12に示すように、strands-agent-metrics ロググループからのカスタムメトリクスで生成された新しい名前空間 StrandsAgentMetrics が確認できます。

    図 12: CloudWatch メトリクスコンソール上でのアプリケーションメトリクス

  5. StrandsAgentMetrics カスタムメトリクスを使用して、CloudWatch コンソールでカスタムダッシュボードとアラームを作成し、AI エージェントアプリケーションの健全性とパフォーマンスを監視することもできます。

クリーンアップ

CloudFormation スタックの削除

  1. AWS CloudFormation コンソールを開き、ナビゲーションペインでスタックを選択します。
  2. 先ほど作成した CloudFormation スタックを選択し、削除を選択し、「スタックを削除しますか？」というポップアップに対して、再度削除を選択します。

Transaction Searchの無効化

  1. CloudWatch コンソールの設定に移動します。
  2. X-ray トレースタブを押し、トランザクション検索のビュー設定を選択します。
  3. 次に編集をクリックします。
  4. transaction search 機能を無効にするためにチェックボックスを外します。
  5. Save をクリックします。

結論

このブログ投稿では、Amazon CloudWatch を活用して AI エージェントアプリケーションを観察し、洞察を得る方法を探りました。OpenTelemetry 標準仕様に基づいて構築された Strands Agents SDK を使用して、メトリクス、トレース、ログからなる価値のあるテレメトリデータを生成するために、アプリケーションを計装する方法を実演しました。

CloudWatch エージェントを設定してこのようにテレメトリデータを収集することで、CloudWatch コンソール内で AI エージェントアプリケーションのパフォーマンス、使用量、実行詳細を取り込み、分析する方法を示しました。これにより、アプリケーションの健全性と信頼性を監視し、発生する問題をトラブルシューティングし、AI 駆動ワークフローのパフォーマンスを最適化できます。

重要なポイントは、使用する特定のエージェンティック AI フレームワークは異なる場合がありますが、オブザーバビリティの原則は同じであるということです。アプリケーションが OpenTelemetry などのオープンな標準仕様でテレメトリデータを生成する限り、CloudWatch を活用して可視性を得ることができます。アプリケーションが EC2、Lambda、ECS、EKS、またはその他の環境で実行されているかどうかに関係なく、エージェンティック AI ワークロードから関連するオブザーバビリティデータを収集するように CloudWatch エージェントを設定するだけです。