שימוש ברישום אוטומטי של נציגים

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

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

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

מטא-נתונים שנוספו לאינדקס באופן אוטומטי

המטא-נתונים והיכולות שנוספים לאינדקס של סוכן במהלך הרישום האוטומטי תלויים בשאלה אם הסוכן מטמיע את פרוטוקול Agent2Agent‏ (A2A):

• סוכנים שמטמיעים את פרוטוקול A2A: Agent Registry שולח שאילתה ל/.well-known/agent-card.json כרטיס הסוכן כדי לחלץ באופן אוטומטי את המיומנויות והיכולות של A2A שפורסמו ב-Agent Registry.
• סוכנים שלא מטמיעים את פרוטוקול A2A: Agent Registry רושם את הסוכן, אבל לא יכול לתעד באופן אוטומטי מטא-נתונים כמו כתובת ה-URL של נקודת הקצה (endpoint) שבה הסוכן מתארח, זהות הסוכן ומיומנויות A2A. אלה סוכנים שחושפים, לדוגמה, נקודות קצה רגילות של REST או gRPC. כדי לשייך יכולות לסוכנים שהם לא סוכן A2A, צריך להשתמש ברישום ידני או לרשום מיומנויות.

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

1. הגדרת Agent Registry.

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

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

רישום נציגים מ-Agent Runtime

אם אתם מפתחים ופורסים סוכנים באמצעות Agent Runtime ב-Gemini Enterprise Agent Platform, הרישום ב-Agent Registry מתבצע באופן אוטומטי.

בדוגמה הבאה מוסבר איך לפרוס ב-Agent Runtime נציג שמטמיע את פרוטוקול A2A. מידע נוסף זמין במאמר פריסת נציג.

# Create and deploy the agent
# This action automatically registers the agent in Agent Registry
remote_agent = client.agent_engines.create(
    agent=my_a2a_agent, # Your defined A2A object
    config={
        "display_name": "my-support-agent",
        "description": "An agent that handles support tickets.",
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

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

רישום סוכנים מובנים של Google

סוכנים מובְנים של Google, כמו סוכנים של Google Workspace ו-Gemini Enterprise, רשומים באופן אוטומטי ב-Agent Registry. לא צריך לבצע שום שלב של הגדרה או פריסה. הסוכנים האלה נקלטים וזמינים לגילוי במאגר שלכם.

רישום סוכנים מ-GKE

כדי לרשום סוכנים שנפרסו ב-Google Kubernetes Engine ‏ (GKE), צריך להוסיף למניפסט הפריסה את התוויות וההערות הנדרשות של Kubernetes. בדוגמה הבאה מוצג מניפסט של GKE שמגדיר Deployment של Kubernetes ו-Service של Kubernetes, שמוגדרים לרישום אוטומטי:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
  labels:
    # GKE takes this label and registers the agent to Agent Registry
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  selector:
    matchLabels:
      app: my-agent
  template:
    metadata:
      labels:
        app: my-agent
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
# Kubernetes Service for in-cluster network routing to the agent pod
apiVersion: v1
kind: Service
metadata:
  name: my-agent-service
  labels:
    app: my-agent
spec:
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: my-agent

מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud .

כדי להגדיר ולהחיל את מניפסט הפריסה:

1. ב-metadata.labels של המניפסט של Deployment, מוסיפים את התווית registry.gke.io/functional-type: "AGENT". התווית הזו מזהה את הפריסה כעומס עבודה של סוכן AI, ומורה לבקר של סביבת זמן הריצה של אשכול GKE לבדוק את עומס העבודה ולרשום את הסוכן ב-Agent Registry.

   הערה: GKE תומך גם בהערה apphub.cloud.google.com/functional-type: "AGENT" לצורך תאימות לדורות קודמים. עם זאת, צריך להשתמש בתווית registry.gke.io/functional-type: "AGENT" לפריסות של GKE.

2. ב-metadata.annotations של המניפסט של Deployment, מפעילים את הגילוי האוטומטי של מיומנויות ה-A2A של הנציג על ידי הוספת ההערה a2a-protocol.org/agent-card. בקר ההטמעה של GKE משתמש בהערה הזו כדי לשלוח שאילתה לכרטיס הסוכן של A2A.

3. בשדה spec.template.metadata.annotations של תבנית ה-Pod, מפעילים תקשורת מאומתת על ידי הגדרת Agent Identity עם ההערה iam.gke.io/spiffe-identity-type: agent-identity.

4. מחילים את מניפסט הפריסה על האשכול. מידע נוסף זמין במאמר פריסה ותזמור של סוכני AI.

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

רישום סוכנים מ-Cloud Run

אתם יכולים לרשום סוכנים באופן אוטומטי כשאתם פורסים אותם כשירותים או כמשימות של Cloud Run, על ידי ציון הדגלים --functional-type=agent ו---identity-type=agent-identity. הדגל --functional-type=agent מזהה את השירות או את המשימה ב-Cloud Run כסוכן AI, ולא כעומס עבודה רגיל בקונטיינר, ומורה ל-Cloud Run לרשום את הסוכן ב-Agent Registry. במהלך הרישום, Cloud Run מוסיף באופן אוטומטי את שם הסוכן ואת הסוג AGENT למרשם.

בעומסי עבודה שמוגדרים עם --functional-type=agent צריך לציין את הדגל --identity-type=agent-identity. פריסה עם כל סוג זהות אחר תגרום לשגיאה.

כדי להגדיר רישום אוטומטי בשירות או במשימה חדשים או קיימים של Cloud Run, קראו את המאמר הגדרת התכונות של Gemini Enterprise Agent Platform ל-Cloud Run. במאמר פריסת סוכני A2A ב-Cloud Run מוסבר איך להכין, להכיל בקונטיינר ולפרוס סוכן שתואם ל-A2A ב-Cloud Run.

אימות הרישום

כדי לוודא שהסוכנים נרשמו בהצלחה ב-Agent Registry, אפשר להציג אותם ברשימה:

המסוף

1. במסוף Google Cloud , נכנסים לדף Agent Registry:

   כניסה ל-Agent Registry

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

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

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

4. מסננים את הרשימה לפי המיקום של הסוכן או משאב זמן הריצה שלו:

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

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

gcloud

אפשר לסנן את הרשימה לפי המטא-נתונים של הנציג. מוודאים שהגדרתם את סביבת ה-CLI של gcloud ל-Agent Registry, ואז מריצים את הפקודה gcloud agent-registry agents list:

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

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

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

סוכנים מובְנים של Google משתמשים בפורמט של מזהה סוכן (URN) שתלוי במקום שבו הסוכן נפרס. לדוגמה, כדי למצוא סוכנים מובנים של Google Workspace, אתם יכולים לסנן את הרשימה לפי המפיץ googleapis.com באמצעות --filter="agentId:'urn:agent:googleapis.com:*'".

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