Agent Runtime 會自動收集及處理已部署代理程式的作業指標。您可以使用這些指標瞭解代理程式的效能和健康狀態，不必手動設定。
本文說明如何在 Agent Runtime 中監控代理程式，方法是在Google Cloud 控制台中查看內建指標、建立自訂指標，以及設定快訊。如要進行進階監控，您也可以使用 PromQL 或 Cloud Monitoring API 查詢指標。
總覽
您可以使用 Cloud Monitoring 執行 Agent Runtime，不必進行任何額外設定。系統會自動收集內建的代理程式指標，並在Google Cloud 控制台的 Cloud Monitoring 頁面中顯示。
支援的內建指標
系統支援下列代理程式指標，並與 Agent Runtime 受監控資源 aiplatform.googleapis.com/ReasoningEngine 建立關聯：
- 要求數量
- 要求的延遲時間
- 容器 CPU 分配時間
- 容器記憶體配置時間
如要進一步瞭解指標類型、單位、標籤，以及延遲和取樣週期，請參閱 AI 平台指標完整清單。
ADK 遙測指標
對於版本 >= 2.6.0 的 Agent Development Kit (ADK) 代理，GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY 會啟用其他內建指標，符合 OpenTelemetry 的生成式 AI 語意慣例。
這些指標會匯出至 Cloud Monitoring，做為「設定專案 Google Cloud 」中的使用者定義指標。這個環境變數也會啟用追蹤記錄和記錄 (請參閱「為代理程式寫入追蹤記錄」)。
查看代理程式的指標
您可以在 Google Cloud 控制台中使用 Metrics Explorer 查看代理程式內建指標：
如要取得在指標探索器中查看指標的權限，請要求管理員授予您專案的「Monitoring 檢視者」角色 (
roles/monitoring.viewer)。前往 Google Cloud 控制台的「Metrics Explorer」：
選取 Google Cloud 專案。
按一下「選取指標」開啟搜尋列。
在搜尋列中輸入「Gemini Enterprise Agent Platform Reasoning Engine」，然後點選「Gemini Enterprise Agent Platform Reasoning Engine」。
按一下「Reasoning_engine」指標類別，然後按一下指標，例如「Request count」。
視需要設定其他標籤篩選器、匯總元素，以及調整時間範圍。
根據預設，Metrics Explorer 中「要求計數」指標的圖表會根據預設時間間隔對齊資料點，並將資料點繪製為每秒要求數 (速率指標)。
如果是以 Agent Development Kit 為基礎的代理程式，您也可以使用 Agent Runtime 資訊主頁，在 Google Cloud 控制台中查看代理程式的指標。
代理程式的查詢指標
您也可以透過 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 執行下列操作：
取得 Agent Runtime 受監控資源定義
列出可用的代理程式指標定義
查詢「
request_count」的時間序列資料
所有代理程式指標都與 Agent Platform 監控資源 aiplatform.googleapis.com/ReasoningEngine 相關聯。
您可以透過 APIs Explorer、語言專屬用戶端程式庫或指令列，叫用這些 API。如要透過 API Explorer 和用戶端程式庫讀取指標，請參閱說明文件。下列範例示範如何在指令列中使用，更具體來說是 curl 工具。
取得 Agent Platform 受監控資源定義
下列指令會使用 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 Platform 的所有指標和標籤篩選器：
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 Platform 執行個體 ID。這並非必要步驟。您可以在同一專案中，查詢多個 Agent Platform 執行個體。
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。
為代理程式建立自訂指標
如果內建代理程式指標無法滿足特定用途，您可以定義自訂指標。您可以透過下列方法建立自訂指標：
記錄指標
以下步驟示範如何為範例工作流程建立及使用記錄指標 (tool_calling_count)，其中多個代理會呼叫多項工具，而您想計算工具呼叫次數：
指定工具，在每次呼叫時寫入記錄項目。例如：
"tool-\<tool-id\> invoked by agent-\<agent-id\>"。透過 Google Cloud 控制台建立新的計數器類型記錄指標：
前往 Google Cloud 控制台的「記錄指標」頁面：
在「使用者定義指標」部分，按一下「建立指標」。 「建立記錄指標」窗格隨即顯示。
在「指標類型」部分，選取「計數器」
在「詳細資料」部分，輸入「記錄指標名稱」。例如
tool_calling_count。視需要輸入「Description」(說明) 和「Units」(單位)。在「篩選器選取」部分，執行下列操作：
在「選取專案或記錄檔 bucket」下拉式清單中，選取「專案記錄」。
在「Build filter」(建構篩選器) 欄位中，使用 Logging 查詢語言輸入記錄篩選器。 例如：
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+)。
- 按一下「完成」。
點選「建立指標」。
如要在 Google Cloud 控制台中查看
tool_calling_count指標和相關聯的記錄，請按照下列步驟操作：前往 Google Cloud 控制台的「Metrics Explorer」頁面：
按一下「選取指標」開啟搜尋列。
在搜尋列中輸入「Gemini Enterprise Agent Platform Reasoning Engine」，然後點選「Gemini Enterprise Agent Platform 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" ] }系統會以
Cumulative類型建立新指標token_count，代表應用程式啟動以來的權杖總數。如要進一步瞭解Cumulative指標，請參閱「指標種類和類型」。標籤model和agent分別代表目標大型語言模型 (LLM) 和叫用代理的名稱。
您可以在 Metrics Explorer 中找到
token_count指標：- 前往 Google Cloud 控制台的「Metrics Explorer」頁面：
按一下「選取指標」開啟搜尋列。
在搜尋列中輸入「Generic node」，然後點選「Custom metrics」。
按一下「權杖數量」。
使用下列參數呼叫
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 上傳資料點後，您可以在 Google Cloud 控制台查看新指標
token_count：前往 Google Cloud 控制台的「Metrics Explorer」頁面：
按一下「選取指標」開啟搜尋列。
在搜尋列中輸入「Generic node」，然後點選「Custom metrics」。
按一下「權杖數」。視需要調整時間範圍，並為
model或agent設定標籤值。
為代理程式建立快訊
您可以將指標與快訊搭配使用。詳情請參閱「快訊總覽」。
以下範例說明如何為 request_latencies 指標建立門檻快訊，以便在延遲時間於指定時間範圍內超過預先定義的值時收到通知：
前往 Google Cloud 控制台的「Alerting」(快訊) 頁面：
點選「Create Policy」(建立政策)。「建立警告政策」頁面隨即開啟。
在「政策設定模式」中，選取「建立工具」。
在「Select a metric」(選取指標) 下拉式選單中，依序選取
Agent Platform Reasoning Engine->reasoning_engine->Request Latency。在「新增篩選器」部分中，視需要設定篩選器 (例如
reasoning_engine_id、response_code)。在「轉換資料」專區，將「滾動週期」和「滾動週期函式」切換為
5min和99th percentile等值 (監控 5 分鐘對齊期間內，要求延遲時間的第 99 個百分位數)。點選「下一步」。
在「Configure alert trigger」專區，執行下列操作：
在「條件類型」部分選取「門檻」。
選取「Alert trigger」(快訊觸發條件)，例如「Any time series violates」(任何時間序列違反條件時)。
選取「門檻位置」，例如「高於門檻」。
輸入門檻值，例如
5000ms。點選「下一步」。
在「設定通知並完成快訊」部分，執行下列操作：
選取一或多個通知管道。詳情請參閱「管理通知管道」。
(選用) 設定通知主旨、事件自動關閉期限、應用程式標籤、政策標籤、嚴重性等級和額外文件。
在「為快訊政策命名」部分設定政策名稱，例如
latency-99p-alert。點選「建立政策」。
如果發生事件，請參閱「以指標為基礎的警告政策事件」，進一步瞭解如何確認及調查事件，以及如何將警告設為靜音。
如要查看更多快訊範例，請參閱 JSON 格式的範例政策。
監控代理程式的指標
您可以使用 Agent Runtime Overview 資訊主頁，監控代理程式的運作健康狀態和效能。
查看預設資訊主頁
前往 Google Cloud 控制台的「Dashboards」(資訊主頁) 頁面：
選取 Google Cloud 專案。
在「My Dashboards」(我的資訊主頁) 窗格中，新增篩選器
Name:Agent Runtime Overview。按一下「Agent Runtime Overview」(代理程式執行階段總覽)，顯示預設代理程式資訊主頁。
自訂預設資訊主頁
預設資訊主頁只會包含代理程式內建指標。如要將自訂指標新增至資訊主頁，請按照下列步驟複製及自訂預設資訊主頁：
按一下「複製資訊主頁」。在「複製資訊主頁」對話方塊中，按一下「複製」。 資訊主頁副本隨即開啟。您也可以在「Custom」自訂類別下方的「My Dashboards」我的資訊主頁窗格中，找到資訊主頁副本。
在資訊主頁副本中，按照下列步驟新增指標：
點選「新增小工具」。「新增小工具」側邊面板隨即顯示。
在「資料」中，選取「指標」。系統隨即會顯示「設定小工具」側邊面板。
按一下「選取指標」開啟搜尋列。
如果自訂指標是使用記錄指標建立：
在搜尋列中輸入「Gemini Enterprise Agent Platform Reasoning Engine」，然後按一下「Gemini Enterprise Agent Platform Reasoning Engine」。
按一下「記錄指標」指標類別，然後點選指標，例如「Logging/user/tool_calling_count」。
按一下「套用」。
如果自訂指標是使用使用者定義指標建立：
在搜尋列中輸入「Generic Node」，然後按一下「Generic Node」。
按一下「自訂指標」指標類別，然後按一下指標，例如「權杖數量」。
按一下「套用」。
資訊主頁會顯示新的圖表，其中包含自訂指標。
您可以進一步調整資訊主頁的版面配置，例如：
按住小工具標題，然後拖曳到同一資訊主頁的其他位置，即可移動小工具。
按住小工具右下角並調整大小，即可變更小工具大小。
如要進一步瞭解如何使用 Prometheus 查詢語言 (PromQL) 新增指標圖表，以及如何將指標製成表格，請參閱「在自訂資訊主頁中新增圖表和表格」。
如果您已設定自訂快訊，請參閱「在資訊主頁上顯示快訊政策和快訊」，將這類快訊新增至資訊主頁。