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

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

משתמשים בקישורים כדי לטפל בשני תרחישים:

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

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

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

לפני שמתחילים לנהל את הקישורים, צריך לבצע את הפעולות הבאות:

  1. הגדרת Agent Registry
  2. רושמים את רכיבי המקור והיעד. מידע נוסף על רישום רכיבים עם יכולות של סוכנים
  3. כדי להגדיר קישורים להרשאות מוקצות, צריך ליצור ספק אימות עם מנהל אימות של זהות סוכן. מידע נוסף זמין במאמר אימות לכלים ולמשאבים.
  4. כדי להשתמש בפקודות של Google Cloud CLI שמופיעות במסמך הזה, צריך לוודא שהגדרתם את סביבת gcloud CLI.

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

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

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

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

יצירת קשר

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

gcloud 

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: המזהה של סוכן המקור בפורמט של שם משאב אחיד (URN).
  • ‫TARGET_ID: המזהה של משאב היעד בפורמט URN, כמו מזהה של שרת MCP.

Terraform

כדי ליצור קישור בין סוכן מקור למשאב יעד, צריך להגדיר משאב google_agent_registry_binding. כדי ליצור קשר בין כתובת IP לבין חסימה, צריך להשתמש ב-target block:

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 = "urn:agent:my-publisher:my-namespace:SOURCE_AGENT_NAME"
  }

  target {
    identifier = "urn:mcp:my-publisher:my-namespace:TARGET_RESOURCE_NAME"
  }
}

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

  • ‫REGION: האזור של המאגר.
  • ‫BINDING_NAME: השם הייחודי שרוצים לתת לקישור.
  • ‫DISPLAY_NAME: השם של הקישור שקריא לאנשים.
  • ‫SOURCE_AGENT_NAME: השם של סוכן המקור.
  • ‫TARGET_RESOURCE_NAME: השם של משאב היעד, כמו שרת או נקודת קצה של MCP.

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

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

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

gcloud 

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

מחליפים את 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 = "urn:agent:my-publisher:my-namespace:SOURCE_AGENT_NAME"
  }

  target {
    identifier = "urn:mcp:my-publisher:my-namespace:TARGET_RESOURCE_NAME"
  }

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

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

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

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

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

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

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

צפייה בפרטי הקישור

כדי לאחזר את הפרטים של קישור יחיד:

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

עדכון של קישור

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

gcloud 

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

Terraform

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

מחיקת קישור

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

gcloud 

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

Terraform

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

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