פתרון בעיות בהגדרת הסביבה של Agent Runtime

במסמך הזה מוסבר איך לפתור שגיאות שיכולות להתרחש כשמגדירים סביבה ל-Agent Runtime. המאמר כולל שלבים לפתרון בעיות בייבוא חבילות.

שגיאות בייבוא של Agent Platform SDK

אם לא הצלחתם לייבא את Agent Platform SDK for Python, יכול להיות שהבעיה נובעת מאחת מהסיבות הבאות:

גרסה מיושנת של Agent Platform SDK ל-Python

בעיה:

מופיעה הודעת שגיאה שדומה להודעה הבאה:

ImportError: cannot import name 'reasoning_engines' from 'vertexai.preview'

או

ImportError: cannot import name 'agent_angines' from 'vertexai'

סיבה אפשרית:

יכול להיות שהבעיה הזו מתרחשת אם הגרסה של חבילת google-cloud-aiplatform ישנה יותר מ-1.82.0 (במקרה של agent_engines) או מ-1.47.0 (במקרה של reasoning_engines). כדי לבדוק את הגרסה של חבילת google-cloud-aiplatform, מריצים את הפקודה הבאה בטרמינל:

pip show google-cloud-aiplatform

פתרון מומלץ:

כדי לעדכן את חבילת google-cloud-aiplatform, מריצים את הפקודה הבאה בטרמינל:

pip install google-cloud-aiplatform --upgrade

מריצים את הפקודה הבאה כדי לוודא שהגרסה המעודכנת היא 1.82.0 ואילך:

pip show google-cloud-aiplatform

אם אתם נמצאים במופע של מחברת (לדוגמה, Jupyter,‏ Colab או Workbench), יכול להיות שתצטרכו להפעיל מחדש את זמן הריצה כדי להשתמש בחבילות המעודכנות.

שגיאות הרשאה 401

בעיה:

מופיעה הודעת שגיאה שדומה להודעה הבאה:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

או

Agent Engine Error: An error occurred during invocation. Exception: API request failed with status 401:
Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.

סיבה אפשרית:

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

1. משתמש או סוכן שמנסים להשתמש באסימון גישה מחוץ להקשר שבו הוא הונפק, למשל העברת האסימון בין סוכנים.
2. הסוכן מתקשר עם נקודת קצה ל-API שלא תואמת ל-mTLS, כמו telemetry.googleapis.com במקום telemetry.mtls.googleapis.com.

פתרון מומלץ:

בתרחיש מספר 1, אם יש לכם סיבה מוצדקת לשתף טוקנים בין סוכנים, אתם יכולים לבטל את מדיניות ברירת המחדל של בקרת הגישה מבוססת-ההקשר (CAA). לא מומלץ לבצע את הפעולה הזו, כי היא חושפת את הסוכן לגניבת פרטי הכניסה.

כדי לבטל את ההצטרפות למדיניות ברירת המחדל של CAA, צריך להגדיר את משתנה הסביבה הבא כשיוצרים את המופע של Agent Runtime:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

בתרחיש מספר 2, אפשר להגדיר את המשתנה GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES לערך False כדי לאפשר לסוכנים להשתמש בנקודות הקצה של ה-API שאינן mTLS כפתרון זמני. במקרה הזה, הבעיה הבסיסית יכולה להיות בעיה מוכרת ב-ADK.