本頁面由 Cloud Translation API 翻譯而成。

記錄代理程式

如要在代理部署至 Vertex AI Agent Engine 執行階段時，使用代理中的 Cloud Logging，請採用下列其中一種方法：

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

為代理程式寫入記錄

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

嚴重程度：例如 info、warn、error
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"
}

查看代理程式的記錄

您可以使用記錄檔探索工具查看記錄項目：

如要取得在記錄檔探索工具中查看記錄的權限，請要求管理員授予您專案的記錄檢視者角色 (roles/logging.viewer)。
前往 Google Cloud 控制台的「Logs Explorer」：

前往 Logs Explorer
在頁面頂端選取�專案 (對應至 PROJECT_ID)。 Google Cloud
在「資源類型」中，選取「Vertex AI Agent Builder Reasoning Engine」。

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

執行階段查詢

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

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

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

建構查詢

您可以使用記錄檔探索工具逐步建構查詢。查詢通常是根據下列考量事項建構：

時間軸：根據時間搜尋相關記錄項目
範圍：根據標準屬性搜尋相關記錄項目
- 資源：將其與專案中的其他資源類型分開。
  - ：在記錄檢視器中顯示為「Vertex AI Agent Builder Reasoning Engine」，且 "aiplatform.googleapis.com/ReasoningEngine" 位於記錄項目中。"aiplatform.googleapis.com/ReasoningEngine"type
  - 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。
標籤：鍵/值組合對應項，提供記錄項目的其他資訊。標籤可以是使用者定義或系統定義，有助於分類記錄檔，方便您在記錄檔探索工具中搜尋。
payload：記錄項目的內容。

以下範例查詢會從已部署的代理程式中，擷取所有 INFO 記錄檔 (含 RESOURCE_ID)：

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

您可以在記錄檔探索工具中查看，網址為

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

查詢已適當進行網址編碼，其他參數如下：

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

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

查詢代理程式的記錄

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

結構化查詢語言 (SQL)。記錄檔分析可讓您查詢記錄檔檢視或分析檢視。
- 記錄檢視畫面具有固定結構定義，對應於記錄項目。
- 分析檢視畫面的結構定義是以 SQL 查詢結果為基礎。
Python。透過程式設計語言 (本例為 Python) 的用戶端程式庫呼叫 Cloud Logging API。

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`

記錄代理程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

為代理程式寫入記錄

stdout 或 stderr

Python Logging

Cloud Logging 用戶端

stdout 或 stderr

Python Logging

Cloud Logging 用戶端

查看代理程式的記錄

執行階段查詢

建構查詢

查詢代理程式的記錄

Python

SQL

記錄代理程式