שימוש ברישום ידני

צריך לרשום ידנית סוכנים שמתארחים מחוץ ל-Google Cloud או שפועלים בסביבות זמן ריצה לא נתמכות. במאמר הזה מוסבר איך לרשום סוכנים באופן ידני במרשם הסוכנים.

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

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

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

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

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

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

רישום סוכן שתואם ל-A2A

אם הסוכן המרוחק שלכם מטמיע את המפרט של Agent2Agent‏ (A2A), צריך להפנות את Agent Registry אל מטען הייעודי (payload) של הסוכן agent-card.json. הרישום מסנכרן אוטומטית את כרטיס הסוכן ומבצע אינדקס של הכישורים הזמינים של הסוכן לצורך גילוי.

כדי לרשום את הסוכן:

המסוף

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

    כניסה ל-Agent Registry

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

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

  4. לוחצים על הוספת סוכן.

  5. בחלונית פרטי הסוכן, מזינים את הפרטים הבאים:

    • סוג: בוחרים באפשרות A2A.
    • אזור: בוחרים את המיקום הגיאוגרפי שבו רוצים לרשום את הסוכן.

  6. בוחרים אחת מהאפשרויות האלה:

    • כדי לרשום את הסוכן באמצעות כתובת ה-URI של המשאב, בוחרים בכרטיסייה מכתובת URI ומזינים כתובת URL תקינה בשדה URI. לאחר מכן לוחצים על ייבוא כדי לייבא את כרטיס הנציג מכתובת ה-URL.
    • כדי להעתיק ולהדביק את התוכן של כרטיס הסוכן, בוחרים בכרטיסייה הדבקת JSON ומדביקים את התוכן המלא של קובץ agent-card.json.

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

gcloud

כדי לרשום סוכן A2A, שומרים את כרטיס הסוכן של הסוכן כקובץ JSON מקומי, לדוגמה, agent-card.json, ומבצעים את הפעולות הבאות:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=agent-card.json

גודל הקובץ המקסימלי של קובץ המפרט הוא 10 KB.

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

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

Terraform

כדי לרשום סוכן שתואם ל-A2A, מגדירים את המשאב google_agent_registry_service. מציינים את הבלוק agent_spec עם הסוג A2A_AGENT_CARD ואת content שמייצג את מטען ה-JSON של כרטיס הנציג:

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = jsonencode({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

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

  • ‫REGION: האזור שבו רושמים את הסוכן.
  • ‫AGENT_NAME: השם הייחודי שרוצים לתת לסוכן, לדוגמה, my-support-agent.
  • ‫DISPLAY_NAME: השם שרוצים לתת לסוכן, שקריא לאנשים. לדוגמה, Support Agent.

רישום סוכן REST רגיל

אפשר לגלות סוכני REST רגילים לפי השם והתיאור שלהם, אבל אין להם מיומנויות שאפשר לחפש אלא אם הם פועלים לפי פרוטוקול A2A.

אם רוצים לרשום סוכן מרוחק שלא מיישם את מפרט A2A, כמו נקודת קצה רגילה של REST או SaaS API, ‏ Agent Registry API יוצר משאב Service ללא מפרט פרוטוקול סוכן.

כדי לרשום את הסוכן:

המסוף

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

    כניסה ל-Agent Registry

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

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

  4. לוחצים על הוספת סוכן.

  5. בחלונית פרטי הסוכן, מזינים את הפרטים הבאים:

    • סוג: בוחרים באפשרות לא A2A.
    • שם: מזינים שם מוצג של הסוכן שקריא לבני אדם, כמו Travel Agent.
    • תיאור: מזינים תיאור של היכולות של הסוכן, כמו A test agent that plans travel itineraries.
    • אזור: בוחרים את המיקום הגיאוגרפי שבו רוצים לרשום את הסוכן.
    • נקודת קצה: מזינים את נקודת הקצה שבה הסוכן מתארח.

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

gcloud

אפשר גם לספק את ממשק נקודת הקצה המוגדר HTTP/JSON באמצעות הדגל --interfaces כדי שהמאגר יצור חיבור עם הסוכן.

כדי לרשום סוכן REST רגיל:

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

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

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

Terraform

כדי לרשום סוכן REST רגיל, צריך להגדיר את המשאב google_agent_registry_service עם agent_spec שמוגדר ל-NO_SPECtype, ולהגדיר את חיבורי הממשק של נקודת הקצה:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

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

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

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

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

אימות הרישום

אחרי שרושמים את הנציג, צריך לוודא ש-Agent Registry עיבד בהצלחה את Service ויצר את משאב Agent המתאים:

המסוף

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

    כניסה ל-Agent Registry

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

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

    בדף צריך להופיע רשימה של כל הסוכנים הרשומים והפרטים שלהם.

gcloud 

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

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

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

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

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

Terraform

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

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

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

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

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

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