ניהול מיומנויות

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

במאמר הזה מוסבר איך לבצע את המשימות האדמיניסטרטיביות האלה.

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

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

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

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

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

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

פירוט של רשימת המיומנויות וצפייה בהן

אתם יכולים לעיין בכל המיומנויות הרשומות או לחפש יכולות ספציפיות:

המסוף

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

    כניסה ל-Agent Registry

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

gcloud

כדי להציג רשימה של כל המיומנויות במיקום מסוים:

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

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

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

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

  • ‫SKILL_ID: המזהה של המיומנות שרוצים לבדוק.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: מיקום המאגר.

REST

כדי לאחזר את רשימת כל המיומנויות:

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

כדי לאחזר מאגר מיומנויות יחיד:

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

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

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: מיקום המאגר.
  • ‫SKILL_ID: המזהה של המיומנות שרוצים לבדוק.

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

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

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

המסוף

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

    כניסה ל-Agent Registry

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

  5. בוחרים אחת מהאפשרויות הבאות:

    • עדכון מטא-נתונים של סקיל:

      1. לוחצים על עריכה.
      2. בחלונית עריכת היכולת, מעדכנים את השם לתצוגה או את תיאור היכולת.
      3. לוחצים על Save.

    • עדכון הגרסה שמוגדרת כברירת מחדל:

      1. מחפשים את הטבלה Version history (היסטוריית גרסאות).
      2. מוצאים את הגרסה שרוצים להגדיר כפעילה.
      3. בעמודה 'פעולות', לוחצים על הפעלת הגרסה.

gcloud

  • כדי לעדכן את המטא-נתונים של מיומנות:

    gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION"

  • כדי לעדכן את גרסת ברירת המחדל של הסקיל:

    gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --default-revision="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

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

  • ‫SKILL_ID: המזהה של הסקיל שרוצים לעדכן.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: מיקום המאגר.
  • ‫DISPLAY_NAME: השם המוצג המעודכן.
  • ‫DESCRIPTION: התיאור המעודכן.
  • ‫REVISION_ID: המזהה של הגרסה של המיומנות שרוצים להגדיר כברירת מחדל.

REST

שולחים PATCH בקשה עם השדות שרוצים לעדכן:

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "defaultRevision": "projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,defaultRevision"

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

  • ‫DISPLAY_NAME: השם המוצג המעודכן של המיומנות.
  • ‫DESCRIPTION: התיאור המעודכן של המיומנות.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: מיקום המאגר.
  • ‫SKILL_ID: המזהה של הסקיל שרוצים לעדכן.
  • ‫REVISION_ID: המזהה של הגרסה של המיומנות שרוצים להפעיל.

ניהול מצבי מחזור החיים של מיומנויות

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

  • טיוטה: הסקיל נמצא בשלב הראשוני של יצירה או פיתוח. הוא לא מוגש בזמן ריצה, והורדות של מטען ייעודי (payload) נחסמות. במצב הזה אפשר לשנות את ההגדרות של היכולת ואת המטען הייעודי (payload) באופן חופשי, לפני שמקדמים את היכולת למצב היעד פעיל.
  • פעילה: המיומנות מוצגת וניתן לפתור אותה באופן מלא.
  • מושבת: ניסיון לפתור את הסקיל נכשל באופן מיידי, וההורדות נחסמות. בניגוד למצב Decommissioned, אפשר להפעיל מחדש את המיומנות בשלב מאוחר יותר, כלומר להחזיר אותה למצב היעד Active.
  • הוצאה משימוש: אפשר להמשיך לטעון את המיומנות, אבל היא מחזירה כותרות אזהרה שמציינות שהיא תצא משימוש.
  • יצא משימוש: המיומנות מושבתת באופן סופי, לא מוצגת יותר, ואי אפשר להחזיר אותה למצב פעיל או לכל מצב אחר. אפשר להוציא משימוש מיומנות רק אחרי שהיא כבר הוצאה משימוש. חשוב להקצות מספיק זמן להעברה לפני שמוציאים את המיומנות משימוש. זהו מצב סופי, ומומלץ להשתמש בו בזהירות רבה.

כדי להעביר מיומנות למצב אחר במחזור החיים שלה:

המסוף

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

    כניסה ל-Agent Registry

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

gcloud

מעדכנים את מאגר המיומנויות באמצעות הדגל --target-state:

gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --target-state=DISABLED

הערכים המותרים למצב היעד הם:

  • DRAFT
  • ACTIVE
  • DISABLED
  • DEPRECATED
  • DECOMMISSIONED.

REST

שולחים בקשת PATCH עם הפרמטר targetState בגוף הבקשה ובמסכת העדכון:

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "targetState": "TARGET_STATE_DISABLED"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=targetState"

הערכים המותרים למצב היעד הם:

  • TARGET_STATE_DRAFT
  • TARGET_STATE_ACTIVE
  • TARGET_STATE_DISABLED
  • TARGET_STATE_DEPRECATED
  • TARGET_STATE_DECOMMISSIONED.

מחיקת סקיל

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

המסוף

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

    כניסה ל-Agent Registry

  2. לוחצים על הכרטיסייה כישורים.
  3. בודקים את רשימת המיומנויות. אפשר לסנן את התצוגה באמצעות התפריטים מיקום או סטטוס.
  4. לוחצים על השם של הסקיל שרוצים למחוק.
  5. בדף Skill Details (פרטי המיומנות), לוחצים על Delete (מחיקה).
  6. בתיבת הדו-שיח לאישור, מזינים DELETE ולוחצים על מחיקה.

gcloud 

gcloud alpha agent-registry skills delete 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?force=true"

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