このページでは、組み込み指標、カスタム指標、アラートを使用して Vertex AI Agent Engine でエージェントをモニタリングする方法について説明します。
概要
Cloud Monitoring を使用すると、追加の設定や構成なしで Vertex AI Agent Engine を使用できます。組み込みのエージェント指標は自動的に収集され、Google Cloud コンソールの Cloud Monitoring ページに表示されます。
サポートされている組み込み指標
次のエージェント指標がサポートされており、Vertex AI Agent Engine のモニタリング対象リソース aiplatform.googleapis.com/ReasoningEngine に関連付けられています。
- リクエスト数
- リクエストのレイテンシ
- コンテナの CPU 割り当て時間
- コンテナのメモリ割り当て時間
指標タイプ、単位、ラベル、レイテンシ、サンプリング期間の詳細については、AI Platform 指標の完全なリストをご覧ください。
エージェントの指標を表示する
エージェントの組み込み指標は、 Google Cloud コンソールで Metrics Explorer を使用して表示できます。
指標エクスプローラで指標を表示する権限を取得するには、プロジェクトに対するモニタリング閲覧者ロール（
roles/monitoring.viewer）を付与するよう管理者に依頼してください。Google Cloud コンソールの Metrics Explorer に移動します。
Google Cloud プロジェクトを選択します。
[指標を選択] をクリックして検索バーを開きます。
検索バーに「Vertex AI Reasoning Engine」と入力し、[Vertex AI Reasoning Engine] をクリックします。
[Reasoning_engine] 指標カテゴリをクリックし、[リクエスト数] などの指標をクリックします。
必要に応じて、追加のラベルフィルタと集計要素を設定し、時間範囲を調整します。
デフォルトでは、リクエスト数指標の Metrics Explorer のグラフは、データポイントをデフォルトの時間間隔で調整し、データポイントをリクエスト/秒（レート指標）としてプロットします。
エージェントの指標をクエリする
Prometheus Query Language（PromQL）または Cloud Monitoring v3 API を使用して指標をクエリすることもできます。PromQL は、指標のフィルタリング、集計、変換のためのオプションを多数提供します。一方、Cloud Monitoring API を使用すると、すべての未加工データポイントをプログラムで一覧表示してクエリできます。
PromQL を使用して指標をクエリする
PromQL を使用すると、カスタム時間間隔でデータポイントを調整して集計し、変換されたデータポイントを絶対リクエスト数（リクエスト / 秒ではなく）としてプロットできます。次の例では、Agent Engine インスタンス ID（RESOURCE_ID）とレスポンス コード（RESPONSE_CODE）でデータをフィルタしています。
sum_over_time(
increase(
aiplatform_googleapis_com:reasoning_engine_request_count{
monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
reasoning_engine_id='RESOURCE_ID',
response_code='RESPONSE_CODE'
}
[10m]
)
[10m:10m]
)
特定のエラー レスポンス コード（500 など）でラベル付けされたリクエストの数と、リクエストの合計数（失敗したリクエストの割合）の比率を計算することで、エラー率をクエリできます。
sum_over_time(
sum(
rate(
aiplatform_googleapis_com:reasoning_engine_request_count{
monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
reasoning_engine_id='RESOURCE_ID',
response_code='500'
}
[10m]
)
)
[10m:10m]
)
/
sum_over_time(
sum(
rate(
aiplatform_googleapis_com:reasoning_engine_request_count{
monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
reasoning_engine_id='RESOURCE_ID',
}
[10m]
)
)
[10m:10m]
)
比率指標のベスト プラクティスと制限事項については、指標の比率についてをご覧ください。エラー率指標のアラートを設定する方法の例については、JSON のサンプル ポリシーをご覧ください。
Cloud Monitoring API を使用して指標をクエリする
Cloud Monitoring API を使用すると、次のことができます。
Vertex AI Agent Engine のモニタリング対象リソース定義を取得する
使用可能なエージェント指標の定義を一覧表示する
request_countの時系列データをクエリする
すべてのエージェント指標は、エージェント エンジンのモニタリング対象リソース aiplatform.googleapis.com/ReasoningEngine に関連付けられます。
これらの API は、API エクスプローラ、言語固有のクライアント ライブラリ、またはコマンドラインから呼び出すことができます。API Explorer とクライアント ライブラリを使用して指標を読み取る方法については、ドキュメントをご覧ください。次の例は、コマンドラインでの使用方法（特に curl ツール）を示しています。
Agent Engine のモニタリング対象リソース定義を取得する
次のコマンドは、projects.monitoredResourceDescriptors を使用してモニタリング対象リソースの定義を取得します。また、フィルタリングに使用できるすべてのラベルも取得します。
gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/monitoredResourceDescriptors/aiplatform.googleapis.com/ReasoningEngine
ラベルには、resource_container、location、reasoning_engine_id を含める必要があります。
使用可能なエージェント指標の定義を一覧表示する
次のコマンドは、projects.metricDescriptors を使用して、Agent Engine のすべての指標とラベルフィルタを取得します。
gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/metricDescriptors?filter='metric.type=starts_with("aiplatform.googleapis.com/reasoning_engine")'結果には、次の指標の定義と、それらの特定のラベルが含まれます。
aiplatform.googleapis.com/reasoning_engine/request_countaiplatform.googleapis.com/reasoning_engine/request_latenciesaiplatform.googleapis.com/reasoning_engine/cpu/allocation_timeaiplatform.googleapis.com/reasoning_engine/memory/allocation_time
request_count の時系列データをクエリする
projects.timeSeries.list を interval、filter、aggregation などのパラメータとともに使用して、時系列データをクエリできます。
次の例は、特定の期間における特定のエージェント インスタンスの request_count 指標の未加工データポイントをクエリする方法を示しています。
gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/timeSeries?filter='metric.type="aiplatform.googleapis.com/reasoning_engine/request_count"%20AND%20resource.labels.reasoning_engine_id="RESOURCE_ID"&interval.endTime=2025-03-26T11:00:0.0-08:00&interval.startTime=2025-03-26T10:00:0.0-08:00'
次のように置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- RESOURCE_ID: Agent Engine インスタンス ID。これは必ずしも必要ではありません。同じプロジェクト内の複数の Agent Engine インスタンスに対してクエリを実行できます。
interval.startTimeとinterval.endTime: 時間間隔の開始（包括的）と終了（排他的）。RFC 3339 形式。たとえば、協定世界時（UTC）の場合は"2025-03-26T11:22:33Z"、太平洋標準時（PST）の場合は"2025-03-26T11:22:33-08:00"です。完全な定義とその他の例については、RFC 3339 をご覧ください。
次のようなレスポンスが返されます。
{
"timeSeries": [
{
"metric": {
"labels": {
"response_code": "200",
"response_code_class": "2xx"
},
"type": "aiplatform.googleapis.com/reasoning_engine/request_count"
},
"resource": {
"type": "aiplatform.googleapis.com/ReasoningEngine",
"labels": {
"reasoning_engine_id": "RESOURCE_ID",
"location": "LOCATION",
"project_id": "PROJECT_ID"
}
},
"metricKind": "DELTA",
"valueType": "INT64",
"points": [
{
"interval": {
"startTime": "2025-03-26T18:55:27.001Z",
"endTime": "2025-03-26T18:56:27Z"
},
"value": {
"int64Value": "25"
}
},
{
"interval": {
"startTime": "2025-03-26T18:54:27.001Z",
"endTime": "2025-03-26T18:55:27Z"
},
"value": {
"int64Value": "36"
}
}
// ... more data points ...
]
}
// ... potentially more time series with other response codes ...
],
"unit": "1"
}
レスポンスの形式について詳しくは、projects.timeSeries.list をご覧ください。
エージェントのカスタム指標を作成する
組み込みのエージェント指標が特定のユースケースに対応していない場合は、カスタム指標を定義できます。カスタム指標は、次の方法で作成できます。
ログベースの指標: 大量のログエントリの傾向とパターンをモニタリングします。
ユーザー定義指標: アプリケーション固有のデータやクライアント側のシステムデータの取得など、 Google Cloudで定義されていない指標。
ログベースの指標
次の手順では、複数のエージェントが複数のツールを呼び出すワークフローの例で、ツール呼び出しの数をカウントするログベースの指標（tool_calling_count）を作成して使用する方法を示します。
ツールが呼び出されるたびにログエントリを書き込むように指定します。例:
"tool-\<tool-id\> invoked by agent-\<agent-id\>"Google Cloud コンソールで新しいカウンタタイプのログベースの指標を作成します。
Google Cloud コンソールの [ログベースの指標] ページに移動します。
[ユーザー定義の指標] セクションで、[指標を作成] をクリックします。[ログベースの指標の作成] ペインが表示されます。
[指標タイプ] で [カウンタ] を選択します。
[詳細] セクションで、[ログベースの指標の名前] を入力します。例:
tool_calling_count。必要に応じて、[説明] と [単位] を入力します。[フィルタの選択] セクションで、次の操作を行います。
[プロジェクトまたはログバケットを選択] プルダウン リストで、[プロジェクトのログ] を選択します。
[フィルタの作成] フィールドに、ロギングクエリ言語を使用してログフィルタを入力します。次に例を示します。
resource.type="aiplatform.googleapis.com/ReasoningEngine" resource.labels.reasoning_engine_id="RESOURCE_ID" textPayload =~ "tool-\d+ invoked by agent-\d+" -- assuming both tool and agent IDs are numeric
[ラベル] セクションで、[ラベルを追加] ボタンをクリックして、2 つの新しいラベルを追加します。
最初のラベルに対して、次の操作を行います。
[ラベル名] フィールドに「
tool」と入力します。[フィールド名] フィールドに「
textPayload」と入力します。[正規表現] フィールドに「
(tool-\d+) invoked by agent-\d+」と入力します。
2 番目のラベルに対して、次の操作を行います。
[ラベル名] フィールドに「
agent」と入力します。[フィールド名] フィールドに「
textPayload」と入力します。[正規表現] フィールドに「
tool-\d+ invoked by (agent-\d+)」と入力します。
- [完了] をクリックします。
[指標を作成] をクリックします。
tool_calling_count指標と関連するログを表示するには、 Google Cloud コンソールで次の操作を行います。Google Cloud コンソールの [Metrics Explorer] ページに移動します。
[指標を選択] をクリックして検索バーを開きます。
検索バーに「Vertex AI Reasoning Engine」と入力し、[Vertex AI Reasoning Engine] をクリックします。
[ログベースの指標] 指標カテゴリをクリックし、[Logging/user/tool_calling_count] をクリックします。必要に応じて期間を調整します。
（省略可）ラベル
toolとagentでフィルタします。すべてのエージェントの特定のツールの呼び出し回数の合計を取得するには、フィルタラベル
toolにそのツール ID の値を設定します。すべてのツールについて特定のエージェントの呼び出し回数の合計を取得するには、フィルタラベル
agentにそのエージェント ID の値を設定します。
必要に応じて、[合計条件] を
toolまたはagentに設定して、さまざまなツールやエージェント別に合計数を取得します。
エージェントログの書き込み方法については、エージェントのロギングをご覧ください。ログベースの指標の詳細については、ログベースの指標の概要をご覧ください。
ユーザー定義の指標
次の手順では、複数のエージェントが複数のモデルを呼び出すワークフローの例で、ユーザー定義指標（token_count）を作成して使用する方法を示します。この例では、使用されたトークンの合計数を計算します（各呼び出しエージェントとターゲット モデルのアプリケーション起動以降のトークン数をトラッキングしていると仮定します）。
次のパラメータを指定して
projects.metricDescriptors.createを呼び出し、カスタム指標タイプを定義します。name: URL 文字列（projects/PROJECT_IDなど）Request body:MetricDescriptorオブジェクト:{ "name": "token_count", "description": "Token Consumed by models.", "displayName": "Token Count", "type": "custom.googleapis.com/token_count", "metricKind": "CUMULATIVE", "valueType": "INT64", "unit": "1", "labels": [ { "key": "model", "valueType": "STRING", "description": "Model." }, { "key": "agent", "valueType": "STRING", "description": "Agent." } ], "monitoredResourceTypes": [ "generic_node" ] }新しい指標
token_countが種類Cumulativeで作成されます。これは、アプリケーションの起動以降のトークンの合計数を表します。Cumulative指標の詳細については、指標の種類とタイプをご覧ください。ラベルmodelとagentは、ターゲットの大規模言語モデル（LLM）と呼び出しエージェントの名前を表します。
token_count指標は、Metrics Explorer で確認できます。- Google Cloud コンソールの [Metrics Explorer] ページに移動します。
[指標を選択] をクリックして検索バーを開きます。
検索バーに「Generic node」と入力し、[カスタム指標] をクリックします。
[トークン数] をクリックします。
次のパラメータを指定して
projects.timeSeries.createを呼び出し、新しい指標にデータポイントを書き込みます。name: URL 文字列（projects/PROJECT_IDなど）Request body:TimeSeriesオブジェクトのリスト:{ "timeSeries": [ { "metric": { "type": "custom.googleapis.com/token_count", "labels": { "model": "model-1", "agent": "agent-1" } }, "resource": { "type": "generic_node", "labels": { "project_id": "PROJECT_ID", "node_id": "RESOURCE_ID", "namespace": "", "location": "us-central1" } }, "points": [ { "interval": { "startTime": "2025-03-26T10:00:00-08:00", "endTime": "2025-03-26T10:01:00-08:00" }, "value": { "int64Value": 15 } } ] }, { "metric": { "type": "custom.googleapis.com/token_count", "labels": { "model": "model-1", "agent": "agent-2" } }, "resource": { "type": "generic_node", "labels": { "project_id": "PROJECT_ID", "node_id": "RESOURCE_ID", "namespace": "", "location": "us-central1" } }, "points": [ { "interval": { "startTime": "2025-03-26T10:00:00-08:00", "endTime": "2025-03-26T10:01:00-08:00" }, "value": { "int64Value": 20 } } ] } // ... more time series ... ] }
Cloud Monitoring API を介してデータポイントがアップロードされると、 Google Cloud コンソールで新しい指標
token_countを表示できます。Google Cloud コンソールの [Metrics Explorer] ページに移動します。
[指標を選択] をクリックして検索バーを開きます。
検索バーに「Generic node」と入力し、[カスタム指標] をクリックします。
[トークン数] をクリックします。必要に応じて、期間を調整し、
modelまたはagentのラベル値を構成します。
エージェントのアラートを作成する
指標はアラートと組み合わせて使用できます。詳細については、アラートの概要をご覧ください。
次の例は、request_latencies 指標のしきい値アラートを作成して、レイテンシが指定された期間に事前定義された値を超えた場合に通知を受け取る方法を示しています。
Google Cloud コンソールの [アラート] ページに移動します。
[ポリシーを作成] をクリックします。[アラート ポリシーを作成] ページが開きます。
[ポリシー構成モード] で [ビルダー] を選択します。
[指標を選択] プルダウン メニューで、
Vertex AI Reasoning Engine->reasoning_engine->Request Latencyを選択します。[フィルタを追加] セクションで、必要に応じてフィルタ（
reasoning_engine_id、response_codeなど）を構成します。[データの変換] セクションで、[ローリング ウィンドウ] と [ローリング ウィンドウ関数] を
5minや99th percentileなどの値に切り替えます（5 分間の調整期間におけるリクエスト レイテンシの 99 パーセンタイルをモニタリングします）。[次へ] をクリックします。
[アラート トリガーを構成する] セクションで、次の操作を行います。
[条件タイプ] で [しきい値] を選択します。
[アラート トリガー]（[任意の時系列の違反] など）を選択します。
[しきい値の位置]（[しきい値より上] など）を選択します。
しきい値（
5000msなど）を入力します。[次へ] をクリックします。
[通知を構成してアラートを確定する] セクションで、次の操作を行います。
1 つ以上の通知チャンネルを選択します。詳細については、通知チャンネルを管理するをご覧ください。
（省略可）通知の件名、インシデントの自動クローズ期間、アプリケーション ラベル、ポリシーラベル、重大度レベル、追加のドキュメントを構成します。
[アラート ポリシーの命名] セクションで、ポリシー名（
latency-99p-alertなど）を設定します。[ポリシーを作成] をクリックします。
インシデントが発生した場合は、指標ベースのアラート ポリシーのインシデントで、インシデントの確認と調査、アラートのミュートの詳細をご覧ください。
アラートの例については、JSON のサンプル ポリシーをご覧ください。
エージェントの指標をモニタリングする
Vertex AI Agent Engine の概要ダッシュボードを使用すると、エージェントの運用の健全性とパフォーマンスをモニタリングできます。
デフォルトのダッシュボードを表示する
Google Cloud コンソールで [ダッシュボード] ページに移動します。
Google Cloud プロジェクトを選択します。
[My Dashboards] ペインで、フィルタ
Name:Vertex AI Agent Engine Overviewを追加します。[Vertex AI Agent Engine の概要] をクリックして、デフォルトのエージェント ダッシュボードを表示します。
デフォルトのダッシュボードをカスタマイズする
デフォルトのダッシュボードには、エージェントの組み込み指標のみが含まれています。独自のカスタム指標をダッシュボードに追加するには、次の手順でデフォルトのダッシュボードをコピーしてカスタマイズします。
[ダッシュボードをコピー] をクリックします。[ダッシュボードのコピー] ダイアログで、[コピー] をクリックします。ダッシュボードのコピーが開きます。ダッシュボードのコピーは、[カスタム] カテゴリの [マイ ダッシュボード] ペインにもあります。
ダッシュボードのコピーで、次の手順に沿って指標を追加します。
[ウィジェットを追加] をクリックします。[ウィジェットを追加] サイドパネルが表示されます。
[データ] で [指標] を選択します。[ウィジェットを構成する] サイドパネルが表示されます。
[指標を選択] をクリックして検索バーを開きます。
ログベースの指標を使用してカスタム指標が作成されている場合:
検索バーに「Vertex AI Reasoning Engine」と入力し、[Vertex AI Reasoning Engine] をクリックします。
[ログベースの指標] 指標カテゴリをクリックし、[Logging/user/tool_calling_count] などの指標をクリックします。
[適用] をクリックします。
ユーザー定義の指標を使用してカスタム指標が作成されている場合:
検索バーに「Generic Node」と入力し、[Generic Node] をクリックします。
[カスタム指標] 指標カテゴリをクリックし、[トークン数] などの指標をクリックします。
[適用] をクリックします。
カスタム指標を表示する新しいグラフがダッシュボードに表示されます。
ダッシュボードのレイアウトは、次のようにさらに調整できます。
ウィジェットのタイトルを長押しして、同じダッシュボード内の別の場所にドラッグして、ウィジェットを移動します。
ウィジェットの右下隅を長押ししてサイズを調整し、ウィジェットのサイズを変更します。
Prometheus Query Language（PromQL）を使用して指標グラフを追加する方法と、指標を一覧表示する方法については、カスタム ダッシュボードにグラフとテーブルを追加するをご覧ください。
カスタム アラートを構成している場合は、ダッシュボードにアラート ポリシーとアラートを表示するを参照して、そのようなアラートをダッシュボードに追加してください。