רישום מיומנויות

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

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

  1. הגדרת Agent Registry.

  2. משיגים את מזהה הפרויקט של פרויקט הפיקוח שבו מופעל Agent Registry.

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

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

כדי לקבל את ההרשאות שדרושות לרישום מיומנויות ב-Agent Registry, בקשו מהאדמין לתת לכם את התפקידים הבאים ב-IAM בפרויקט הפיקוח שבו Agent Registry מופעל:

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

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

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

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

כדי לרשום מיומנות, צריך לארוז את קובצי המקור של המיומנות בארכיון ZIP. הארכיון חייב לכלול קובץ הוראות SKILL.md ברמה הבסיסית (root). בשלב ההטמעה של תהליך רישום המיומנות, Agent Registry מאמת שהמטען הייעודי (payload) עומד במגבלות הבאות:

  • גודל ארכיון ZIP: גודל הארכיון הדחוס המקסימלי הוא 500KB.
  • גודל כולל של מטען ייעודי (payload) לא דחוס: עד 10MB.
  • גודל קובץ בודד: הגודל המקסימלי של קובץ לא דחוס הוא 1MB.
  • היררכיה עמוקה: עומק ההיררכיה המקסימלי של הספרייה הוא 8 רמות.
  • תאימות למפרט: קובץ ה-SKILL.md חייב להכיל קטע YAML תקין של front matter שמגדיר את השם, התיאור והמטא-נתונים, כפי שמוגדר במפרט המיומנויות של הסוכן.

רישום סקיל

אתם יכולים לרשום באופן ידני את המיומנויות שלכם ב-Agent Registry. במאמר התמחור של Agent Registry מוסבר כמה עולה להשתמש במיומנויות.

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

המסוף

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

    כניסה ל-Agent Registry

  2. בכלי לבחירת פרויקטים, בוחרים את הפרויקט ב- Google Cloud .

  3. לוחצים על הכרטיסייה מיומנויות.

  4. בכרטיסייה Skills, הכפתור Add skill מציג שתי אפשרויות ליצירת מאגר מיומנויות ולייבוא חבילת המיומנויות הראשונית. בוחרים אחת מהאפשרויות הבאות:

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

  5. בחלונית Create skill או Import skill, מציינים את הפרטים הבאים:

    • שם לתצוגה: מזינים שם ידידותי למשתמש בשביל המיומנות.
    • תיאור: סיכום קצר שמסביר את היכולות של המיומנות.
    • ‫Location: בוחרים את האזור הגיאוגרפי, לדוגמה global,‏ us או eu.

  6. בקטע Payload source (מקור המטען הייעודי), בוחרים אחת מהאפשרויות הבאות:

    • קובץ: גוררים את קובץ ה-ZIP של המיומנות או מחפשים בספרייה המקומית.

    • ‫Bucket: מזינים את הנתיב לארכיון ה-ZIP שמאוחסן בקטגוריה של Cloud Storage, בפורמט gs://BUCKET_NAME/SKILL_PACKAGE.zip.

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

    המיומנות נוצרת במצב מושבת (DISABLED). בכל הפעולות הבאות שקשורות למיומנות, צריך להתייחס למיומנות בתור private-SKILL_ID, כמו שמוצג במסוףGoogle Cloud .

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

gcloud

  1. יוצרים את מאגר המיומנויות ומעלים את המטען הייעודי (payload) של הגרסה הראשונית שלו באמצעות הפקודה gcloud alpha agent-registry skills create. אתם יכולים להעלות קובץ ZIP מקומי או לייבא חבילה שמאוחסנת ב-Cloud Storage:

    • העלאת קובץ ZIP מקומי: כדי לרשום מיומנות באמצעות מטען ייעודי (payload) של קובץ ZIP מקומי:

      gcloud alpha agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --target-state=disabled \
    --payload="LOCAL_ZIP_PATH"

      מחליפים את LOCAL_ZIP_PATH בנתיב לארכיון המיומנויות הארוזות במכונה המקומית, לדוגמה, ./workspace-docs-skill.zip.

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

      gcloud alpha agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --target-state=disabled \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

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

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

    מחליפים את הערכים הבאים בכל אחת מהפקודות:

    • ‫SKILL_ID: מזהה המשאב של המיומנות, לדוגמה workspace-docs-skill. אחרי היצירה, המרשם מוסיף באופן אוטומטי את הקידומת private-. בכל הפקודות הבאות של המיומנות, צריך להשתמש במזהה עם הקידומת, לדוגמה, private-workspace-docs-skill.
    • ‫PROJECT_ID: מזהה הפרויקט.
    • ‫LOCATION: האזור הגיאוגרפי, לדוגמה: global,‏ us או eu.
    • ‫DISPLAY_NAME: שם ידידותי למשתמש של המיומנות.
    • ‫DESCRIPTION: סיכום קצר שמסביר את היכולות של המיומנות.

  2. מיומנויות חדשות שנוצרות מתחילות במצב מושבת (DISABLED). כדי שהמיומנות תהיה זמינה לחיפוש על ידי סוכנים, מגדירים את גרסת ברירת המחדל שלה ומעדכנים את מצב היעד ל-Active. הוראות מופיעות במאמר ניהול מצבי מחזור החיים של מיומנויות.

REST

  1. יוצרים את מאגר המיומנויות עם גרסה ראשונית מוטמעת:

    שיטת ה-HTTP וכתובת ה-URL

    POST https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID

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

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

    גוף בקשת JSON (העלאת קובץ מקומי)

    כדי ליצור סקיל באמצעות העלאה ישירה של בייטים של ארכיון ZIP מקומי, משתמשים במטען הייעודי (payload) של archiveUploadSource. במהלך היצירה, צריך להגדיר את targetState לערך TARGET_STATE_DISABLED:

    {
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_DISABLED",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

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

    • ‫DISPLAY_NAME: שם ידידותי למשתמש של המיומנות.
    • ‫DESCRIPTION: סיכום קצר שמסביר את היכולות של המיומנות.
    • ‫BASE64_ZIP_BYTES: ייצוג מחרוזת בקידוד base64 של ארכיון ה-ZIP המקומי.

    גוף בקשת JSON (ייבוא מ-Cloud Storage)

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

    {
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_DISABLED",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

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

    • ‫DISPLAY_NAME: שם ידידותי למשתמש של המיומנות.
    • ‫DESCRIPTION: סיכום קצר שמסביר את היכולות של המיומנות.
    • ‫BUCKET_NAME: שם הקטגוריה ב-Cloud Storage שמכילה את חבילת ה-ZIP.
    • ‫SKILL_PACKAGE: השם של חבילת המיומנות שמכילה את המטען הייעודי (payload) של המיומנות.

    הפקודה curl (העלאת קובץ מקומי)

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "type": "SIMPLE",
      "targetState": "TARGET_STATE_DISABLED",
      "initialRevision": {
        "archiveUploadSource": {
          "archiveContent": "'"$(base64 -w0 local_skill.zip)"'"
        }
      }
    }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

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

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

    כדי להעלות קובץ לקטגוריה של Cloud Storage, מחליפים את גוף בקשת ה-JSON בשדות ובערכים המתאימים.

  2. מיומנויות חדשות שנוצרות מתחילות במצב מושבת (DISABLED). כדי שהמיומנות תהיה זמינה לחיפוש על ידי סוכנים, מגדירים את גרסת ברירת המחדל שלה ומעדכנים את מצב היעד ל-Active. הוראות מופיעות במאמר ניהול מצבי מחזור החיים של מיומנויות.

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

לדוגמה, אם יוצרים מיומנות עם המזהה workspace-tools, שם המשאב שנוצר הוא projects/PROJECT_NUMBER/locations/LOCATION/skills/private-workspace-tools. מזהה המיומנות מוקצה בתור urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. צריך להשתמש במזהה שפורסם ב-private-workspace-tools לכל הפעולות הבאות של המיומנות.

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