設定記錄功能

記錄檔對於瞭解及偵錯代理程式的行為至關重要。 將代理部署至 Agent Runtime 時，您可以使用 Cloud Logging 追蹤活動、監控執行作業，以及提升效能。本文說明如何為代理程式撰寫及查看記錄。

如要在代理程式部署至 Agent Runtime 時使用 Cloud Logging，請採取下列任一做法：

  • stdout 或 stderr：根據預設 (不需額外設定)，寫入 stdout 和 stderr 的記錄會分別傳送至記錄 ID reasoning_engine_stdout 和 reasoning_engine_stderr。限制是必須為文字。
  • Python 記錄：內建的 Python 記錄器可與 Cloud Logging 整合。相較於寫入 stdout 或 stderr，這項功能支援結構化記錄，且設定簡單。
  • Cloud Logging 用戶端：使用者可以寫入結構化記錄，並完全控管記錄器 (例如設定 logName 和資源類型)。

為代理程式寫入記錄

為代理程式編寫記錄時，請判斷下列事項：

  • 嚴重程度：例如資訊、警告、錯誤
  • payload：記錄內容 (例如文字或 JSON)
  • 其他欄位：用於記錄之間的相互關聯 (例如追蹤記錄/時距、標記、標籤)

舉例來說，如要在開發代理程式時記錄每個查詢的輸入內容：

stdout 或 stderr 

from typing import Dict

class MyAgent:

    def set_up(self):
        # No set up required. The logs from stdout and stderr are routed to
        # `reasoning_engine_stdout` and `reasoning_engine_stderr` respectively.
        pass

    def query(self, input: Dict):
        import sys

        print(
            f"input: {input}",
            file=sys.stdout,  # or sys.stderr
        )

Python Logging 

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logging_client.setup_logging(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID", ""),
                },
            ),
        )

    def query(self, input: Dict):
        import logging
        import json

        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        logging.info( # or .warning(), .error()
            json.dumps(input),
            extra=logging_extras,
        )

Cloud Logging 用戶端

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logger = self.logging_client.logger(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID", ""),
                },
            ),
        )

    def query(self, input: Dict):
        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        self.logger.log_struct(
            input,
            severity="INFO",  # or "DEBUG", "WARNING", "ERROR", "CRITICAL"
            **logging_extras,
        )

代理程式部署並查詢時，會產生記錄項目。舉例來說，以下程式碼：

remote_agent = agent_engines.create(
    MyAgent(),
    requirements=["cloudpickle==3", "google-cloud-logging"],
)

remote_agent.query(input={"hello": "world"})

產生類似下列內容的記錄項目：

stdout 或 stderr 

{
  "insertId": "67a3bb3b000cc2df444361ab",
  "textPayload": "input: {'hello': 'world'}",
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID"
    }
  },
  "timestamp": "2025-02-05T19:25:47.836319Z",
  "logName": "projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout",  # or `*_stderr`
  "receiveTimestamp": "2025-02-05T19:25:47.842550772Z"
}

Python Logging 

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-02-05T20:30:19.348067Z",
  "severity": "INFO",
  "labels": {
    "foo": "bar",
    "python_logger": "root",
  },
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

Cloud Logging 用戶端

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-01-30T21:38:50.776813191Z",
  "severity": "INFO",
  "labels": {"foo": "bar"},
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

查看代理程式記錄

您可以使用 Logs Explorer 查看記錄項目：

  1. 如要取得在 Logs Explorer 中查看記錄的權限，請要求管理員授予您專案的「記錄檢視者」角色 (roles/logging.viewer)。

  2. 前往 Cloud de Confiance 控制台的「Logs Explorer」：

    前往 Logs Explorer

  3. 在頁面頂端選取�專案 (對應至 PROJECT_ID)。 Cloud de Confiance by S3NS

  4. 在「資源類型」中，選取「Gemini Enterprise Agent Platform Reasoning Engine」。

如果是以 Agent Development Kit 為基礎的代理，您也可以使用 Agent Runtime 資訊主頁，在 Cloud de Confiance 控制台中查看代理的記錄。

執行階段查詢

您可以在 Cloud Logging 中，依已部署代理程式的各項支援作業篩選記錄。 如要這麼做，請根據各項作業查詢的基礎 REST 端點篩選記錄：

  • POST /api/reasoning_engine：針對同步和非同步方法提出的查詢。
  • POST /api/stream_reasoning_engine：適用於對串流和非同步串流方法提出的查詢。
  • POST /api/bidi_reasoning_engine：用於向雙向串流方法發出的查詢。

執行階段查詢會根據已部署代理程式支援作業清單中的 api_mode 欄位，轉送至 REST 端點。

建構查詢

您可以使用 Logs Explorer 逐步建構查詢。查詢通常是根據下列考量事項建構而成：

  • 時間軸：根據時間搜尋相關記錄項目
  • 範圍：根據標準屬性搜尋相關記錄項目
    • 資源：將其與專案中的其他類型資源分開。
      • type：在 Logs Explorer 中顯示為「Gemini Enterprise Agent Platform Reasoning Engine」，在記錄項目中顯示為 "aiplatform.googleapis.com/ReasoningEngine"。
      • labels：位置 (LOCATION)、專案 PROJECT_ID 和資源 RESOURCE_ID。
    • logName：記錄項目所屬的記錄：
      • 建構時間的記錄項目具有記錄 ID reasoning_engine_build。
      • stdout 和 stderr 的記錄項目分別具有記錄 ID reasoning_engine_stdout 和 reasoning_engine_stderr。
      • 根據「為代理程式寫入記錄」中的程式碼，Python 記錄或 Cloud Logging 用戶端的記錄項目會包含自訂記錄 ID。
    • 追蹤記錄和時距：用於追蹤查詢時的記錄。
    • severity：記錄項目的嚴重性。
    • insertId：記錄項目的專屬 ID。
  • labels：鍵/值組合的對應，提供記錄項目相關的其他資訊。標籤可以是使用者定義或系統定義，有助於分類記錄，方便您在 Logs Explorer 中搜尋。
  • payload：記錄項目的內容。

以下範例查詢會從已部署的代理程式擷取所有 INFO 記錄，並使用 RESOURCE_ID：

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

您可以在 Logs Explorer 中查看，網址為

https://https://console.cloud.s3nscloud.fr/logs/query;query=severity%3DINFO%0Aresource.labels.reasoning_engine_id%3D%22RESOURCE_ID%22;duration=DURATION?project=PROJECT_ID

其中查詢已適當經過網址編碼，其他參數如下：

  • DURATION：例如過去 30 分鐘的 PT30M (或過去 10 分鐘的 PT10M)，以及
  • PROJECT_ID： Cloud de Confiance by S3NS 專案。

詳情請參閱「使用 Logging 查詢語言建構及儲存查詢」。

查詢代理程式的記錄

如要以程式輔助方式查詢記錄，有兩種常見做法：

Python

from google.cloud import logging

logging_client = logging.Client(project="PROJECT_ID")
logger = logging_client.logger("LOG_ID")  # E.g. "logging_client"
print("Listing entries for logger {}:".format(logger.name))
for entry in logger.list_entries(
    filter_="resource.labels.reasoning_engine_id=RESOURCE_ID"  # Optional
):
    timestamp = entry.timestamp.isoformat()
    print("* {}: {}".format(timestamp, entry.payload))

每個 entry 都會對應至 LogEntry。 如要瞭解 logger.list_entries 的輸入引數，請參閱 API 參考資料。

SQL

記錄檢視畫面：

SELECT *
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

Analytics 資料檢視：

SELECT *
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`