ניהול גרסאות של סקילז

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

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

לפני שמתחילים

לפני שמתחילים, צריך להגדיר את Agent Registry ולרשום מיומנות עצמאית. כדי לבצע את המשימות האלה, צריך מזהה פרויקט.

כדי להשתמש בפקודות של ה-CLI של gcloud שמופיעות במסמך הזה, צריך לוודא שהגדרתם את סביבת ה-CLI של gcloud.

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות לניהול עדכונים של מיומנויות במאגר הסוכנים, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM ‏Agent Registry User (roles/agentregistry.user) בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

יצירת גרסה חדשה של סקיל

כשיוצרים גרסה חדשה, מטען ZIP חדש מועלה למאגר התגים הקיים של ה-Skill. כשיוצרים גרסה חדשה של סקיל, היא הופכת אוטומטית לגרסה הפעילה של הסקיל. עם זאת, אפשר לעדכן את הגרסה שמוגדרת כברירת מחדל של סקיל בכל שלב. אפשר להוריד רק גרסאות פעילות.

גודל קובץ ה-ZIP המקסימלי של גרסת סקיל הוא 500 KB.

המסוף

  1. נכנסים לדף Agent Registry במסוף Google Cloud :

    כניסה ל-Agent Registry

  2. בוחרים בכרטיסייה מיומנויות ולוחצים על שם המיומנות.
  3. בדף פרטי המיומנות, מחפשים את הטבלה היסטוריית גרסאות.
  4. לוחצים על הוספת גרסה.

  5. בחלונית Add version (הוספת גרסה), בוחרים באחת מהאפשרויות הבאות:

    • קובץ: מעלים את החבילה או קובץ ה-ZIP שמכילים את הקוד או את קובץ ההוראות (SKILL.md) של ההנחיה. אפשר ללחוץ על עיון כדי למצוא את הקובץ בסביבה המקומית.

    • קטגוריה: צריך לספק URI של Cloud Storage ‏ (gs://...) שמכיל חבילת ZIP תקינה. אפשר ללחוץ על Browse כדי למצוא את הקובץ בקטגוריות של Cloud Storage.

  6. לוחצים על יצירה.

הגרסה של המיומנות מוצגת בטבלה Version history בדף Skill Details.

gcloud

אפשר ליצור גרסה למיומנות על ידי העלאת קובץ ZIP מקומי או ייבוא חבילה שמאוחסנת ב-Cloud Storage.

מחליפים את מה שכתוב בשדות הבאים:

  • ‫REVISION_ID: המזהה שרוצים להקצות לגרסה של המיומנות.
  • ‫SKILL_ID: המזהה של המיומנות שבה משתמשים לתיקון.
  • ‫PROJECT_ID: מזהה הפרויקט.

  • ‫LOCATION: מיקום המאגר.

  • העלאת קובץ ZIP מקומי: כדי ליצור גרסה של מיומנות באמצעות מטען ייעודי מקומי של קובץ ZIP:

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --payload="LOCAL_ZIP_PATH"

    מחליפים את LOCAL_ZIP_PATH בנתיב לארכיון של המיומנות הארוזה במחשב המקומי.

  • ייבוא מקטגוריה של Cloud Storage: כדי ליצור עדכון של מיומנות באמצעות ארכיון ZIP שמתארח בקטגוריה של Cloud Storage:

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫BUCKET_NAME: שם הקטגוריה של Cloud Storage שמכילה את חבילת ה-ZIP.
    • ‫SKILL_PACKAGE: השם של חבילת הסקיל שמכילה את גרסת הסקיל.

REST

כדי ליצור גרסה של סקיל, שולחים POST בקשה לאוסף הגרסאות. אפשר להעלות את מטען ה-ZIP ישירות או לציין נתיב ב-Cloud Storage.

  • העלאה של קובץ ZIP מקומי: מציינים archiveUploadSource שמכיל את הבייטים של קובץ ה-ZIP בקידוד base64 בגוף הבקשה. אפשר להשתמש בפקודה base64 בשורה ב-curl:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "archiveUploadSource": {
          "archiveContent": "$(base64 -w0 local_skill.zip)"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

  • ייבוא מקטגוריה של Cloud Storage: מציינים gcsSource בגוף הבקשה ומפנים לנתיב של הקטגוריה:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "gcsSource": {
          "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: מיקום המאגר.
  • ‫SKILL_ID: המזהה של מאגר המיומנויות.
  • ‫REVISION_ID: המזהה שרוצים להקצות לגרסה הזו.
  • ‫BUCKET_NAME: שם קטגוריית Cloud Storage שמכילה את קובץ ה-ZIP.
  • ‫SKILL_PACKAGE: השם של חבילת ה-ZIP.

הצגת רשימה של שינויים ותיאור שלהם

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

כדי לראות רשימה של הגרסאות ופרטים עליהן, פועלים לפי השלבים הבאים:

המסוף

  1. נכנסים לדף Agent Registry במסוף Google Cloud :

    כניסה ל-Agent Registry

  2. בוחרים בכרטיסייה מיומנויות ולוחצים על שם המיומנות.
  3. בדף פרטי המיומנות, מחפשים את הטבלה היסטוריית גרסאות.
  4. בודקים את מזהי הגרסאות, את זמן היצירה, את מצב השינוי ואת הפעולות הזמינות.

gcloud

כדי להציג רשימה של כל הגרסאות של סקיל:

gcloud alpha agent-registry skills revisions list \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

כדי לתאר את המטא-נתונים של גרסה ספציפית:

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST

כדי להציג רשימה של גרסאות:

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"

כדי לקבל מטא-נתונים של גרסה אחת:

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

הורדת מטען ייעודי (payload) של גרסה

אתם יכולים להוריד מטען ייעודי (payload) של קובץ ZIP שעבר קומפילציה של גרסה ספציפית לצורך אימות או ניפוי באגים מקומיים.

כדי להוריד את המטען הייעודי, צריכים להתקיים שני התנאים הבאים:

כדי להוריד את מטען הנתונים של עדכון פעיל, פועלים לפי השלבים הבאים:

המסוף

  1. נכנסים לדף Agent Registry במסוף Google Cloud :

    כניסה ל-Agent Registry

  2. בוחרים בכרטיסייה מיומנויות ולוחצים על שם המיומנות.
  3. בדף פרטי המיומנות, מחפשים את הטבלה היסטוריית גרסאות.
  4. מוצאים את הגרסה שרוצים להוריד.
  5. בעמודה 'פעולות', לוחצים על הורדה. מטען ה-ZIP יורד למחשב המקומי.

gcloud

כדי להוריד את מטען הנתונים של ארכיון של עדכון, מריצים את הפקודה describe עם הדגל --alt=media ומפנים את הפלט לקובץ:

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --flags="alt=media" > skill_payload.zip

REST

שולחים בקשת GET לכתובת ה-URL של המשאב של הגרסה, ומוסיפים את הפרמטר של השאילתה alt=media. חובה להשתמש בדגל -L עם curl כדי לעקוב אחרי הפניות אוטומטיות של HTTP:

curl -L -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -o skill_payload.zip \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID?alt=media"

מחיקה של גרסה ספציפית

כשמוחקים גרסה ספציפית, מטען ה-ZIP שלה והיסטוריית המטא-נתונים שלה מוסרים ממאגר הסוכנים.

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

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

המסוף

  1. נכנסים לדף Agent Registry במסוף Google Cloud :

    כניסה ל-Agent Registry

  2. בוחרים בכרטיסייה מיומנויות ולוחצים על שם המיומנות.
  3. בדף פרטי המיומנות, מחפשים את הטבלה היסטוריית גרסאות.
  4. מחפשים את הגרסה שרוצים למחוק.
  5. בעמודה 'פעולות', לוחצים על מחיקה ומאשרים את הפעולה.

gcloud 

gcloud alpha agent-registry skills revisions delete REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST 

curl -X DELETE \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

המאמרים הבאים