扩展的元数据架构

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 接口的目标端点网址。
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 连接器的类型,采用小写连字符分隔的标识符。
version string 创建此实例所依据的连接器定义版本。
state string 连接器实例的预配状态。
instanceUri string 按租户寻址的连接器的客户网站网址。
tenantId string 外部服务中客户租户的标识符。
skills array 附加到自定义 MCP 连接器的 Agent Registry skill 修订版本,最多五个条目。对于其他连接器以及未附加 skill 的自定义 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 摘要,由 64 个小写十六进制字符组成。