ניהול סוכנים

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

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

1. הגדרת Agent Registry.

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

3. רושמים את הסוכנים ב-Agent Registry.

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

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

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

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

איך מוצאים סוכנים זמינים

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

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

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

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

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

המסוף

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

   כניסה ל-Agent Registry

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

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

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

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

gcloud

כדי להציג את כל הנציגים במיקום מסוים, מריצים את הפקודה gcloud agent-registry agents list:

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION

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

• ‫PROJECT_ID: מזהה הפרויקט. אם הגדרתם גבול ניהול, ציינו את המזהה של פרויקט הניהול כדי להציג את הסוכנים במיקום שצוין בכל הפרויקטים החברים בגבול. כל שם משאב שמוחזר שומר על מזהה הנציג ומשתמש בפרויקט שצוין בבקשה.
• ‫REGION: המיקום של המאגר, למשל us-central1,‏ eu או global. בפרויקט ניהול, ציון מיקום מאגד נציגים באותו מיקום בכל הפרויקטים החברים בגבול.

סינון סוכנים רשומים

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

המסוף

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

   כניסה ל-Agent Registry

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

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

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

4. מסננים את הרשימה לפי המיקום, משאב זמן הריצה או המזהה של הסוכן:

   • כדי לסנן לפי מיקום, לוחצים על התפריט Location, בוחרים את המיקומים שרוצים לסנן ולוחצים על Apply.
   • כדי לסנן לפי סביבת זמן ריצה, לוחצים על התפריט Runtime, בוחרים את סביבות זמן הריצה שרוצים לסנן ולוחצים על Apply.
   • כדי להציג או להסתיר סוכני Google שנוצרו על ידי המערכת, לוחצים על Show system-created agents או על Hide system-created agents בסרגל הכלים של הטבלה. כדי להציג רק את הסוכנים המובנים של Google, לוחצים על Filter, מזינים urn:agent:googleapis.com: בשדה Agent ID ולוחצים על Apply.

   בדף מוצגת רשימה מסוננת של הנציגים הרשומים לפי התנאים שבחרתם.

gcloud

כדי לסנן את רשימת הסוכנים כך שיוחזרו רק משאבים שתואמים למטא-נתונים ספציפיים, מעבירים את הדגל --filter לפקודה gcloud agent-registry agents list:

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.
• ‫FILTER_EXPRESSION: ביטוי הסינון של הנציגים שרוצים לסנן. לדוגמה, אפשר להשתמש במסננים הבאים:
  • כדי לסנן לפי השם המוצג, משתמשים ב-displayName='DISPLAY_NAME'.
  • כדי לחפש לפי מזהה הסוכן הייחודי והגלובלי (URN), משתמשים ב-agentId='urn:agent:AGENT_URN'.
  • כדי להציג רק את הסוכנים המובנים של Google, משתמשים ב-agentId:"urn:agent:googleapis.com:".
  • כדי לסנן לפי פרויקט חבר ספציפי כששולחים שאילתה לפרויקט ניהול, משתמשים ב-agentId:"urn:agent:projects-MEMBER_PROJECT_NUMBER:".

Terraform

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

data "google_agent_registry_agent" "filtered_agent" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

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

• ‫REGION: האזור של המרשם.
• ‫DISPLAY_NAME: השם הקריא לאנשים של הנציג שלפיו רוצים לסנן, לדוגמה Support Agent.

הצגת פרטים של סוכן

כדי לראות פרטים של סוכן ספציפי, כולל הפרוטוקולים, הסקילים של A2A והזהות שלו:

המסוף

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

   כניסה ל-Agent Registry

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

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

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

4. לוחצים על שם הנציג שרוצים לראות.

   דף הפרטים כולל כרטיסיות עם פרטי הנציג.

5. לוחצים על הכרטיסייה המתאימה כדי לראות פרטים ספציפיים על הנציג.

   זמינות התכונות תלויה בסביבת זמן הריצה. כרטיסיות כמו Sessions,‏ Playground,‏ Memories ו-Evaluation הן יכולות ספציפיות שמופיעות לסוכנים שמבוססים על סביבות זמן ריצה מנוהלות, כמו Agent Runtime ב-Gemini Enterprise Agent Platform:

   • סקירה כללית: פרטים בסיסיים על הנציג, כולל השם, המזהה, המיקום, התיאור וזמן הריצה שלו. בסקירה הכללית מוצגות גם מיומנויות A2A והפניה לזמן ריצה, שנדרשות כדי ליצור שאילתות בתרשים הטופולוגי.
   • תצפיתיות: תובנות שמתמקדות באפליקציה, כמו זמן אחזור, תנועה, שגיאות והוצאות על טוקנים. הכרטיסייה הזו משתלבת עם הכלים של Google Cloud Observability כדי להציג מדדי ביצועים בזמן אמת וניצול ברמת המערכת, וכך לעזור לכם לנהל את העלויות ואת חוויית המשתמש. מידע נוסף מופיע בסקירה הכללית על ניראות.
   • ‫Traces: הנתיב המדויק של השיחה, שלב אחרי שלב, כולל עיצוב מפורט של הודעות הקלט והודעות העוזר הדיגיטלי, כדי לנפות באגים בלולאות חשיבה רציונלית מורכבות עם כמה סוכנים או בשגיאות בקריאות API לכלים בזמן אמת. מידע נוסף זמין במאמר הצגת מעקבים של נציגים.
   • אבטחה: ממצאים מהגנה מוגברת על המודל ומ-Security Command Center, כולל הפרות של מדיניות התוכן, סיכונים לדליפת נתונים והערכות תאימות. למידע נוסף על אבטחה, ראו הצגת ממצאי אבטחה.
   • ‫Topology: מפה חזותית של הקשרים וזרימת התנועה בין הסוכן, ה-Agent Gateway שהוקצה לו ושרתי ה-MCP שאיתם הוא יוצר אינטראקציה. מידע נוסף על Agent Gateway מופיע בסקירה הכללית על Agent Gateway. למידע נוסף על טופולוגיה, ראו הצגת תרשימים של סוכן רשום.
   • זהות: הישות המורשית של הסוכן שמשמשת לאכיפת המדיניות. אתם משתמשים בזהות הזו, למשל, כדי להגדיר קישורים של ספקי אימות לצורך אימות לכלים ולמשאבים.
   • סשנים: היסטוריית שיחות קבועה ומעקב אחרי אינטראקציות פעילות עם הנציג.
   • Playground: ממשק צ'אט ישיר לבדיקת ההתנהגות של הנציג.
   • זיכרונות: תכונות להתאמה אישית לטווח ארוך שיוצרות או מאחזרות פרטים משיחות קודמות עם הסוכן כדי לשמור על ההקשר בין האינטראקציות.
   • הערכה: פרטים על כל משימות הערכת תפקוד הסוכנים. בכרטיסייה הזו אפשר ליצור משימות הערכה חדשות, להעלות מדדים ולהעריך את הביצועים הקוגניטיביים של הנציג ואת אמינות המודל בהשוואה לתנועה בזמן אמת או לסימולציות סינתטיות.

gcloud

כדי לראות את המטא-נתונים המפורטים של סוכן ספציפי, מריצים את הפקודה gcloud agent-registry agents describe:

gcloud agent-registry agents describe AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION

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

• ‫AGENT_NAME: שם הנציג, לדוגמה my-custom-agent.
• ‫PROJECT_ID: מזהה הפרויקט. בגבול ניהול, אתם יכולים לציין את מזהה פרויקט הניהול או את המזהה של הפרויקט החבר שבו נפרס הסוכן. שם המשאב שמוחזר שומר על מזהה הנציג ומשתמש בפרויקט שצוין בבקשה.
• ‫REGION: האזור של המרשם.

Terraform

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

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  agent_id = "AGENT_ID"
}

output "agent_create_time" {
  description = "The timestamp when the agent was registered."
  value       = data.google_agent_registry_agent.my_agent.create_time
}

output "agent_update_time" {
  description = "The timestamp when the agent was last updated."
  value       = data.google_agent_registry_agent.my_agent.update_time
}

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

• ‫REGION: האזור של המרשם.
• ‫AGENT_ID: המזהה הייחודי של הנציג, לדוגמה my-custom-agent.

עדכון המטא-נתונים ונקודות הקצה של הנציג

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

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

המסוף

מעדכנים את פרטי הנציג הזמינים במסוף Google Cloud :

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

   כניסה ל-Agent Registry

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

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

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

4. לוחצים על השם של הנציג שרוצים לעדכן.

5. בכרטיסייה Overview של הנציג, לוחצים על Edit.

6. בחלונית Edit service, מזינים את הפרטים המעודכנים של הנציג, כמו השם או התיאור החדשים שלו.

7. לוחצים על Save.

gcloud

מריצים את הפקודה gcloud agent-registry services update עם דגלים ספציפיים כדי לשנות את הפרמטרים של הסוכן:

• עדכון השם המוצג והתיאור: משתמשים בדגלים --display-name ו---description, לדוגמה:

  gcloud agent-registry services update AGENT_NAME \
      --project=PROJECT_ID \
      --location=REGION \
      --display-name="New display name" \
      --description="Updated description of the agent's purpose."
  

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

  • ‫AGENT_NAME: שם הנציג, לדוגמה my-support-agent.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫REGION: האזור של המרשם.

• עדכון כתובת ה-URL של נקודת הקצה: משתמשים בדגל --interfaces כדי לציין את נקודת הקצה החדשה, לדוגמה:

  gcloud agent-registry services update AGENT_NAME \
      --project=PROJECT_ID \
      --location=REGION \
      --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
  

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

  • ‫AGENT_NAME: שם הנציג, לדוגמה my-support-agent.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫REGION: האזור של המרשם.
  • ‫ENDPOINT_URL: כתובת ה-URL החדשה של נקודת הקצה של הסוכן, לדוגמה https://new-api.example.com/agent.
  • ‫PROTOCOL: הקישור לפרוטוקול של נקודת הקצה. הערכים התקינים הם http-json,‏ grpc או jsonrpc.

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

  gcloud agent-registry services update AGENT_NAME \
      --project=PROJECT_ID \
      --location=REGION \
      --agent-spec-content=AGENT_SPEC_FILE
  

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

  • ‫AGENT_NAME: שם הנציג, לדוגמה my-support-agent.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫REGION: האזור של המרשם.
  • ‫AGENT_SPEC_FILE: הנתיב לקובץ המפרט החדש של הסוכן, לדוגמה new-agent-card.json. גודל הקובץ המקסימלי של קובץ המפרט הוא 10KB.

Terraform

כדי לעדכן את המטא-נתונים, את כתובת ה-URL של נקודת הקצה או את המפרט של הנציג הרשום, משנים את הפרמטרים של המשאב google_agent_registry_service הקיים בהגדרות, ואז מריצים את הפקודה terraform apply:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "New Display Name"
  description  = "Updated description of the agent's purpose."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

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

• ‫REGION: האזור של המרשם.
• ‫AGENT_NAME: השם הייחודי שרוצים לתת לנציג, לדוגמה my-support-agent.
• ENDPOINT_URL: כתובת ה-URL של נקודת קצה ל-API של הסוכן, לדוגמה https://api.example.com/v1/agents/1234.
• ‫PROTOCOL: הקישור לפרוטוקול של נקודת הקצה. הערכים התקינים הם HTTP_JSON,‏ GRPC או JSONRPC.

הסרת נציג

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

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

המסוף

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

   כניסה ל-Agent Registry

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

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

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

4. לוחצים על השם של הנציג שרוצים להסיר.

5. בכרטיסייה Overview של הנציג, לוחצים על Delete.

6. בתיבת הדו-שיח לאישור, מזינים DELETE כדי לאשר את הפעולה.

7. לוחצים על Delete.

gcloud

מריצים את הפקודה gcloud agent-registry services delete:

gcloud agent-registry services delete AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION

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

• ‫AGENT_NAME: שם הסוכן שרוצים להסיר, לדוגמה my-support-agent.
• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.

Terraform

מסירים את המשאב google_agent_registry_service שמייצג את הסוכן מההגדרות של Terraform, ואז מריצים את הפקודה terraform apply.

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

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