כשרושמים באופן ידני סוכנים או שרתי Model Context Protocol (MCP) ב-Agent Registry על ידי יצירת משאב Service, צריך לספק קובצי תצורה בפורמט JSON שמצהירים על היכולות שלהם. כדי שמשתמשים יוכלו למצוא מיומנויות A2A וכלים של MCP של הנציג, Agent Registry מאמת את הקבצים האלה לפי מפרטים של קוד פתוח לפני הוספה שלהם לאינדקס. כדי לעצב את המפרטים של Agent Cards ושל כלי MCP, אתם יכולים להשתמש במבנים ובדוגמאות הבאים של JSON.
סכימת כרטיס הסוכן
כשרושמים סוכן שתואם ל-A2A, המטען הייעודי (payload) של agent-card.json צריך לעמוד בדרישות של המפרט הרשמי של Agent2Agent (A2A).
גודל הקובץ המקסימלי של קובץ המפרט הוא 150KB.
שדות המערך skills תומכים באינדקס החיפוש של מילות המפתח.
מרשם הסוכנים תומך בגרסאות 1.0 ו-0.3 של כרטיס הסוכן של A2A. בוחרים גרסה כדי לראות את סכימת ה-JSON ואת הגדרות השדות שלה:
גרסה 1.0 (מומלץ)
בגרסה 1.0 של כרטיסי סוכן A2A, המטען הייעודי (payload) חייב לעמוד במפרט הרשמי של גרסה 1.0 של A2A. במפרט הזה, אתם מצהירים על נקודות קצה (endpoint) של תעבורת נתונים במערך supportedInterfaces:
{
"name": "string",
"description": "string",
"version": "string",
"supportedInterfaces": [
{
"url": "string",
"protocolBinding": "string",
"protocolVersion": "string",
"tenant": "string"
}
],
"capabilities": {
"streaming": false,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
],
"skills": [
{
"id": "string",
"name": "string",
"description": "string",
"tags": [
"string"
],
"examples": [
"string"
]
}
]
}
הגדרות השדות
-
name: השם הקריא לאנשים של הנציג. -
description: סיכום כללי של מטרת הנציג. -
version: גרסת הסוכן, לדוגמה1.0.0. -
supportedInterfaces: מערך של שילובים נתמכים של כתובות URL ופרוטוקולי העברה. כל ממשק מכיל את הפרטים הבאים:-
url: כתובת ה-URL של נקודת הקצה שבה נמצא הממשק הזה. -
protocolBinding: הקישור לפרוטוקול שנתמך בכתובת ה-URL הזו, לדוגמה,HTTP+JSON,JSONRPCאוGRPC. -
protocolVersion: גרסת פרוטוקול A2A שהממשק הזה חושף, לדוגמה1.0.0. -
tenant(אופציונלי): המזהה של בעלי הנציג.
-
-
capabilities(אופציונלי): מציין יכולות תפעוליות נתמכות, כמו:-
extensions(אופציונלי): מערך של תוספי פרוטוקול. -
streaming(אופציונלי): ערך בוליאני שמציין אם הנציג תומך בתשובות בסטרימינג. -
pushNotifications(אופציונלי): ערך בוליאני שמציין אם יש תמיכה בהתראות לגבי עדכוני משימות. extendedAgentCard(אופציונלי): ערך בוליאני שמציין אם הנציג מספק כרטיס נציג מורחב אחרי אימות.
-
-
defaultInputModes(אופציונלי): מערך של סוגי MIME שמתקבלים כקלט. -
defaultOutputModes(אופציונלי): מערך של סוגי MIME שנוצרו כפלט. -
skills: מערך של מיומנויות A2A תיאוריות שיש לסוכן:-
id: מזהה פרוגרמטי ייחודי של מיומנות ה-A2A. -
name: שם קריא לאנשים של המיומנות של A2A. -
description: הסבר מפורט על מה שהמיומנות של A2A עושה. -
tags: מערך של מחרוזות של מילות מפתח שמשמשות לסיווג המיומנות של A2A. -
examples: מערך של הנחיות או תרחישים לדוגמה שהמיומנות הזו של A2A מטפלת בהם.
-
גרסה 0.3
בגרסה 0.3 של כרטיסי סוכן A2A, המטען הייעודי (payload) חייב לעמוד במפרט של גרסה 0.3.0. במפרט הזה, כתובת ה-URL הראשית להסקת מסקנות וגרסת הפרוטוקול מוצהרות כשדות ברמה העליונה:
{
"name": "string",
"description": "string",
"version": "string",
"protocolVersion": "string",
"url": "string",
"skills": [
{
"id": "string",
"name": "string",
"description": "string",
"tags": [
"string"
],
"examples": [
"string"
]
}
],
"capabilities": {
"streaming": false,
"pushNotifications": false,
"stateTransitionHistory": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
]
}
הגדרות השדות
-
name: השם הקריא לאנשים של הנציג. -
description: סיכום כללי של מטרת הנציג. -
version: גרסת הסוכן, לדוגמה1.0.2. -
protocolVersion: גרסת פרוטוקול A2A שהסוכן מטמיע. בגרסה1.0השדה הזה ברמה העליונה הוצא משימוש, ולכן הערך של הסכימה הזו חייב להיות0.3או כל גרסת תיקון של0.3, כמו0.3.1. -
url: כתובת ה-URL של נקודת הקצה שבה אפשר להגיע לנציג. -
capabilities(אופציונלי): אובייקט שמציין את היכולות התפעוליות שהנציג תומך בהן, כמוstreaming,pushNotificationsאוstateTransitionHistory. -
defaultInputModes(אופציונלי): מערך של מחרוזות שמגדיר את סוגי ה-MIME שמוגדרים כברירת מחדל שהנציג מקבל כקלט, לדוגמה,["text/plain"]. -
defaultOutputModes(אופציונלי): מערך של מחרוזות שמגדירות את סוגי ה-MIME שמוגדרים כברירת מחדל שהסוכן יוצר כפלט, לדוגמה,["text/plain"]. -
skills: מערך של מיומנויות A2A תיאוריות שיש לסוכן:-
id: מזהה פרוגרמטי ייחודי של מיומנות ה-A2A. -
name: שם קריא לאנשים של המיומנות של A2A. -
description: הסבר מפורט על מה שהמיומנות של A2A עושה. -
tags: מערך של מחרוזות של מילות מפתח שמשמשות לסיווג המיומנות של A2A. -
examples: מערך של הנחיות או תרחישים לדוגמה שהמיומנות הזו של A2A מטפלת בהם.
-
סכימה של כלי MCP
כשרושמים שרת MCP, המטען הייעודי (payload) של toolspec.json צריך לכלול רשימה של כלים שתואמים לסכימת האובייקטים של Tool ב-MCP.
המטען הייעודי (payload) הצפוי הוא אובייקט JSON עם שדה tools יחיד, בדיוק כמו שהוא מוחזר על ידי הכלים הרגילים של MCP או בקשת הרשימה.
גודל הקובץ המקסימלי של קובץ המפרט הזה הוא 150KB.
{
"tools": [
{
"name": "string",
"description": "string",
"inputSchema": {
"type": "object",
"properties": {}
},
"annotations": {
"title": "string",
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": true
},
"_meta": {
"com.googleapis.iap/PolicyHints": {
"authorization": {
"toolDisabled": false,
"hitlMode": "HITL_MODE_ALWAYS"
}
}
}
}
]
}
הגדרות השדות
tools: מערך של כלים שהשרת מספק:-
name: המזהה הפרוגרמטי של הכלי. -
description: הסבר קריא לאנשים על מטרת הכלי. -
inputSchema: אובייקט סכימת JSON שמגדיר את הפרמטרים הצפויים לכלי.
annotations: רמזים התנהגותיים שמנחים את סוכני התזמור איך להשתמש בכלי:-
title: שם קריא לאנשים של הכלי. -
readOnlyHint: אםtrue, הכלי רק מאחזר נתונים ולא משנה את הסביבה שלו. ברירת המחדל היאfalse. -
destructiveHint: אם הערך הואtrue, הכלי מבצע פעולות שעשויות לגרום לשינויים באופן סופי. ברירת המחדל היאtrue. -
idempotentHint: אםtrue, לקריאה חוזרת לכלי אין השפעה נוספת. ברירת המחדל היאfalse. -
openWorldHint: אם הערך הואtrue, הכלי יוצר אינטראקציה עם מערכות חיצוניות. ברירת המחדל היאtrue.
-
_meta(אופציונלי): מטא-נתונים ברמת הפרוטוקול שתואמים למפרט של Model Context Protocol (MCP) לצירוף מטא-נתונים מובְנים לכלים. מכיוון שה-annotationsהרגיל הוא אובייקט סגור שמוגבל לרמזים מוגדרים מראש,_metaמספק מאגר שניתן להרחבה למטא-נתונים נוספים, תוך שמירה על תאימות עם לקוחות MCP רגילים.כדי למנוע התנגשויות בין שמות של ספקים שונים, המפתחות ברמה העליונה ב-
_metaמשתמשים בסימון דומיין הפוך. מרשם הסוכנים מאמת את_metaמול סכימת המטא-נתונים המורחבת שלapphub.googleapis.com/McpServer, ותומך במרחב השמות הבא:
com.googleapis.iap/PolicyHints(אופציונלי): רמזים למדיניות שנבדקים על ידי שרת proxy לאימות זהויות (IAP) ו-Agent Gateway כדי לאכוף את ההרשאות של הכלי ואת אמצעי הבקרה של האדם שבתהליך (HITL):-
authorization(אופציונלי): הגדרת ההרשאה לכלי:-
toolDisabled(אופציונלי): ערך בוליאני שמציין אם הכלי מושבת להפעלה. כדי להשבית את הכלי, צריך להגדיר את הערךtrue. ערך ברירת המחדל הואfalse, כלומר הכלי מופעל אם משמיטים את השדה הזה. -
hitlMode(אופציונלי): מחרוזת שמציינת את מצב ההפעלה של הכלי עם האדם שבתהליך (HITL):-
HITL_MODE_UNSPECIFIED: מצב ה-HITL לא צוין. -
HITL_MODE_DISABLED: הכלי פועל בלי צורך באישור אינטראקטיבי של בן אדם. -
HITL_MODE_ALWAYS: הכלי תמיד דורש אישור אנושי אינטראקטיבי לפני ההפעלה. -
HITL_MODE_IF_UNSAFE: הכלי דורש אישור אנושי אינטראקטיבי רק כשהפעולה מוערכת כלא בטוחה.
-
-
-
-