רישום נקודות קצה

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

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

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

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

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

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

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

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

רישום נקודת קצה

מכיוון שנקודות הקצה הן יעדים חיצוניים מותאמים אישית, צריך להשתמש ברישום ידני כדי להוסיף אותן ל-Agent Registry:

המסוף

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

    כניסה ל-Agent Registry

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

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

  4. לוחצים על הוספת נקודת קצה.

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

    אפשר גם ללחוץ על בדיקת החיבור בחלונית הזו כדי לבדוק את החיבור לכתובת ה-URL של היעד.

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

gcloud

אתם יוצרים משאב Service עם endpoint-spec-type של no-spec.

רושמים את נקודת הקצה ומגדירים את פרטי החיבור של הממשק שלה:

gcloud agent-registry services create ENDPOINT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

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

  • ‫ENDPOINT_NAME: השם שרוצים לתת לנקודת הקצה, למשל my-external-api.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫REGION: האזור של המאגר.
  • ‫DISPLAY_NAME: השם של נקודת הקצה שקריא לאנשים.
  • ‫ENDPOINT_URL: כתובת היעד, לדוגמה, https://api.example.com/v1/data.
  • ‫PROTOCOL: הקישור לפרוטוקול של הממשק. הערכים התקינים הם http-json,‏ grpc או jsonrpc.

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

Terraform

כדי לרשום נקודת קצה חיצונית, מגדירים את המשאב google_agent_registry_service באמצעות הבלוק endpoint_spec:

resource "google_agent_registry_service" "endpoint" {
  location     = "REGION"
  service_id   = "ENDPOINT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external REST API registered using Terraform."

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

  endpoint_spec {
    type = "NO_SPEC"
  }
}

output "endpoint_resource_name" {
  description = "The generated read-only Endpoint resource name."
  value       = google_agent_registry_service.endpoint.registry_resource
}

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

  • ‫REGION: האזור של המאגר.
  • ‫ENDPOINT_NAME: השם הייחודי שרוצים לתת לנקודת הקצה, למשל my-external-api.
  • ‫DISPLAY_NAME: השם של נקודת הקצה שקריא לאנשים.
  • ‫ENDPOINT_URL: כתובת היעד, לדוגמה, https://api.example.com/v1/data.
  • ‫PROTOCOL: הקישור לפרוטוקול של הממשק. הערכים התקינים הם HTTP_JSON,‏ GRPC או JSONRPC.

רישום של נקודת קצה מורכבת של ממשקי Google APIs

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

כשמנתבים את תעבורת הנתונים של הסוכן דרך Agent Gateway במצב יציאה, תעבורת הנתונים היוצאת ברשת נחסמת כברירת מחדל. כדי לאפשר לסוכנים בפרויקטים של עומסי עבודה לתקשר עם ממשקי API חיוניים של Google Cloud , אפשר לקבץ כמה ממשקי API לנקודת קצה מורכבת אחת של Service בפרויקט המרכזי לניהול הרשאות.

קיבוץ הממשקים לנקודת קצה אחת מפשט את ניהול המדיניות, כי אפשר לנהל קשירת מדיניות אחת של IAP לכל חבילת הליבה של Google APIs.

כדי לרשום נקודת קצה מורכבת של Google APIs:

gcloud

רושמים את נקודת הקצה עם כמה כתובות URL של ממשקים בפרויקט המרכזי של ניהול ההרשאות:

gcloud agent-registry services create SERVICE_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=jsonrpc,url=API_URL \
  --interfaces=protocolBinding=jsonrpc,url=ADDITIONAL_API_URL

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

  • ‫SERVICE_NAME: המזהה של השירות, לדוגמה: core-gapi-services.
  • ‫CENTRAL_PROJECT_ID: מזהה הפרויקט של פרויקט השליטה המרכזי שמארח את Agent Registry ו-Agent Gateway.
  • ‫REGION: האזור שבו נמצאים השער והמאגר.
  • ‫DISPLAY_NAME: השם שקריא לאנשים, לדוגמה, Core Google APIs.
  • ‫DESCRIPTION: תיאור קצר, לדוגמה, Essential Google APIs for agent operations.
  • ‫API_URL: כתובת ה-URL של ה-API הראשי של Google, כמו https://telemetry.googleapis.com.
  • ‫ADDITIONAL_API_URL: חוזרים על האפשרות --interfaces לכל כתובת URL נוספת של Google API או וריאציה שנדרשת לסוכנים, כמו https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com, או וריאציות אזוריות ו-mTLS כמו https://telemetry.mtls.googleapis.com.

Terraform

כדי לרשום את נקודת הקצה של ממשקי Google API המורכבים באמצעות Terraform, מגדירים את המשאב google_agent_registry_service עם כמה בלוקים של interfaces:

resource "google_agent_registry_service" "core_gapi_services" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "SERVICE_NAME"
  display_name = "DISPLAY_NAME"
  description  = "DESCRIPTION"

  endpoint_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "API_URL"
    protocol_binding = "JSONRPC"
  }

  # Add an interfaces block for each additional Google API URL
  interfaces {
    url              = "ADDITIONAL_API_URL"
    protocol_binding = "JSONRPC"
  }
}

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

  • ‫CENTRAL_PROJECT_ID: מזהה הפרויקט של פרויקט השליטה המרכזי.
  • ‫REGION: האזור של המאגר.
  • ‫SERVICE_NAME: מזהה השירות.
  • ‫DISPLAY_NAME: השם שקריא לאנשים.
  • ‫DESCRIPTION: תיאור השירות.
  • ‫API_URL: כתובת ה-URL של ה-API הראשי של Google, כמו https://telemetry.googleapis.com.
  • ‫ADDITIONAL_API_URL: חוזרים על הבלוק interfaces לכל כתובת URL נוספת של Google API או לכל וריאציה שנדרשת על ידי הסוכנים, כמו https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com, או וריאציות אזוריות ו-mTLS כמו https://telemetry.mtls.googleapis.com.

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