סכימות מטא-נתונים מורחבות

‫App Hub מוסיף באופן אוטומטי מטא-נתונים מורחבים לחלק מהשירותים ועומסי העבודה כדי לשפר את יכולת הגילוי, את הפיקוח ואת השילוב עם מערכות אחרות. מפתח ייחודי מזהה כל סכימה נתמכת ומגדיר את המבנה והשדות של סוג ספציפי של מטא-נתונים. כדי לראות את המטא-נתונים האלה, עיינו במאמר הצגת סכימות של מטא-נתונים מורחבים.

apphub.googleapis.com/AgentProperties

הסכימה הזו משמשת לתיאור המאפיינים של סוכן AI, ומאפשרת למערכות אחרות למצוא ולהבין אותו. בדרך כלל, המדיניות הזו חלה על עומסי עבודה עם מאפיין של סוג פונקציונלי AGENT. הסכימה תואמת לכרטיס הסוכן של Agent2Agent‏ (A2A).

הגדרת הסכימה

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

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "apphub.googleapis.com/AgentProperties",
  "description": "The schema for apphub.googleapis.com/AgentProperties. Except for framework, the properties are derived from the A2A Agent Card.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "displayName": {
      "type": "string",
      "description": "The display name of the agent."
    },
    "description": {
      "type": "string",
      "description": "The description of the agent."
    },
    "version": {
      "type": "string",
      "description": "Contains the version of the Agent."
    },
    "framework": {
      "type": "string",
      "description": "The agent framework used to develop the agent."
    },
    "agentCardUri": {
      "type": "string",
      "description": "The URI of the agent card for the agent."
    },
    "skills": {
      "type": "array",
      "description": "A list of skills the agent possesses.",
      "items": {
        "type": "object",
        "title": "Skills",
        "description": "Defines a skill for an agent.",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "A unique identifier for the agent's skill."
          },
          "name": {
            "type": "string",
            "description": "A human readable name for the agent's skill."
          },
          "description": {
            "type": "string",
            "description": "A description of the agent's skill."
          },
          "tags": {
            "type": "array",
            "description": "A set of keywords describing the skill's capabilities.",
            "items": {
              "type": "string"
            }
          },
          "examples": {
            "type": "array",
            "description": "Example prompts or scenarios that this skill can handle.",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

תיאורי השדות

שדה סוג תיאור
displayName string השם המוצג של הנציג.
description string תיאור הנציג.
version string גרסת הנציג.
framework string המסגרת ששימשה לפיתוח הנציג.
agentCardUri string ה-URI של כרטיס הסוכן.
skills array רשימת הסקילים של הסוכן.
skills.id string מזהה ייחודי של המיומנות של הנציג.
skills.name string שם קריא לאנשים של המיומנות של הנציג.
skills.description string תיאור של המיומנות של הסוכן.
skills.tags array מתוך string קבוצה של מילות מפתח שמתארות את היכולות של המיומנות.
skills.examples array מתוך string הנחיות או תרחישים לדוגמה שהמיומנות הזו יכולה לטפל בהם.

apphub.googleapis.com/McpServer

הסכימה apphub.googleapis.com/McpServer מגדירה את המאפיינים של שרת Model Context Protocol‏ (MCP) ואת הכלים שהוא חושף. ‫App Hub מחיל את הסכימה הזו על שירותים שהמאפיין של סוג הפונקציה שלהם הוא MCP_SERVER. הסכימה כוללת הצהרות על נקודות קצה של העברה והגדרות של כלים שתואמות למפרט של MCP, כולל רמזים לגבי התנהגות ב-annotations ורמזים לגבי מדיניות ב-_meta.

הגדרת הסכימה

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

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "apphub.googleapis.com/McpServer",
  "description": "The schema for apphub.googleapis.com/McpServer.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "displayName": {
      "type": "string",
      "description": "The display name of the MCP Server."
    },
    "description": {
      "type": "string",
      "description": "The description of the MCP Server."
    },
    "interfaces": {
      "type": "array",
      "description": "The connection details for the MCP Server.",
      "items": {
        "$ref": "#/definitions/Interface"
      }
    },
    "tools": {
      "type": "array",
      "description": "Tools provided by the MCP Server.",
      "items": {
        "$ref": "#/definitions/Tool"
      }
    }
  },
  "required": ["interfaces"],
  "definitions": {
    "Tool": {
      "description": "Represents a single tool provided by an MCP Server.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Human-readable name of the tool."
        },
        "description": {
          "type": "string",
          "description": "Description of what the tool does."
        },
        "annotations": {
          "$ref": "#/definitions/Tool.Annotations",
          "description": "Annotations associated with the tool."
        },
        "_meta": {
          "$ref": "#/definitions/Tool.Meta",
          "description": "Protocol-level metadata conforming to MCP _meta."
        }
      }
    },
    "Tool.Annotations": {
      "description": "Annotations describing the characteristics and behavior of a tool or operation.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "title": {
          "type": "string",
          "description": "A human-readable title or name for the tool or operation."
        },
        "destructiveHint": {
          "type": "boolean",
          "description": "Hint indicating if the operation can cause destructive changes."
        },
        "idempotentHint": {
          "type": "boolean",
          "description": "Hint indicating if the operation is idempotent (safe to retry)."
        },
        "openWorldHint": {
          "type": "boolean",
          "description": "Hint indicating if the operation assumes an open world."
        },
        "readOnlyHint": {
          "type": "boolean",
          "description": "Hint indicating if the operation is read-only."
        }
      }
    },
    "Tool.Meta": {
      "type": "object",
      "description": "Protocol-level tool metadata container conforming to MCP _meta.",
      "additionalProperties": false,
      "properties": {
        "com.googleapis.iap/PolicyHints": {
          "$ref": "#/definitions/Iap.PolicyHints",
          "description": "IAP specific policy hints."
        }
      }
    },
    "Iap.PolicyHints": {
      "type": "object",
      "description": "IAP custom extensions to MCP policy hints.",
      "additionalProperties": false,
      "properties": {
        "authorization": {
          "$ref": "#/definitions/Iap.Authorization",
          "description": "Authorization configurations for the tool."
        }
      }
    },
    "Iap.Authorization": {
      "type": "object",
      "description": "Authorization configuration including Human-in-the-loop (HITL) settings.",
      "additionalProperties": false,
      "properties": {
        "toolDisabled": {
          "type": "boolean",
          "description": "Indicates if the tool is disabled. Defaults to false when absent, which means the tool is enabled."
        },
        "hitlMode": {
          "type": "string",
          "description": "Human-in-the-loop (HITL) execution mode.",
          "enum": [
            "HITL_MODE_UNSPECIFIED",
            "HITL_MODE_DISABLED",
            "HITL_MODE_ALWAYS",
            "HITL_MODE_IF_UNSAFE"
          ]
        }
      }
    },
    "Interface": {
      "description": "Represents interface.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "url": {
          "type": "string",
          "description": "The destination URL.",
          "pattern": "^https?://"
        },
        "protocolBinding": {
          "type": "string",
          "description": "The protocol binding of the interface.",
          "enum": [
            "JSONRPC"
          ]
        }
      },
      "required": ["url", "protocolBinding"]
    }
  }
}

תיאורי השדות

שדה סוג תיאור
displayName string השם המוצג של שרת ה-MCP.
description string תיאור שרת ה-MCP.
interfaces array פרטי החיבור לשרת ה-MCP.
interfaces.url string כתובת ה-URL של נקודת הקצה (endpoint) של היעד בממשק.
interfaces.protocolBinding string הקישור לפרוטוקול של הממשק, לדוגמה JSONRPC.
tools array כלים שסופקו על ידי שרת ה-MCP.
tools.name string שם הכלי, בפורמט שקריא לאנשים.
tools.description string תיאור של מה שהכלי עושה.
tools.annotations object הערות MCP רגילות שמשויכות לכלי.
tools.annotations.title string שם קריא לאנשים של הכלי.
tools.annotations.readOnlyHint boolean רמז שמציין אם הכלי רק מאחזר נתונים ולא משנה את הסביבה שלו.
tools.annotations.destructiveHint boolean רמז שמציין אם הפעולה יכולה לגרום לשינויים הרסניים.
tools.annotations.idempotentHint boolean רמז שמציין אם הפעולה היא אידמפוטנטית ואפשר לבצע ניסיון חוזר שלה באופן בטוח.
tools.annotations.openWorldHint boolean רמז שמציין אם הפעולה מקיימת אינטראקציה עם מערכות חיצוניות.
tools._meta object מטא-נתונים ברמת הפרוטוקול שתואמים למפרט _meta של MCP. המפתחות חייבים להיות בפורמט של סימון דומיין הפוך.
tools._meta.com.googleapis.iap/PolicyHints object הצעות למדיניות של שרת proxy לאימות זהויות (IAP) לכלי.
tools._meta.com.googleapis.iap/PolicyHints.authorization object הגדרת הרשאה והאדם שבתהליך (HITL) לכלי.
tools._meta.com.googleapis.iap/PolicyHints.authorization.toolDisabled boolean מציין אם הכלי מושבת להפעלה. צריך להגדיר את הערך true כדי להשבית את הכלי. אם לא מציינים את הפרמטר, ערך ברירת המחדל הוא false, כלומר הכלי מופעל.
tools._meta.com.googleapis.iap/PolicyHints.authorization.hitlMode string מצב הרצה של "האדם שבתהליך" (HITL). הערכים הנתמכים הם HITL_MODE_UNSPECIFIED,‏ HITL_MODE_DISABLED, HITL_MODE_ALWAYS ו- HITL_MODE_IF_UNSAFE.

discoveryengine.googleapis.com/agentregistry/connector

הסכימה discoveryengine.googleapis.com/agentregistry/connector מגדירה את המטא-נתונים של הספק למחברי הנתונים של Gemini Enterprise. כשרושמים שרת Model Context Protocol‏ (MCP) חיצוני באמצעות מחבר Gemini Enterprise, ‏ App Hub מצרף את המטא-נתונים המורחבים האלה למשאב השירות הבסיסי.

Agent Registry מציג את המטא-נתונים האלה במפה attributes של משאב הגילוי McpServer המתאים, כדי שאפליקציות לקוח וסוכני תזמור יוכלו לבדוק את מאפייני המחבר, כמו type,‏ state ו-instanceUri.

הגדרת הסכימה

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

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "discoveryengine.googleapis.com/agentregistry/connector",
  "description": "Gemini Enterprise (Discovery Engine) connector metadata. Present on the McpServer of a resource backed by a Gemini Enterprise connector. Every field is optional.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "description": "The type of the Gemini Enterprise connector, as a lowercase hyphen-separated identifier: for example 'github', 'atlassian-rovo'. Instances of the same connector share a type; it identifies which external service the connector integrates with.",
      "maxLength": 128
    },
    "version": {
      "type": "string",
      "description": "The version of the connector definition this instance was created from, for example '1.0'.",
      "maxLength": 32
    },
    "state": {
      "type": "string",
      "description": "The provisioning state of the connector instance. Some possible values are: 'STATE_UNSPECIFIED', 'INITIALIZING', 'INITIALIZED', 'INITIALIZATION_FAILED', 'ACTIVE', 'RUNNING', 'FAILED', 'WARNING', 'UPDATING' or 'DELETING'.",
      "maxLength": 64
    },
    "instanceUri": {
      "type": "string",
      "description": "The customer's own site, for connectors addressed per customer: for example 'https://acme.atlassian.net'. This is the tenant the connector reads from, and differs from the MCP endpoint in 'interfaces', which is the same for every customer of a given connector. Absent for connectors that address a single fixed endpoint.",
      "maxLength": 512
    },
    "tenantId": {
      "type": "string",
      "description": "The identifier of the customer tenant within the external service, where the service requires one to address it.",
      "maxLength": 128
    },
    "skills": {
      "type": "array",
      "description": "The Agent Registry skill revisions a Gemini Enterprise administrator added to this custom MCP connector, one entry per skill, at most five. Absent for other connectors and for custom MCP connectors without any.",
      "maxItems": 5,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "skill": {
            "type": "string",
            "description": "The resource name of the skill, in the form 'projects/{project_number}/locations/{location}/skills/{skill}'.",
            "minLength": 1,
            "maxLength": 1024
          },
          "skillUid": {
            "type": "string",
            "description": "The 'uid' of the skill.",
            "minLength": 1,
            "maxLength": 128
          },
          "revision": {
            "type": "string",
            "description": "The resource name of the skill revision, in the form 'projects/{project_number}/locations/{location}/skills/{skill}/revisions/{revision}'.",
            "minLength": 1,
            "maxLength": 1024
          },
          "revisionUid": {
            "type": "string",
            "description": "The 'uid' of the skill revision.",
            "minLength": 1,
            "maxLength": 128
          },
          "sha256": {
            "type": "string",
            "description": "The SHA-256 digest of the skill revision's payload, as 64 lowercase hexadecimal characters.",
            "pattern": "^[0-9a-f]{64}$"
          }
        },
        "required": ["skill", "skillUid", "revision", "revisionUid", "sha256"]
      }
    }
  }
}

תיאורי השדות

שדה סוג תיאור
type string סוג המחבר של Gemini Enterprise, כמזהה באותיות קטנות שמופרד במקפים.
version string הגרסה של הגדרת המחבר שממנה נוצר המופע הזה.
state string מצב ההקצאה של המכונה של המחבר.
instanceUri string כתובת ה-URL של אתר הלקוח למחברים שמופנים לכל דייר.
tenantId string המזהה של דייר הלקוח בשירות החיצוני.
skills array גרסאות המיומנויות של Agent Registry שמצורפות למחבר MCP מותאם אישית, עד חמישה פריטים. השדה הזה מושמט במחברים אחרים ובמחברי MCP בהתאמה אישית שלא מצורפים אליהם סקילים.
skills.skill string שם המשאב של המיומנות, בפורמט projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL.
skills.skillUid string המזהה הייחודי (uid) של המיומנות.
skills.revision string שם המשאב של גרסת המיומנות, בפורמט projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL/revisions/REVISION.
skills.revisionUid string המזהה הייחודי (uid) של גרסת המיומנות.
skills.sha256 string תמצית SHA-256 של המטען הייעודי (payload) של גרסת הסקיל, ב-64 תווים הקסדצימליים באותיות קטנות.