סכימות JSON

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

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

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

סכימת כרטיס הסוכן

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

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

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

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

סכמה של כלי ה-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.