Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

הגדרה של רישום ביומן

רישום ביומן חיוני להבנה ולניפוי באגים של התנהגות הסוכנים. כשפורסים סוכן ב-Agent Runtime, אפשר להשתמש ב-Cloud Logging כדי לעקוב אחרי הפעילות, לעקוב אחרי ההפעלה ולשפר את הביצועים. במסמך הזה מוסבר על השיטות לכתיבה ולצפייה ביומנים של הסוכנים.

כדי לעבוד עם Cloud Logging בסוכנים כשהם נפרסים ב-Agent Runtime, משתמשים באחת מהשיטות הבאות:

‫stdout או stderr: כברירת מחדל (ללא הגדרה נוספת), יומנים שנכתבים ל-stdout ול-stderr ינותבו למזהי היומן 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"
}

צפייה ביומנים של סוכן

אפשר לראות את הרשומות ביומן באמצעות Logs Explorer:

כדי לקבל הרשאה לצפייה ביומנים ב-Logs Explorer, צריך לבקש מהאדמין להקצות לכם את התפקיד Logs Viewer (roles/logging.viewer) בפרויקט.
נכנסים אל Logs Explorer במסוף Google Cloud :

כניסה לדף Logs Explorer
בוחרים את Google Cloud הפרויקט (שמתאים ל-PROJECT_ID) בחלק העליון של הדף.
בשדה Resource Type, בוחרים באפשרות Gemini Enterprise Agent Platform Reasoning Engine.

בסוכנים שמבוססים על ערכת פיתוח סוכנים, אפשר גם לראות את היומנים של הסוכן ב Google Cloud מסוף באמצעות מרכז הבקרה של זמן הריצה של הסוכן.

שאילתות בזמן ריצה

אפשר לסנן יומנים ב-Cloud Logging לפי כל פעולה נתמכת של סוכן שנפרס. כדי לעשות זאת, מסננים את היומנים לפי נקודת הקצה הבסיסית של REST לכל שאילתת פעולה:

‫POST /api/reasoning_engine: לשאילתות שמופנות לשיטות סינכרוניות ואסינכרוניות.
‫POST /api/stream_reasoning_engine: לשימוש בשיטות streaming ו-async streaming.
POST /api/bidi_reasoning_engine: לשאילתות שמופנות לשיטות של סטרימינג דו-כיווני.

שאילתות בזמן ריצה מנותבות לנקודות הקצה של REST בהתאם לשדה api_mode ברשימת הפעולות הנתמכות של סוכן שנפרס.

יצירת שאילתות

אפשר להשתמש ב-Logs Explorer כדי ליצור שאילתות באופן מצטבר. בדרך כלל, השאילתות מבוססות על השיקולים הבאים:

ציר זמן: כדי לחפש רשומות רלוונטיות ביומן לפי זמן
‫scope: כדי לחפש רשומות רלוונטיות ביומן על סמך מאפיינים קנוניים
- משאב: להפריד אותו מסוגים אחרים של משאבים בפרויקט.
  - ‫type: מופיע כ-Gemini Enterprise Agent Platform Reasoning Engine ב-Logs Explorer וכ-"aiplatform.googleapis.com/ReasoningEngine" ברשומה ביומן.
  - ‫labels: למיקום (LOCATION), לפרויקט PROJECT_ID ולמשאב RESOURCE_ID.
- ‫logName: היומן שאליו שייכת הרשומה ביומן:
  - לרשומות ביומן בזמן הבנייה יש מזהה יומן reasoning_engine_build.
  - רשומות היומן של stdout ו-stderr כוללות את מזהה היומן reasoning_engine_stdout ו-reasoning_engine_stderr בהתאמה.
  - לרשומות ביומן מ-python logging או מלקוח Cloud Logging יהיו מזהי יומן מותאמים אישית על סמך הקוד שלכם ב-Write logs for an agent.
- ‫trace ו-span: ליומנים כשעוקבים אחרי שאילתות.
- ‫severity: רמת החומרה של רשומת היומן.
- ‫insertId: המזהה הייחודי של רשומה ביומן.
‫labels: מפה של צמדי מפתח/ערך שמספקת מידע נוסף על רשומת היומן. התוויות יכולות להיות מוגדרות על ידי המשתמש או על ידי המערכת, והן שימושיות לסיווג של יומנים ומקלות על החיפוש שלהם ב-Logs Explorer.
‫payload: התוכן של רשומת היומן.

הדוגמה הבאה היא של שאילתה לכל היומנים של INFO מסוכן שפריסתו הושלמה עם RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

אפשר לראות אותו ב-Logs Explorer בכתובת

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

כאשר השאילתה קודדה כראוי בכתובת ה-URL, והפרמטרים האחרים הם:

‫DURATION: לדוגמה, PT30M ל-30 הדקות האחרונות (או PT10M ל-10 הדקות האחרונות), וגם
‫PROJECT_ID: הפרויקט ב- Google Cloud .

פרטים נוספים מופיעים במאמר יצירה ושמירה של שאילתות באמצעות שפת השאילתות של Logging.

שליחת שאילתות על היומנים של סוכן

יש שתי אפשרויות נפוצות לגישה תוכנתית ליומני שאילתות:

‫Structured Query Language (SQL). ב-Log Analytics אפשר להריץ שאילתות על תצוגות של יומנים או על תצוגות של נתונים סטטיסטיים.
- תצוגות יומן כוללות סכימה קבועה שמתאימה לרשומות ביומן.
- לתצוגות מפורטות ב-Analytics יש סכימה שמבוססת על התוצאות של שאילתת SQL.
‫Python. מפעילים את Cloud Logging API באמצעות ספריית הלקוח של שפת התכנות (Python במקרה הזה).

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

הגדרה של רישום ביומן