擴充中繼資料結構定義

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 代理技能的專屬 ID。
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 介面的目的地端點網址。
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 符合 MCP _meta 規格的通訊協定層級中繼資料。鍵必須採用反向網域標記法。
tools._meta.com.googleapis.iap/PolicyHints object 工具的 Identity-Aware 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 資料連接器的供應商中繼資料。透過 Gemini Enterprise 連接器註冊外部 Model Context Protocol (MCP) 伺服器時,App Hub 會將這項擴充中繼資料附加至基礎服務資源。

Agent Registry 會在對應 McpServer 探索資源的 attributes 對應中顯示這項中繼資料,讓用戶端應用程式和自動化調度管理代理程式可以檢查連接器屬性,例如 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 連接器的類型,以小寫連字號分隔的 ID 表示。
version string 建立這個執行個體時使用的連接器定義版本。
state string 連接器執行個體的佈建狀態。
instanceUri string 連接器的客戶網站網址 (按租戶定址)。
tenantId string 外部服務中客戶租戶的 ID。
skills array 附加至自訂 MCP 連接器的 Agent Registry 技能修訂版本,最多五個項目。如果是其他連接器和未附加技能的自訂 MCP 連接器,則會省略。
skills.skill string 技能的資源名稱,格式為 projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL。
skills.skillUid string 技能的專屬 ID (uid)。
skills.revision string 技能修訂版本的資源名稱,格式為 projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL/revisions/REVISION。
skills.revisionUid string 技能修訂版本的專屬 ID (uid)。
skills.sha256 string 技能修訂版本酬載的 SHA-256 摘要,以 64 個小寫十六進位字元表示。