ניהול סוכנים

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

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

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

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

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

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

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

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

עוד סוכנים

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

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

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

המסוף

1. במסוף Google Cloud , עוברים אל Agent Registry:

   כניסה ל-Agent Registry

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

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

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

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

gcloud

כדי לראות את הרשימה של כל הסוכנים במיקום ספציפי, משתמשים בפקודה agents list:

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

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המאגר.

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

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

המסוף

1. במסוף Google Cloud , עוברים אל Agent Registry:

   כניסה ל-Agent Registry

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

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

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

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

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

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

gcloud

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

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

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

• כדי לסנן לפי השם המוצג, משתמשים ב-displayName='DISPLAY_NAME'.
• כדי לחפש לפי מזהה (URN) ייחודי גלובלי, משתמשים בפונקציה agentId='urn:agent:AGENT_URN'.

Terraform

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

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

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

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

צפייה בפרטים מנציג

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

המסוף

1. במסוף Google Cloud , עוברים אל Agent Registry:

   כניסה ל-Agent Registry

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

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

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

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

   בדף הפרטים יש כרטיסיות עם פרטי הסוכן.

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

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

   • סקירה כללית: פרטים מרכזיים מהסוכן, כולל השם, המזהה, המיקום, התיאור וזמן הריצה של הסוכן. בסקירה הכללית מוצגים גם כישורים ומזהה ה-URI של המשאב, שנדרשים לבניית שאילתות בתרשים הטופולוגיה.
   • יכולת צפייה (Observability): תובנות שמתמקדות באפליקציה, כמו זמן אחזור, תעבורה, שגיאות והוצאות על אסימונים. הכרטיסייה הזו משולבת עם כלי Google Cloud Observability כדי להציג מדדי ביצועים בזמן אמת וניצול ברמת המערכת, וכך לעזור לכם לנהל את העלויות ואת חוויית המשתמש. מידע נוסף מופיע במאמר סקירה כללית על יכולת התצפית.
   • עקבות: הנתיב המדויק של שיחה, שלב אחר שלב, כולל עיצוב מפורט של הודעות קלט והודעות של העוזר הדיגיטלי, כדי לנפות באגים בלולאות מורכבות של נימוקים מרובי-סוכנים או בשגיאות בהפעלת כלים בזמן אמת. מידע נוסף מופיע במאמר בנושא צפייה בנתוני מעקב של סוכנים.
   • אבטחה: ממצאים מ-Model Armor ומ-Security Command Center, כולל הפרות של מדיניות התוכן, סיכונים של דליפת נתונים והערכות תאימות. מידע נוסף על אבטחה זמין במאמר בנושא הצגת ממצאי אבטחה.
   • טופולוגיה: מפה חזותית של הקשרים וזרימות התנועה בין סוכן, שער הסוכן שהוקצה לו ושרתי ה-MCP שהוא מתקשר איתם. מידע נוסף על Agent Gateway זמין בסקירה הכללית על Agent Gateway. מידע נוסף על טופולוגיה זמין במאמר הצגת גרפים של סוכן רשום.
   • זהות: החשבון הראשי של הסוכן שמשמש לאכיפת המדיניות. לדוגמה, אפשר להשתמש בזהות הזו כדי להגדיר קישורי ספק אימות לאימות לכלים ולמשאבים.
   • סשנים: היסטוריית שיחות קבועה ומעקב אחרי אינטראקציות פעילות עם הנציג.
   • סביבת ניסויים: ממשק צ'אט ישיר לבדיקת התנהגות הסוכן.
   • זיכרונות: תכונות התאמה אישית לטווח ארוך שיוצרות או שולפות פרטים משיחות קודמות עם הסוכן כדי לשמור על ההקשר בין האינטראקציות.
   • הערכה: פרטים של כל משימות הערכת הסוכן. בכרטיסייה הזו אפשר ליצור משימות הערכה חדשות, להעלות מדדים ולהעריך את הביצועים הקוגניטיביים של הסוכן ואת מהימנות המודל בהשוואה לתנועת נתונים בזמן אמת או לסימולציות סינתטיות.

gcloud

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

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

מחליפים את AGENT_NAME בשם הסוכן, לדוגמה, my-custom-agent.

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 API, משתמשים במשאבי Agent לגילוי. לכן, עליך לעדכן את משאב Service הרשום באופן ישיר.

המסוף

עדכון הפרטים הזמינים של הנציג דרך Google Cloud המסוף:

1. במסוף Google Cloud , עוברים אל Agent Registry:

   כניסה ל-Agent Registry

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

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

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

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

5. בכרטיסייה סקירה כללית של הסוכן, לוחצים על עריכה.

6. בחלונית Edit service, מזינים את המידע המעודכן של הסוכן, כמו השם או התיאור החדשים שלו.

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

gcloud

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

• עדכון השם המוצג והתיאור: משתמשים בדגלים --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
  

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

  • ‫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
  

  מחליפים את AGENT_SPEC בשם של קובץ המפרט של הסוכן החדש, לדוגמה, new-agent-card.json. גודל הקובץ המקסימלי של קובץ המפרט הוא 10KB.

Terraform

כדי לעדכן את המטא-נתונים, כתובת נקודת הקצה או המפרט של הסוכן הרשום, משנים את הפרמטרים של משאב 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.remote-service.com/v1/agents/1234.
• ‫PROTOCOL: פרוטוקול הקישור של נקודת הקצה. הערכים התקינים הם HTTP_JSON,‏ GRPC או JSONRPC.

הסרת סוכן

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

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

המסוף

1. במסוף Google Cloud , עוברים אל Agent Registry:

   כניסה ל-Agent Registry

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

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

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

4. לוחצים על השם של הסוכן שרוצים להסיר.

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

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

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

gcloud

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.

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

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