‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

אזהרה: התכונה הזו לא נתמכת במיקומים מרובי-אזורים us ו-eu. חובה להשתמש באזור נתמך או במיקום global. מידע נוסף זמין במאמר מיקומי רישום של סוכנים.

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

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

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

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

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

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

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

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

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

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

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

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

המסוף

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

כניסה ל-Agent Registry
בכלי לבחירת פרויקטים, בוחרים את Google Cloud הפרויקט שבו הגדרתם את Agent Registry.
לוחצים על הכרטיסייה סוכנים.
לוחצים על הוספת סוכן.
בחלונית פרטי הסוכן, מזינים את הפרטים הבאים:
- סוג: בוחרים באפשרות A2A.
- אזור: בוחרים את המיקום הגיאוגרפי שבו רוצים לרשום את הסוכן.
בוחרים אחת מהאפשרויות האלה:
- כדי לרשום את הסוכן באמצעות כתובת ה-URI של המשאב, בוחרים בכרטיסייה מכתובת URI ומזינים כתובת URL תקינה בשדה URI. לאחר מכן לוחצים על ייבוא כדי לייבא את כרטיס הנציג מכתובת ה-URL.
- כדי להעתיק ולהדביק את התוכן של כרטיס הסוכן, בוחרים בכרטיסייה הדבקת JSON ומדביקים את התוכן המלא של קובץ agent-card.json.
לוחצים על 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.

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

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

המסוף

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

כניסה ל-Agent Registry
בכלי לבחירת פרויקטים, בוחרים את ה Google Cloud פרויקט שבו הגדרתם את Agent Registry.
לוחצים על הכרטיסייה סוכנים.
לוחצים על הוספת סוכן.
בחלונית פרטי הסוכן, מזינים את הפרטים הבאים:
- סוג: בוחרים באפשרות לא A2A.
- שם: מזינים שם מוצג של הסוכן שקריא לבני אדם, כמו Travel Agent.
- תיאור: מזינים תיאור של היכולות של הסוכן, כמו A test agent that plans travel itineraries.
- אזור: בוחרים את המיקום הגיאוגרפי שבו רוצים לרשום את הסוכן.
- נקודת קצה: מזינים את נקודת הקצה שבה מתארח הסוכן.
לוחצים על 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.

רישום סוכן מפרויקט אחר

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

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

שיקולים לגבי רישום בין פרויקטים

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

מיקומים תואמים: המופע של Agent Registry,‏ Agent Gateway ונקודות הקצה של הסוכן צריכים להיות באותו אזור גיאוגרפי או במיקום global.
מגבלה של גילוי אוטומטי: גילוי אוטומטי בין פרויקטים לא אפשרי. צריך לרשום ידנית כל סוכן מרוחק.
ניהול מחזור חיים: רשומות ידניות ב-Agent Registry לא מתעדכנות או נמחקות באופן אוטומטי כשמתרחשים שינויים בפרויקט המרוחק. כשסוכנים מרוחקים משתנים או מוסרים, צריך לנהל את מחזור החיים של הרשומות האלה במרשם המרכזי.
במצב יציאה בלבד: ניהול חוצה-פרויקטים באמצעות Agent Gateway נתמך רק בשערי Agent-to-Anywhere (יציאה). כדי להשתמש בשערי כניסה (ingress) מסוג Client-to-Agent, הסוכן ושער הכניסה צריכים להיות באותו פרויקט.

רישום הסוכן המרוחק

כדי לרשום סוכן באופן ידני מפרויקט אחר, פועלים לפי השלבים הבאים:

המסוף

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

כניסה ל-Agent Registry
בכלי לבחירת פרויקטים, בוחרים את פרויקט השליטה המרכזי Google Cloudשבו רוצים לרשום את הסוכן.
לוחצים על הכרטיסייה סוכנים.
לוחצים על הוספת סוכן.
בחלונית פרטי הסוכן, מזינים את הפרטים הבאים:
- סוג: בוחרים באפשרות A2A אם הסוכן המרוחק מטמיע את פרוטוקול A2A, או באפשרות Non-A2A אם מדובר בנקודת קצה רגילה של REST.
- Region: בוחרים את האזור שתואם לפריסת השער המרכזי והסוכן המרוחק.
מזינים את נקודת הקצה של הסוכן:
- עבור סוכני A2A, בוחרים באפשרות מכתובת URI ומזינים את כתובת ה-URL של כרטיס הסוכן המרוחק, או בוחרים באפשרות הדבקת JSON ומדביקים את התוכן של agent-card.json.
- עבור סוכנים שאינם A2A, מזינים את כתובת ה-URL של נקודת הקצה של הסוכן המרוחק.
לוחצים על Save.

gcloud

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

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

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

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

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

‫AGENT_NAME: השם של הסוכן במרשם המרכזי, לדוגמה, remote-support-agent.
‫CENTRAL_PROJECT_ID: מזהה הפרויקט של פרויקט השליטה המרכזי.
‫REGION: האזור שבו רושמים את הסוכן.
‫DISPLAY_NAME: שם קריא לאנשים של הסוכן, לדוגמה, Remote Support Agent.
‫REMOTE_ENDPOINT_URL: כתובת ה-URL של נקודת הקצה של הסוכן שפועל בפרויקט המרוחק, לדוגמה, https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app.
‫PROTOCOL: פרוטוקול הקישור של נקודת הקצה. הערכים התקינים הם http-json,‏ grpc או jsonrpc.

Terraform

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

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

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

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

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

‫CENTRAL_PROJECT_ID: מזהה הפרויקט של פרויקט השליטה המרכזי.
‫REGION: האזור שבו רושמים את הסוכן.
‫AGENT_NAME: השם הייחודי של הסוכן שלכם במאגר, לדוגמה, remote-support-agent.
‫DISPLAY_NAME: שם קריא לאנשים של הסוכן, לדוגמה, Remote Support Agent.
‫REMOTE_PROJECT_ID: מזהה הפרויקט שבו מתארח הסוכן.
‫REMOTE_ENDPOINT_URL: כתובת ה-URL של נקודת הקצה של הסוכן שפועל בפרויקט המרוחק.
‫PROTOCOL: פרוטוקול הקישור של נקודת הקצה. הערכים התקינים הם HTTP_JSON,‏ GRPC או JSONRPC.

אימות הרישום

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

המסוף

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

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

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

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: השם המוצג של הסוכן שקריא לאנשים.

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

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

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

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

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

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

המסוף

gcloud

Terraform

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

המסוף

gcloud

Terraform

רישום סוכן מפרויקט אחר

שיקולים לגבי רישום בין פרויקטים

רישום הסוכן המרוחק

המסוף

gcloud

Terraform

אימות הרישום

המסוף

gcloud

Terraform

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

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