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

כלים של פרוטוקול A2A

פרוטוקול Agent-to-Agent‏ (A2A) הוא תקן פתוח להעברת הודעות שמאפשר לסוכני AI אוטונומיים לתקשר ולתאם משימות במערכות שונות.

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

איך A2A פועל

פרוטוקול A2A ב-CX Agent Studio פועל באמצעות מודל העברה.

מודל הקצאת הרשאות

במודל ההקצאה, הסוכן שמתחיל את השיחה ב-CX Agent Studio פועל כמתזמן הראשי ושומר על השליטה הכוללת בסשן:

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

דיאגרמת רצף של הענקת גישה מסוג A2A

תקשורת מבוססת-טקסט

כל התקשורת בין הסוכנים בפרוטוקול A2A מבוססת על טקסט:

אם משתמש קצה מקיים אינטראקציה עם נציג ראשי בערוץ קולי (כמו טלפוניה או WebRTC), הדיבור מומר קודם לטקסט.
הסוכן הראשי שולח את תמליל הטקסט והפרמטרים לסוכן המשנה המרוחק במטען ייעודי (payload) של בקשת HTTP.
הטמעות וסטרימינג של אודיו גולמי לא מועברים דרך ממשק הרשת A2A.

תמיכה במודליות

התמיכה במודאליות (טקסט לעומת קול) בפרוטוקול A2A תלויה בכיוון התקשורת:

סוכן מרוחק ל-CX Agent Studio: תומך רק במצב טקסט.
‫CX Agent Studio לסוכן מרוחק: לא משנה באיזה אופן מתקשרים עם CX Agent Studio, כלומר, בסשן של CX Agent Studio אפשר להשתמש בכל אופן נתמך כמו קול או טקסט, אבל הסוכן המרוחק מקבל רק טקסט.

חיוב

אם גם הסשן הראשי וגם הסשן המרוחק נמצאים ב-CX Agent Studio ובאותו פרויקט, תחויבו על סשן אחד.

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

אימות ובקרת גישה

דרישות האימות תלויות בכיוון התקשורת ובשירות היעד.

כיוון	יעד	מנגנון אימות	תפקיד IAM נדרש	תיאור
נכנסות (מחוץ ל-CX Agent Studio)	אפליקציית סוכן ב-CX Agent Studio	אסימון גישה מסוג OAuth 2.0	`roles/ces.client`	נדרש כדי שמתקשרים חיצוניים יוכלו להפעיל את נקודת הקצה הנכנסת של CX Agent Studio.
יוצא (מ-CX Agent Studio אל CX Agent Studio)	סוכן CX Agent Studio בפרויקט אחר	סוכן שירות	`roles/ces.client`	ההרשאה ניתנת לסוכן השירות של הפרויקט שמבצע את הקריאה בפרויקט היעד.
יוצא (מ-CX Agent Studio אל Cloud Run)	שירות Cloud Run	טוקן של מזהה של סוכן שירות	`roles/run.invoker`	ההרשאה ניתנת לסוכן השירות של הפרויקט שמבצע את הקריאה בשירות Cloud Run.
יוצאות (מ-CX Agent Studio אל Vertex AI)	Vertex AI Agent Engine	סוכן שירות OAuth	`roles/aiplatform.user`	ההרשאה ניתנת לסוכן השירות של הפרויקט שמבצע את הקריאה בפרויקט היעד.
מוביל לאתר אחר (מ-CX Agent Studio לצד שלישי)	נקודת קצה חיצונית (למשל ServiceNow או Salesforce)	מפתח API או OAuth	מנוהל באמצעות Secret Manager	פרטי הכניסה השמורים מוזרקים במהלך הפעלת הכלי.

הזהות של סוכן השירות

בקשות יוצאות מ-CX Agent Studio משתמשות בסוכן השירות של CX Agent Studio:

service-PROJECT_NUMBER@gcp-sa-ces.iam.gserviceaccount.com

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

אימות של שיחות נכנסות

כששולחים קריאה ל-CX Agent Studio מאפליקציה חיצונית, מסוכן מותאם אישית או מכלי תזמור, צריך להעביר אסימון גישה תקף מסוג OAuth 2.0 שהונפק על ידי Google בכותרת Authorization:

בדיקה: יוצרים אסימון גישה זמני לחשבון הפעיל:
```
gcloud auth print-access-token
```
לקוחות פרוגרמטיים: משתמשים ב-Application Default Credentials ‏ (ADC):
```
gcloud auth application-default print-access-token
```
סביבת ייצור: משתמשים בחשבון שירות ייעודי ב-Google עם התפקיד roles/ces.client (Customer Engagement Suite Client).

דרישות מוקדמות

לפני שמגדירים כלים של פרוטוקול A2A:

מפעילים את Gemini Enterprise for Customer Experience API ‏ (ces.googleapis.com) בפרויקט:
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
מוודאים שלחשבון המשתמש או לחשבון השירות שקוראים ל-API הוקצה התפקיד Customer Engagement Suite Client (roles/ces.client).

הגדרת כלי פרוטוקול A2A

כדי לקשר את הנציג הראשי לנציג חיצוני מרוחק:

פותחים את מסוף CX Agent Studio.
בוחרים את הפרויקט ופותחים את אפליקציית הסוכן.
בכלי ליצירת סוכנים, לוחצים על סמל הכלים.
לוחצים על הלחצן + (הוספה) כדי ליצור כלי חדש.
בוחרים את כרטיס הכלי פרוטוקול A2A.
מגדירים את כרטיס הנציג באמצעות טופס ממשק המשתמש או עורך JSON.
בשדה URL, מזינים את כתובת ה-URL של נקודת הקצה הבסיסית של הסוכן המרוחק (לדוגמה, https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID או כתובת ה-URL של שירות Cloud Run). אל תוסיפו את /message:send לכתובת ה-URL. מערכת CX Agent Studio מוסיפה את /message:send באופן אוטומטי בזמן הריצה.
בוחרים את סוג האימות המתאים לנקודת הקצה.
לוחצים על יצירה.

דוגמה לכרטיס של סוכן

קובץ ה-JSON לדוגמה הבא מגדיר כרטיס של סוכן למזג אוויר מרחוק:

{
  "name": "weather_agent",
  "description": "Agent capable of querying weather conditions and local time for given locations.",
  "version": "0.1.0",
  "supportedInterfaces": [
    {
      "url": "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "skills": [
    {
      "id": "get_weather",
      "name": "get_weather",
      "description": "Retrieves weather conditions for a specified location.",
      "tags": [
        "weather",
        "forecast"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    },
    {
      "id": "get_current_time",
      "name": "get_current_time",
      "description": "Retrieves current local time for a specified city or timezone.",
      "tags": [
        "time",
        "clock"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    }
  ]
}

הוספת הוראות ניתוב

צריך לתת לסוכן הראשי הוראות מתי להעביר משימות לכלי A2A. לדוגמה:

If the user asks for weather information or local time, use {@TOOL: weather_agent}.
Pass the city or location specified by the user.
If the tool returns an error, inform the user that weather details are temporarily unavailable.

הודעות נכנסות

מערכות חיצוניות יכולות לשלוח הודעות ישירות לאפליקציית נציג ב-CX Agent Studio באמצעות נקודת הקצה של הודעות A2A נכנסות.

כתובת ה-URL של נקודת הקצה הנכנסת

שליחת בקשות HTTP POST לנקודת הקצה הבאה:

https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send

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

‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
‫LOCATION: האזור שבו מתארח יישום הנציג (למשל us-central1).
‫APP_ID: המזהה הייחודי של אפליקציית הסוכן שלכם ב-CX Agent Studio.

סכימת המטען הייעודי (payload) של הבקשה

מבנה מטען ה-JSON הייעודי לשליחת הודעה נכנסת:

‫

{
  "message": {
    "messageId": "msg-MY_UNIQUE_MESSAGE_UUID",
    "role": "ROLE_USER",
    "content": [
      {
        "text": "Hello! I would like help checking my account balance."
      }
    ],
    "metadata": {
      "gecx_a2a_agent_context": "MY_SERIALIZED_AGENT_CONTEXT_STRING"
    }
  }
}

הערה: ב-CX Agent Studio, מטען הייעודי (payload) של ההודעה משתמש בשדה content כדי להכיל חלקי טקסט של ההודעה.

בקשה לדוגמה באמצעות curl

אפשר לבדוק הודעות נכנסות באמצעות curl:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "content": [
        {
          "text": "Hello!"
        }
      ]
    }
  }' \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send"

ניהול ההקשר והמצב

פרוטוקול A2A משתמש בהודעה AgentContext כדי לנהל משתנים ומצבי סשן בין סוכנים. ההקשר מועבר במטא-נתונים של SendMessageRequest באמצעות המפתח gecx_a2a_agent_context.

מיפוי משתנים

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

מיפוי דואר יוצא: RemoteAgentTool.input_variable_mapping מחשב את AgentContext.variables שנשלח לסוכן המרוחק.
מיפוי נכנס: RemoteAgentTool.output_variable_mapping מעדכן את המשתנים של הסוכן הראשי כשהסוכן המרוחק מגיב.

עבור בקשות נכנסות (מלקוח חיצוני אל CX Agent Studio), האפליקציה מבצעת דה-סריאליזציה של מטא-נתונים של gecx_a2a_agent_context וכותבת את AgentContext.variables ישירות לסשן הנוכחי. המשתנים המעודכנים נכתבים בחזרה אל AgentContext.variables כשמשיבים ללקוח.

סגירת הסשן

הסוכן הראשי עוקב אחרי AgentContext.session_metadata.closed כדי לקבוע מתי מסתיים סשן מרוחק:

בבקשות יוצאות, הערך של closed תמיד מוגדר כ-false. אם התשובה של הסוכן המרוחק מגדירה את closed ל-true, החיבור בין האפליקציות מסתיים.
בתשובות נכנסות שחוזרות ללקוח, אפליקציית CX Agent Studio מגדירה את closed ל-true אם הסשן הסתיים.

מצב עם שמירת נתונים

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

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

אפשר להפעיל את השדה RemoteAgentTool.stateful_agent כדי לשמור במטמון את מזהה ההקשר הראשון שמוחזר על ידי הסוכן המרוחק ולעשות בו שימוש חוזר.

מזהה ההקשר ששמור במטמון משמש למשך שאר הסשן, אלא אם הסוכן המרוחק מגיב עם AgentContext.session_metadata.closed == true. אם הסשן ייסגר, המטמון יאופס ומזהה הקשר החדש יישמר במטמון בקריאה הבאה לכלי.

פריסת סוכן משנה מרוחק

אתם יכולים לפרוס סוכנים מותאמים אישית מרחוק בשירותים Google Cloud כדי שיפעלו כסוכני משנה ב-CX Agent Studio.

פריסה ב-Cloud Run

כדי לארח סוכן שנוצר באמצעות הערכה לפיתוח סוכנים (ADK) ב-Cloud Run:

יוצרים קובץ Dockerfile בספריית הפרויקט של הסוכן:

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir "google-adk[a2a]==1.32.0" "a2a-sdk[all]==0.3.26"

COPY . .

ENV PORT=8080
ENV PYTHONUNBUFFERED=1

EXPOSE 8080

CMD ["python", "-m", "app.a2a_rest_server"]

פורסים את הקונטיינר ב-Cloud Run:

gcloud run deploy my-adk-agent \
  --project=PROJECT_ID \
  --region=us-central1 \
  --source=. \
  --memory=4Gi \
  --no-cpu-throttling

נותנים את התפקיד roles/run.invoker בשירות Cloud Run לסוכן השירות של פרויקט ההתקשרות ב-CX Agent Studio.
פועלים לפי השלבים שבקטע הגדרת כלי פרוטוקול A2A כדי לצרף את כתובת ה-URL של שירות Cloud Run ל-CX Agent Studio.

פריסה ל-Vertex AI Agent Engine

כדי לפרוס סוכן ADK ב-Vertex AI Agent Engine:

מגדירים את יחסי התלות ב-requirements.txt:
```
a2a-sdk==0.3.26
google-adk[a2a]>=1.15.0,<2.0.0
```

פריסת המנוע באמצעות Vertex AI SDK:

import os
import sys
from google.protobuf import json_format
import vertexai
from vertexai.agent_engines import _agent_engines

sys.path.append("./")
from app.agent_runtime_app import agent_runtime

client = vertexai.Client(project="PROJECT_ID", location="us-central1")

ops = agent_runtime.register_operations()
class_methods_proto = _agent_engines._generate_class_methods_spec_or_raise(
    agent_engine=agent_runtime,
    operations=ops
)
class_methods_list = [
    json_format.MessageToDict(cm, preserving_proto_field_name=True)
    for cm in class_methods_proto
]

agent_config = {
    "entrypoint_module": "app.agent_runtime_app",
    "entrypoint_object": "agent_runtime",
    "source_packages": ["app", "requirements.txt"],
    "requirements_file": "requirements.txt",
    "class_methods": class_methods_list,
    "agent_framework": "google-adk",
    "env_vars": {
        "GOOGLE_CLOUD_LOCATION": "us-central1",
    },
    "min_instances": 1,
    "max_instances": 10,
    "resource_limits": {"cpu": "4", "memory": "8Gi"},
}

engine = client.agent_engines.create(config=agent_config)
print(f"Deployed Engine Resource Name: {engine.api_resource.name}")

מקצים את התפקיד roles/aiplatform.user בפרויקט היעד לסוכן השירות של CX Agent Studio בפרויקט שממנו מתבצעת הקריאה.
פועלים לפי השלבים במאמר בנושא הגדרת כלי פרוטוקול A2A כדי לצרף את נקודת הקצה של Agent Engine ל-CX Agent Studio.

חיבור לנקודות קצה של צד שלישי

‫CX Agent Studio יכול להעביר משימות לנקודות קצה חיצוניות של צד שלישי, כמו ServiceNow או Salesforce.

כשמגדירים את הכלי במסוף:

פועלים לפי השלבים במאמר הגדרה של כלי פרוטוקול A2A.
בוחרים את שיטת האימות שנדרשת על ידי נקודת הקצה של הצד השלישי (למשל מפתח API או OAuth).
אחסון פרטי כניסה בצורה מאובטחת באמצעות Secret Manager.

השוואה בין כלים של פרוטוקול A2A לבין סוכן ככלי

ב-CX Agent Studio יש כמה שיטות לתיאום תהליכי עבודה עם כמה סוכנים.

התכונה	סוכן ככלי	כלי פרוטוקול A2A
היקף	בתוך האפליקציה (סוכנים באותה אפליקציה של CX Agent Studio).	בין אפליקציות (סוכנים חיצוניים, שירותים מרחוק או פלטפורמות של צד שלישי).
תקשורת	הרצה ישירה בזיכרון או פנימית.	בקשות HTTP ברשת באמצעות תקן ההודעות A2A.
תרחישי שימוש	שימוש חוזר בסוכני משנה פנימיים בלי להעביר את הסשן.	שליחת קריאות לסוכני ADK בהתאמה אישית ב-Cloud Run, ב-Vertex AI או בממשקי API חיצוניים.
פרוטוקול	הרצת כלי פנימי בפלטפורמה.	מטען ייעודי (payload) של JSON בתקן A2A דרך REST.

הרצה של כלי LLM

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

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

מידע נוסף על האופן שבו סוכנים מוצפנים ככלים שאפשר להפעיל זמין במאמר ADK AgentTool implementation ב-GitHub.

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

איך A2A פועל

מודל הקצאת הרשאות

תקשורת מבוססת-טקסט

תמיכה במודליות

חיוב

אימות ובקרת גישה

הזהות של סוכן השירות

אימות של שיחות נכנסות

דרישות מוקדמות

הגדרת כלי פרוטוקול A2A

דוגמה לכרטיס של סוכן

הוספת הוראות ניתוב

הודעות נכנסות

כתובת ה-URL של נקודת הקצה הנכנסת

סכימת המטען הייעודי (payload) של הבקשה

בקשה לדוגמה באמצעות curl

ניהול ההקשר והמצב

מיפוי משתנים

סגירת הסשן

מצב עם שמירת נתונים

פריסת סוכן משנה מרוחק

פריסה ב-Cloud Run

פריסה ל-Vertex AI Agent Engine

חיבור לנקודות קצה של צד שלישי

השוואה בין כלים של פרוטוקול A2A לבין סוכן ככלי

הרצה של כלי LLM

כלים של פרוטוקול A2A