סכימות JSON

כשאתם רושמים באופן ידני סוכנים או שרתי Model Context Protocol‏ (MCP) ב-Agent Registry על ידי יצירת משאב Service, אתם מספקים קובצי תצורה בפורמט JSON שמצהירים על היכולות שלהם. לפני הוספת הקבצים לאינדקס, Agent Registry מאמת אותם לפי מפרטים של קוד פתוח, כדי שהמשתמשים יוכלו למצוא מיומנויות A2A וכלים של MCP לסוכנים. כדי להגדיר את הפורמט של Agent Cards ומפרטי הכלים של MCP, אתם יכולים להשתמש במבנים ובדוגמאות הבאים של JSON.

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

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

‫Agent Registry תומך בגרסאות 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 או בקשת הרשימה. גודל הקובץ המקסימלי של קובץ המפרט הזה הוא 10KB.

{
  "tools": [
    {
      "name": "string",
      "description": "string",
      "inputSchema": {
        "type": "object",
        "properties": {}
      },
      "annotations": {
        "title": "string",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      }
    }
  ]
}

הגדרות השדות

• ‫tools: מערך של כלים שהשרת מספק:

  • ‫name: המזהה הפרוגרמטי של הכלי.
  • ‫description: הסבר קריא לאנשים על מטרת הכלי.
  • ‫inputSchema: אובייקט סכימת JSON שמגדיר את הפרמטרים הצפויים לכלי.

  • ‫annotations: רמזים התנהגותיים שמנחים את סוכני התזמור איך להשתמש בכלי:

    • ‫title: שם קריא לאנשים של הכלי.
    • ‫readOnlyHint: אם הערך הוא true, הכלי רק מאחזר נתונים ולא משנה את הסביבה שלו. ברירת המחדל היא false.
    • ‫destructiveHint: אם הערך הוא true, הכלי מבצע פעולות שעשויות לגרום לשינויים קבועים. ברירת המחדל היא true.
    • ‫idempotentHint: אם true, קריאה חוזרת לכלי לא משפיעה יותר. ברירת המחדל היא false.
    • ‫openWorldHint: אם הערך הוא true, הכלי יוצר אינטראקציה עם מערכות חיצוניות. ברירת המחדל היא true.