このページでは、組み込み指標、カスタム指標、アラートを使用して 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 で確認できます。
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 Explorer、言語固有のクライアント ライブラリ、コマンドラインから呼び出すことができます。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 を設定します。
必要に応じて、[Sum By] を
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] ページに移動します。
[指標を選択] をクリックして検索バーを開きます。
検索バーに「汎用ノード」と入力し、[カスタム指標] をクリックします。
[Token Count] をクリックします。
次のパラメータを指定して
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] ページに移動します。
[指標を選択] をクリックして検索バーを開きます。
検索バーに「汎用ノード」と入力し、[カスタム指標] をクリックします。
[Token Count] をクリックします。 必要に応じて期間を調整し、
modelまたはagentのラベル値を構成します。
エージェントのアラートを作成する
指標はアラートと組み合わせて使用できます。詳細については、アラートの概要をご覧ください。
次の例は、request_latencies 指標のしきい値アラートを作成して、指定された期間にレイテンシが事前定義の値を超えた場合に通知を受け取る方法を示しています。
Google Cloud コンソールの [アラート] ページに移動します。
[ポリシーを作成] をクリックします。[アラート ポリシーを作成] ページが開きます。
[ポリシー構成モード] で [ビルダー] を選択します。
[指標を選択] プルダウン メニューで、
Vertex AI Reasoning Engine->reasoning_engine->Request Latencyの順に選択します。[フィルタを追加] セクションで、必要に応じてフィルタ（
reasoning_engine_id、response_codeなど）を構成します。[データの変換] セクションで、[ローリング ウィンドウ] と [ローリング ウィンドウ関数] を
5minや99th percentileなどの値に切り替えます（5 分間の調整期間におけるリクエスト レイテンシの 99 パーセンタイルをモニタリングします）。[次へ] をクリックします。
[Configure alert trigger] セクションで、次の操作を行います。
[Condition Types] で [しきい値] を選択します。
[任意の時系列の違反] などのアラート トリガーを選択します。
[しきい値より上] などのしきい値の位置を選択します。
しきい値（
5000msなど）を入力します。[次へ] をクリックします。
[Configure notifications and finalize alert] セクションで、次の操作を行います。
1 つ以上の通知チャンネルを選択します。詳細については、通知チャンネルを管理するをご覧ください。
（省略可）通知の件名、インシデントの自動クローズ期間、アプリケーション ラベル、ポリシーラベル、重大度レベル、追加のドキュメントを構成します。
[Name the alert policy] セクションで、ポリシー名を設定します（
latency-99p-alertなど）。[ポリシーを作成] をクリックします。
インシデントが発生した場合は、指標ベースのアラート ポリシーのインシデントで、インシデントの確認と調査、アラートのミュート方法をご確認ください。
アラートの例については、JSON のサンプル ポリシーをご覧ください。
エージェントの指標をモニタリングする
Vertex AI Agent Engine の概要ダッシュボードを使用すると、エージェントの運用の健全性とパフォーマンスをモニタリングできます。
デフォルトのダッシュボードを表示する
Google Cloud コンソールで [ダッシュボード] ページに移動します。
Google Cloud プロジェクトを選択します。
[マイ ダッシュボード] ペインで、フィルタ
Name:Vertex AI Agent Engine Overviewを追加します。[Vertex AI Agent Engine Overview] をクリックして、デフォルトのエージェント ダッシュボードを表示します。
デフォルトのダッシュボードをカスタマイズする
デフォルトのダッシュボードには、エージェントの組み込み指標のみが表示されます。独自のカスタム指標をダッシュボードに追加するには、次の手順でデフォルトのダッシュボードをコピーしてカスタマイズします。
[ダッシュボードをコピー] をクリックします。[ダッシュボードのコピー] ダイアログで、[コピー] をクリックします。ダッシュボードのコピーが開きます。ダッシュボードのコピーは、[カスタム] カテゴリの [マイ ダッシュボード] ペインでも確認できます。
ダッシュボードのコピーに、次の手順で指標を追加します。
[ウィジェットを追加] をクリックします。[ウィジェットを追加] サイドパネルが表示されます。
[データ] で [指標] を選択します。[ウィジェットを構成する] サイドパネルが表示されます。
[指標を選択] をクリックして検索バーを開きます。
ログベースの指標を使用してカスタム指標が作成されている場合:
検索バーに「Vertex AI Reasoning Engine」と入力し、[Vertex AI Reasoning Engine] をクリックします。
指標カテゴリで [ログベースの指標] をクリックし、[Logging/user/tool_calling_count] などの指標をクリックします。
[適用] をクリックします。
ユーザー定義の指標を使用してカスタム指標が作成されている場合:
検索バーに「汎用ノード」と入力し、[汎用ノード] をクリックします。
指標カテゴリで [カスタム指標] をクリックし、[Token Count] などの指標をクリックします。
[適用] をクリックします。
カスタム指標を表示する新しいグラフがダッシュボードに表示されます。
ダッシュボードのレイアウトは、次のようにさらに調整できます。
ウィジェットのタイトルを長押しして、同じダッシュボード上の別の場所にドラッグし、ウィジェットを移動します。
ウィジェットの右下隅を長押しして、サイズを調整します。
Prometheus Query Language（PromQL）を使用して指標グラフを追加する方法と、指標を一覧表示する方法については、カスタム ダッシュボードにグラフと表を追加するをご覧ください。
カスタム アラートを構成している場合は、ダッシュボードにアラート ポリシーとアラートを表示するを参照して、そのようなアラートをダッシュボードに追加します。