本頁說明如何使用內建指標、自訂指標和快訊，監控 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」指標類別，然後按一下指標，例如「Request count」。
視需要設定其他標籤篩選器、匯總元素，以及調整時間範圍。
根據預設，Metrics Explorer 中「要求計數」指標的圖表會根據預設時間間隔對齊資料點，並將資料點繪製為每秒要求數 (速率指標)。
代理程式的查詢指標
您也可以透過 Prometheus 查詢語言 (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 相關聯。
您可以透過 APIs Explorer、語言專屬用戶端程式庫或指令列，叫用這些 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 的時間序列資料
您可以搭配 interval、filter 和 aggregation 等參數使用 projects.timeSeries.list，查詢時間序列資料。
以下範例說明如何在特定時間範圍內，查詢特定代理程式執行個體的 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 格式。例如，"2025-03-26T11:22:33Z"代表世界標準時間 (UTC)，"2025-03-26T11:22:33-08:00"代表太平洋標準時間 (PST)。如需完整定義和更多範例，請參閱 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。
為代理程式建立自訂指標
如果內建代理程式指標無法滿足特定用途，您可以定義自訂指標。您可以透過下列方法建立自訂指標：
記錄指標
以下步驟示範如何為範例工作流程建立及使用記錄指標 (tool_calling_count)，其中多個代理程式會呼叫多項工具，而您想計算工具呼叫次數：
指定工具，在每次呼叫時寫入記錄項目。例如
"tool-\<tool-id\> invoked by agent-\<agent-id\>"。透過 Google Cloud 控制台建立新的計數器類型記錄指標：
前往 Google Cloud 控制台的「記錄指標」頁面：
在「使用者定義指標」部分，按一下「建立指標」。 系統隨即會顯示「建立記錄指標」窗格。
在「指標類型」部分，選取「計數器」
在「詳細資料」部分，輸入「記錄指標名稱」。例如，
tool_calling_count。視需要輸入「Description」(說明) 和「Units」(單位)。在「篩選器選取」部分執行下列操作：
在「選取專案或記錄檔 bucket」下拉式清單中，選取「專案記錄」。
在「Build filter」(建構篩選器) 欄位中，使用記錄查詢語言輸入記錄篩選器。 例如：
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
在「標籤」部分，按一下「新增標籤」按鈕，新增兩個標籤。
請為第一個標籤執行下列操作：
在「標籤名稱」欄位中輸入
tool。在「Field name」(欄位名稱) 欄位中輸入
textPayload。在「Regular expression」(規則運算式) 欄位中，輸入
(tool-\d+) invoked by agent-\d+。
針對第二個標籤，請執行下列操作：
在「標籤名稱」欄位中輸入
agent。在「Field name」(欄位名稱) 欄位中輸入
textPayload。在「Regular expression」(規則運算式) 欄位中，輸入
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：網址字串，例如projects/PROJECT_IDRequest 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) 和叫用代理程式的名稱。
您可以在 Metrics Explorer 中找到
token_count指標：- 前往 Google Cloud 控制台的「Metrics Explorer」頁面：
按一下「選取指標」開啟搜尋列。
在搜尋列中輸入「Generic node」，然後點選「自訂指標」。
按一下「權杖數量」。
呼叫
projects.timeSeries.create並使用下列參數，將資料點寫入新指標：name：網址字串，例如projects/PROJECT_IDRequest 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 上傳資料點後，您可以在控制台中查看新指標
token_count： Google Cloud前往 Google Cloud 控制台的「Metrics Explorer」頁面：
按一下「選取指標」開啟搜尋列。
在搜尋列中輸入「Generic node」，然後點選「自訂指標」。
按一下「權杖數量」。視需要調整時間範圍，並為
model或agent設定標籤值。
為代理建立快訊
您可以將指標與快訊搭配使用。詳情請參閱快訊總覽。
以下範例說明如何為 request_latencies 指標建立門檻快訊，以便在延遲時間於指定時間範圍內超過預先定義的值時收到通知：
前往 Google Cloud 控制台的「Alerting」(快訊) 頁面：
點選「Create Policy」(建立政策)。「建立快訊政策」頁面隨即開啟。
在「政策設定模式」中，選取「建立工具」。
在「Select a metric」(選取指標) 下拉式選單中，依序選取
Vertex AI Reasoning Engine->reasoning_engine->Request Latency。在「新增篩選器」部分，視需要設定篩選器 (例如
reasoning_engine_id、response_code)。在「Transform data」(轉換資料) 區段中，將「Rolling window」(滾動週期) 和「Rolling window function」(滾動週期函式) 切換為
5min和99th percentile等值 (監控 5 分鐘對齊期間的第 99 個百分位數要求延遲)。點選「下一步」。
在「設定快訊觸發條件」部分，執行下列操作：
在「條件類型」中選取「門檻」。
選取「Alert trigger」(快訊觸發條件)，例如「Any time series violates」(任何時間序列違反條件時)。
選取「門檻位置」，例如「高於門檻」。
輸入門檻值，例如
5000ms。點選「下一步」。
在「設定通知並完成快訊」部分，執行下列操作：
選取一或多個通知管道。詳情請參閱「管理通知管道」。
(選用) 設定通知主旨、事件自動關閉期限、應用程式標籤、政策標籤、嚴重性等級和額外文件。
在「為快訊政策命名」部分設定政策名稱，例如
latency-99p-alert。按一下「建立政策」。
如果發生事件，請參閱「以指標為基礎的快訊政策事件」，進一步瞭解如何確認及調查事件，以及將快訊設為靜音。
如要查看更多快訊範例，請參閱 JSON 格式的範例政策。
監控代理程式的指標
您可以使用 Vertex AI Agent Engine 總覽資訊主頁，監控代理程式的運作健康狀態和效能。
查看預設資訊主頁
前往 Google Cloud 控制台的「Dashboards」(資訊主頁) 頁面：
選取 Google Cloud 專案。
在「My Dashboards」(我的資訊主頁) 窗格中，新增篩選器
Name:Vertex AI Agent Engine Overview。按一下「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 查詢語言 (PromQL) 新增指標圖表，以及如何將指標製成表格，請參閱「將圖表和表格新增至自訂資訊主頁」。
如果您已設定自訂快訊，請參閱在資訊主頁上顯示快訊政策和快訊，將這類快訊新增至資訊主頁。