Gemini Enterprise Agent Platform 的代理觀測功能,可讓您全面掌握已部署代理和 Model Context Protocol (MCP) 伺服器的效能、行為和健康狀態。您可以監控重要指標、追蹤執行路徑,並觀察整個多代理系統,藉此診斷問題、最佳化資源消耗,以及提升代理的可靠性。
本文概述 Gemini Enterprise Agent Platform 提供的觀測工具,包括系統層級拓撲、個別代理監控,以及 MCP 伺服器指標。
遙測設定
如要填入這些觀測能力資訊主頁、拓撲和追蹤記錄,請務必設定代理,將 OpenTelemetry 格式的遙測資料傳送至 Google Cloud Observability 的儲存系統。
請確認代理和 MCP 伺服器環境已正確設定,可發出這類資料。內建的 Google Cloud 元件會自動以 OpenTelemetry 格式發出遙測資料。舉例來說,Model Armor 會原生發出標準化遙測資料,讓您直接在追蹤記錄資料中,順暢地公開及監控即時政策攔截,不需任何自訂檢測。
如需代理程式遙測設定操作說明和需求條件,請參閱下列資源:
- 如要檢測使用 ADK 建構的代理,請參閱「使用 OpenTelemetry 檢測 ADK 應用程式」。
- 如要檢測 Gemini Enterprise Agent Platform 上非 ADK 建構的代理,請參閱「AI 代理開發人員適用的觀測能力」。
- 如需 MCP 伺服器遙測資料,請參閱「使用 Cloud Trace 監控 MCP 工具使用情形」。
- 如要瞭解 Model Armor 遙測,請參閱「設定 Model Armor 記錄」。
觀測能力信號
Gemini Enterprise Agent Platform 透過指標、追蹤記錄和記錄檔提供觀測能力。
從 Registry 選取特定代理時,「觀測能力」分頁會提供一系列專屬資訊主頁,用於監控作業健康狀態、效能和基礎架構使用率。使用「Observability」(觀測能力) 分頁中的左側導覽列,切換下列檢視畫面:
- 總覽:追蹤所選時間範圍內的整體用量,包括工作階段總數、每個工作階段的平均對話輪數,以及代理叫用總數。時間序列圖表會顯示詞元用量 (輸入與輸出)、整體代理流量、延遲時間百分位數 (p50、p95、p99) 和錯誤率。
- 評估:顯示線上監控工具,持續評估品質。包括追蹤平均回覆品質、安全性指標、幻覺率和工具使用品質的時間序列小工具。
- 模型:依基礎模型細分成效。您可以監控 P95 延遲時間、總呼叫次數、錯誤率、配額失敗次數,以及特定模型獨立的權杖用量。
- 工具:監控連結至代理的外部工具和服務。這個檢視畫面會詳細列出每項工具的 P95 延遲時間、呼叫次數和錯誤率,以及未呼叫任何工具的互動頻率。
- 用量:提供代理執行階段環境的基礎架構層級指標,包括容器 CPU 分配、容器記憶體分配和權杖用量。
- 記錄:顯示可篩選的原始代理記錄串流,包括嚴重性、時間戳記和執行摘要,方便深入排解問題。詳情請參閱「查看代理記錄」。
除了「觀測能力」分頁中的資訊主頁,您也可以使用代理的「追蹤記錄」分頁,逐步檢查特定工作階段的執行情況,包括時距和輸入/輸出的有向無環圖。詳情請參閱「查看代理追蹤記錄」。您也可以使用「Topology」(拓撲) 分頁,查看該代理程式的特定傳入和傳出依附元件。
如果是 MCP 伺服器,您可以監控要求數量和 p95 要求時間長度,追蹤使用率和回應速度。
稽核代理動作
為支援企業安全性和法規遵循稽核,Gemini Enterprise Agent Platform 會使用雙重歸因記錄,在 Cloud Logging 中記錄代理活動。當代理代表使用者執行動作或呼叫工具 (使用者委派授權) 時,稽核和執行記錄會同時記錄以 SPIFFE 為基礎的代理身分 (稽核記錄中的 principal://...,或執行記錄中的 spiffe://...),以及發起動作的人類使用者身分。當代理依據自身權限自主執行動作時,記錄會直接將動作歸因於專屬代理身分。
稽核人員和安全管理員可以在 Cloud Logging 中,透過篩選記錄查詢中的 is_agentic=true 旗標,隔離並審查代理啟動的事件。將 is_agentic=true 與代理身分或使用者主體結合,即可追蹤端對端執行路徑,並驗證所有代理互動的政策執行情況。
緊急停止和政策傳播預期
應對資安事件或異常代理行為時,Agent Platform 提供兩個互補層級,可停止代理活動:
- 立即終止執行階段或重新轉送流量:刪除部署在 Agent Runtime (
runtimes.delete或reasoningEngines.delete) 的代理,會立即終止其容器執行個體、停止進行中的工作階段和串流叫用,並在刪除作業完成後,永久撤銷其 SPIFFE 代理身分。或者,您可以使用trafficSplitManual將 100% 的根流量重新導向至已知良好的修訂版本,或更新spec.deployment_spec.agent_gateway_config來封存現有修訂版本。 - 依政策撤銷存取權:在 Agent Gateway (
iamEnforcementMode: "ENFORCE") 強制執行的統一存取政策 (UAP) 中新增DENY規則,或套用 Identity and Access Management (IAM) 拒絕政策或撤銷角色,即可封鎖傳出工具和 API 呼叫,同時保留執行階段容器,以便進行鑑識分析。不過,UAP 和 IAM 政策更新最終會保持一致:直接變更政策通常會在 2 分鐘內生效,但最多可能需要 7 分鐘以上才會在全球生效 (請參閱「存取權變更生效時間」),而principalSet或群組成員更新可能需要幾分鐘到幾小時才能同步。政策更新會評估新的授權檢查,不會強制關閉已建立的串流連線,除非重新授權。
如要在事件發生期間立即啟用緊急切換功能,除了套用政策拒絕規則外,請刪除代理程式執行階段,或重新轉送其修訂版本流量。如需逐步說明,請參閱「緊急停止和撤銷存取權」。
遙測和安全性發現項目延遲時間
不同的觀測能力和安全性控制項,會依不同的擷取和評估排程運作。瞭解這些延遲時間預期,有助於事件應變人員區分內嵌強制執行和非同步威脅偵測。
下表摘要說明 Agent Platform 中各項遙測和安全信號的評估模型和預期延遲時間:
| 信號或控制項 | 評估和擷取模型 | 一般延遲時間 |
|---|---|---|
Cloud 稽核記錄和 Agent Gateway 要求記錄 (cloudaudit.googleapis.com/*、networkservices.googleapis.com/gateway_requests) |
系統評估 API 呼叫和閘道授權檢查時,會同步產生這類記錄,並擷取至 Logging。 | 近乎即時 (通常幾秒內即可在記錄檔探索工具中搜尋)。--freshness=6h 等範圍較小的 CLI 新鮮度篩選器有時可能會遺漏最近建立索引的項目,因此驗證近期事件時,請使用 --freshness=1d。 |
Agent Runtime 執行記錄 (aiplatform.googleapis.com/reasoning_engine_stdout、reasoning_engine_stderr) |
從執行階段容器非同步串流至 Logging。 | 通常會在發出後幾秒內顯示。 |
| Cloud Trace 中的分散式追蹤記錄 | OpenTelemetry 範圍完成後,系統會根據設定的 samplingRate 和 parentBasedSampling 規則,以非同步方式匯出。 |
通常在 span 完成後幾秒內即可搜尋。 |
| Cloud Monitoring 指標 | 定期從 Agent Runtime、Agent Gateway 和異常偵測管道取樣。 | 每 60 到 120 秒取樣一次,在 Metrics Explorer 和資訊主頁中,資料顯示延遲時間最多為 180 到 420 秒。 |
| 內嵌政策強制執行 (Agent Gateway、Identity-Aware Proxy、Model Armor) | 在工具呼叫、MCP 要求或模型提示完成前,在即時要求路徑上同步評估。 | 即時 In-line 攔截 (零後續處理延遲)。 |
代理程式異常偵測和 Security Command Center 發現項目 (AGENT_SESSION_ANOMALY) |
在工作階段記錄和追蹤記錄擷取後,透過多層偵測管道進行非同步頻外評估,不會增加即時代理回覆的延遲時間。 | 初次啟用範圍約需 40 分鐘。系統每 120 秒會對異常指標取樣一次 (最多延遲 420 秒才會顯示),且須經過額外的同步處理延遲時間,確認的發現項目才會顯示在 Security Command Center。 |
稽核記錄的防竄改保留功能
Cloud 稽核記錄項目經過特別設計,無法變更:Logging 寫入稽核記錄項目後,其酬載和中繼資料就無法修改。管理員活動和系統事件稽核記錄會儲存在 _Required 記錄檔 bucket 中,該 bucket 會強制執行固定的 400 天保留期限,且無法修改或刪除。
根據預設,資料存取稽核記錄 (cloudaudit.googleapis.com/data_access)、政策遭拒記錄 (cloudaudit.googleapis.com/policy_denied)、Agent Gateway 要求記錄 (networkservices.googleapis.com/gateway_requests) 和雙重歸因代理程式執行記錄 (is_agentic=true) 會轉送至 _Default 記錄檔 bucket,保留期限為 30 天。
如要強制執行防竄改、一次寫入、多次讀取 (WORM) 保留機制,以提供法規遵循證據,請將代理稽核和閘道記錄檔轉送至自訂 Logging bucket、設定自訂保留期限 (1 到 3,650 天),並永久鎖定 bucket。鎖定 Logging bucket 是不可逆的操作,可防止任何人 (包括專案擁有者和組織管理員) 刪除 bucket、在保留期限到期前刪除記錄項目,或縮短保留期限。
如要使用 Google Cloud CLI 建立及鎖定代理稽核記錄的自訂 Logging bucket,請執行下列指令:
gcloud logging buckets create BUCKET_ID \
--location=LOCATION \
--retention-days=RETENTION_DAYS \
--project=PROJECT_ID
gcloud logging buckets update BUCKET_ID \
--location=LOCATION \
--locked \
--project=PROJECT_ID
更改下列內容:
BUCKET_ID:稽核記錄 bucket 的專屬 ID (例如agent-audit-worm-bucket)。LOCATION:bucket 位置 (例如global、us或eu)。RETENTION_DAYS:記錄項目保留天數 (介於1到3650之間)。PROJECT_ID: Google Cloud 專案 ID。
如要防止鎖定的記錄檔 bucket 在上層專案刪除時一併移除,請在專案上設定專案留置權。或者,您也可以將稽核記錄匯出至已設定鎖定資料保留政策 (Bucket Lock) 的 Cloud Storage bucket。詳情請參閱「設定及管理記錄檔 bucket」。
將稽核記錄匯出至 SIEM
如要集中監控安全性、關聯性和長期法規遵循封存,您可以持續將代理稽核記錄、Agent Gateway 授權決策和 is_agentic=true 執行記錄匯出至 Google Security Operations (Google SecOps) 或第三方安全資訊與事件管理 (SIEM) 系統。
您可以設定專案層級的 Logging 接收器,或組織層級或資料夾層級的匯總接收器,將記錄檔轉送至下列目的地:
- Google Security Operations:將 Cloud 稽核記錄、Agent Gateway 記錄和 Security Command Center 的
AGENT_SESSION_ANOMALY發現項目,原生或透過 Pub/Sub 或 Cloud Storage 動態饋給擷取至 Google SecOps,以便調查代理工作階段和企業安全遙測資料。如需設定操作說明,請參閱「將 Google Cloud 資料匯出至 Google SecOps」。 - Pub/Sub (Pub/Sub):將代理稽核記錄即時串流至 Pub/Sub 主題,以便第三方 SIEM 平台 (例如 Splunk、Datadog 或 QRadar) 使用 Pub/Sub 訂閱項目或 Dataflow 連接器擷取。詳情請參閱「將記錄檔轉送至 Pub/Sub」。
- BigQuery (BigQuery) 或 Observability Analytics:將記錄匯出至 BigQuery 資料集,或將已啟用 Observability Analytics 的記錄檔 bucket 連結至 BigQuery,以便針對代理身分、使用者委派和閘道政策拒絕執行 SQL 法規遵循查詢。
- Cloud Storage:將批次 JSON 記錄檔匯出至已啟用值區鎖定功能的 Cloud Storage 值區,以便長期封存且不可變更。
如要建立 Logging 記錄檔接收器,將代理程式稽核和閘道記錄檔串流至 Pub/Sub 主題,以便 SIEM 擷取,請完成下列步驟:
建立記錄檔接收器,並設定「包含」篩選器,擷取 Cloud 稽核記錄、Agent Gateway 要求記錄、Agent Runtime 記錄和雙重歸因項目 (
is_agentic=true):gcloud logging sinks create SINK_NAME \ pubsub.googleapis.com/projects/DESTINATION_PROJECT_ID/topics/TOPIC_ID \ --log-filter='logName:("cloudaudit.googleapis.com" OR "networkservices.googleapis.com%2Fgateway_requests" OR "aiplatform.googleapis.com%2Freasoning_engine") OR jsonPayload.is_agentic=true OR labels.is_agentic="true"' \ --project=PROJECT_ID更改下列內容:
SINK_NAME:記錄檔接收器的名稱 (例如agent-audit-siem-sink)。DESTINATION_PROJECT_ID:託管目的地 Pub/Sub 主題的專案 ID。TOPIC_ID:SIEM 訂閱的 Pub/Sub 主題 ID。PROJECT_ID:要匯出記錄檔的專案 ID。如要匯出整個組織,請將--project=PROJECT_ID替換為--organization=ORGANIZATION_ID --include-children。
擷取接收器的寫入者服務帳戶身分,並授予目的地主題的 Pub/Sub 發布者角色 (
roles/pubsub.publisher):WRITER_IDENTITY=$(gcloud logging sinks describe SINK_NAME \ --project=PROJECT_ID \ --format='value(writerIdentity)') gcloud pubsub topics add-iam-policy-binding TOPIC_ID \ --project=DESTINATION_PROJECT_ID \ --member="${WRITER_IDENTITY}" \ --role="roles/pubsub.publisher"
OpenTelemetry 生成式 AI 慣例
代理追蹤記錄和提示與回覆記錄,主要仰賴生成式 AI 系統的 OpenTelemetry 語意慣例,以標準化方式擷取、結構化及回報生成式 AI 遙測資料。
遵循這些慣例對代理追蹤至關重要,因為這能建立通用、不限供應商的格式,用於描述複雜的多步驟代理工作流程,例如工具執行、檢索步驟和權杖消耗。這項標準化作業有助於在 Google Cloud內外的不同觀測能力後端和數據分析工具之間,實現流暢的互通性。