שימוש ברישום אוטומטי

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

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

המטא-נתונים והיכולות של סוכנים (A2A) שחולצו מסוכן במהלך הרישום שלו תלויים בפרוטוקול של הסוכן. מידע נוסף זמין במאמר בנושא רישום סוכנים.

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

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

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

רישום סוכנים מ-Agent Runtime

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

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

# 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, נרשמים אוטומטית במרשם הסוכנים. לא צריך לבצע שום שלבי הגדרה או פריסה. הסוכנים האלה נקלטים וזמינים לגילוי במאגר שלכם.

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

אפשר לרשום סוכנים שנפרסו ב-Google Kubernetes Engine ‏ (GKE) על ידי הוספת התווית registry.gke.io/functional-type: "AGENT" לפריסות. התווית הזו מזהה את הפריסה כסוכן AI, ומאפשרת ל-Agent Registry לבצע סריקת אינטרוספקציה.

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

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

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

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
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
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

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

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

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

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

אפשר לפרוס סוכנים כשירותים או כמשימות ב-Cloud Run. במאמר הגדרת תכונות של Agent Platform ל-Cloud Run מוסבר איך פורסים סוכן כשירות או כמשימה ב-Cloud Run.

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

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

אימות הרישום

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

המסוף

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

   כניסה ל-Agent Registry

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

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

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

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

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

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

gcloud

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

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 שתלוי במיקום הפריסה של הסוכן. לדוגמה, אפשר לסנן את הרשימה לפי המפרסם googleapis.com באמצעות --filter="agentId:'urn:agent:googleapis.com:*'" כדי למצוא סוכנים מובנים של Google Workspace.

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