ניהול קישורים

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

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

1. הגדרת Agent Registry.

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

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

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

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

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

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

• יצירה, עדכון ומחיקה של קישורים: אדמין של Agent Registry API (roles/agentregistry.admin)
• צפייה בקישורים: צפייה ב-Agent Registry API ‏(roles/agentregistry.viewer)

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

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

תרחישים מחייבים

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

• חיבורי משאבים: קישור של נציג מקור למשאב המטרה, כמו נציג אחר, שרת MCP או נקודת קצה. התרחיש הזה מאפשר לכם למפות Agentic Workflows עם כמה סוכנים, שבהם מתזמר ראשי מקצה משימות לסוכני משנה או לכלים ייעודיים.
• הרשאות שהוקצו: משייכים נציג לספק אימות כדי לאפשר לנציג להתחבר ליעדים חיצוניים או לכלים בהתאמה אישית באמצעות פרטי הכניסה שלו או בשם משתמש ספציפי. הקישור הזה נדרש אם הנציג צריך לבצע אימות מול שרתי MCP או כלים מרוחקים באמצעות אסימוני OAuth או מפתחות API. כשמשתמשים בקישורים, לא צריך להגדיר באופן ידני ספקי אימות בקוד. הוראות מפורטות מופיעות בקטע יצירת קישור לספק אימות במאמר הזה.

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

יצירת קישור

יוצרים כבילה כדי לחבר בין סוכן המקור למשאב המטרה:

gcloud

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

gcloud agent-registry bindings create BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --source-identifier="SOURCE_ID" \
    --target-identifier="TARGET_ID"

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

• ‫BINDING_NAME: השם שרוצים לתת לקישור, לדוגמה my-custom-binding.
• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.
• ‫DISPLAY_NAME: השם הקריא לאנשים שרוצים לתת לקישור, לדוגמה My Custom Binding.
• ‫SOURCE_ID: מזהה הסוכן של סוכן המקור בפורמט Uniform Resource Name ‏(URN).
• ‫TARGET_ID: מזהה המרשם של משאב המטרה בפורמט URN, כמו מזהה סוכן, מזהה שרת MCP או מזהה נקודת קצה.

Terraform

כדי ליצור קישור בין סוכן מקור למשאב המטרה, צריך להגדיר משאב google_agent_registry_binding. כדי להגדיר קישור צריך להשתמש בבלוק target:

resource "google_agent_registry_binding" "agent_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Connects a source agent to a target resource."

  source {
    identifier = "SOURCE_ID"
  }

  target {
    identifier = "TARGET_ID"
  }
}

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

• ‫REGION: האזור של המרשם.
• ‫BINDING_NAME: השם הייחודי שרוצים לתת לקישור.
• ‫DISPLAY_NAME: השם הקריא לאנשים של הקישור.
• ‫SOURCE_ID: מזהה הסוכן של סוכן המקור בפורמט URN.
• ‫TARGET_ID: מזהה המרשם של משאב המטרה בפורמט URN.

יצירת קישור לספק אימות

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

כשמציינים את שם המשאב --auth-provider-binding, צריך להשתמש במזהה הפרויקט:

gcloud

מריצים את הפקודה gcloud agent-registry bindings create עם הדגל --auth-provider-binding:

gcloud agent-registry bindings create BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --source-identifier="SOURCE_ID" \
    --target-identifier="TARGET_ID" \
    --auth-provider-binding="projects/PROJECT_ID/locations/REGION/authProviders/AUTH_PROVIDER_ID"

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

• ‫BINDING_NAME: השם הייחודי שרוצים לתת לקישור.
• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.
• ‫DISPLAY_NAME: השם הקריא לאנשים של הקישור.
• ‫SOURCE_ID: מזהה הסוכן של סוכן המקור בפורמט URN.
• ‫TARGET_ID: מזהה המרשם של משאב המטרה בפורמט URN.
• ‫AUTH_PROVIDER_ID: המזהה של ספק האימות.

Terraform

כדי להגדיר קישור של ספק אימות ב-Terraform, מציינים את הבלוק auth_provider_binding עם שם המשאב של ספק האימות, יחד עם ההיקפים שלו וכתובת ה-URI להמשך:

resource "google_agent_registry_binding" "auth_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"

  source {
    identifier = "SOURCE_ID"
  }

  target {
    identifier = "TARGET_ID"
  }

  auth_provider_binding {
    auth_provider = "projects/PROJECT_ID/locations/REGION/authProviders/AUTH_PROVIDER_ID"
    scopes        = [SCOPES]
    continue_uri  = "CONTINUE_URI"
  }
}

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

• ‫REGION: האזור של המרשם.
• ‫BINDING_NAME: השם הייחודי שרוצים לתת לקישור.
• ‫DISPLAY_NAME: השם הקריא לאנשים של הקישור.
• ‫SOURCE_ID: מזהה הסוכן של סוכן המקור בפורמט URN.
• ‫TARGET_ID: מזהה המרשם של משאב המטרה בפורמט URN.
• ‫PROJECT_ID: מזהה הפרויקט.
• ‫AUTH_PROVIDER_ID: המזהה של ספק האימות.
• ‫SCOPES: רשימה מופרדת בפסיקים של היקפי הרשאות של OAuth 2.0, לדוגמה, "https://www.googleapis.com/auth/cloud-platform".
• ‫CONTINUE_URI: ה-URI להמשך של ספק האימות, לדוגמה, https://example.com/continue.

במאמר פתרון קישורים בקוד של ערכת פיתוח הסוכנים (ADK) מוסבר איך להשתמש בקישורים האלה בקוד של הסוכן.

הצגת רשימה של קישורים

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

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

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

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

הצגת פרטי הקישור

כדי לאחזר את הפרטים של קישור יחיד, מריצים את הפקודה gcloud agent-registry bindings describe:

gcloud agent-registry bindings describe BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION

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

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

עדכון קישור

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

gcloud

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

gcloud agent-registry bindings update BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="NEW_DISPLAY_NAME"

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

• ‫BINDING_NAME: שם הקישור שרוצים לעדכן.
• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.
• ‫NEW_DISPLAY_NAME: השם החדש של הקישור שקריא לאנשים.

Terraform

כדי לעדכן את השם המוצג או התיאור של קישור באמצעות Terraform, משנים את המשאב הקיים google_agent_registry_binding בהגדרות ומריצים את terraform apply.

מחיקת קישור

כדי להסיר קישור בין משאבים, צריך למחוק את הקישור:

gcloud

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

gcloud agent-registry bindings delete BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION

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

• ‫BINDING_NAME: שם הקישור שרוצים למחוק.
• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.

Terraform

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

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

• איך מבצעים אימות לכלים ולמשאבים באמצעות קישורים של ספקי אימות.
• איך פותרים בעיות בנקודות קצה ויוצרים תזמורים באמצעות ADK.