סכימות JSON

כשרושמים סוכנים או שרתים של Model Context Protocol‏ (MCP) באופן מפורש ב-Agent Registry באמצעות ממשקי Services API, צריך לספק קובצי הגדרה שמתארים את היכולות שלהם.

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

במסמך הזה מובאות דוגמאות וקישורים למבני ה-JSON הצפויים של כרטיסי נציג ומפרטים של כלי ה-MCP.

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

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

Agent Registry תומך בגרסאות 0.3 ו-1.0 של כרטיס הסוכן A2A.

סכימה בגרסה 1.0 (מומלץ)

בגרסה 1.0 של כרטיסי סוכן A2A, מטען הייעודי (payload) צריך לעמוד בדרישות של מפרט v1.0 הרשמי של A2A. במפרט הזה, אתם מצהירים על נקודות קצה של התעבורה במערך 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"
      ]
    }
  ]
}

הגדרות השדות (גרסה 1.0)

• ‫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: מערך של יכולות שיש לסוכן:
  • ‫id: מזהה ייחודי של המיומנות שנוצר באופן פרוגרמטי.
  • ‫name: שם קריא לאנשים של המיומנות.
  • ‫description: הסבר מפורט על מה שהמיומנות עושה.
  • ‫tags: מערך של מחרוזות מילות מפתח שמשמשות לסיווג המיומנות.
  • ‫examples: מערך של הנחיות או תרחישים לדוגמה.

סכימה גרסה 0.3

בגרסה 0.3 של כרטיסי סוכן A2A, מטען הייעוד חייב לעמוד בדרישות המפרט v0.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"
  ]
}

הגדרות השדות (גרסה 0.3)

• ‫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 skill.
  • name: שם קריא לאנשים של מיומנות A2A.
  • ‫description: הסבר מפורט על מה שמיומנות ה-A2A עושה.
  • ‫tags: מערך של מחרוזות מילות מפתח שמשמשות לסיווג של מיומנות A2A.
  • ‫examples: מערך של הנחיות או תרחישים לדוגמה שהמיומנות הזו של A2A מטפלת בהם.

סכימת כלי ה-MCP

כשרושמים שרת MCP, מטען הנתונים toolspec.json צריך לכלול רשימה של כלים שתואמים לסכימת האובייקט של MCP Tool.

המטען הייעודי (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 Schema שמגדיר את הפרמטרים הצפויים של הכלי.

  • ‫annotations: רמזים התנהגותיים שמנחים את סוכני כלי התזמור לגבי אופן האינטראקציה עם הכלי:

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