Esquemas de metadatos extendidos

El concentrador de aplicaciones agrega automáticamente metadatos extendidos a algunos servicios y cargas de trabajo para mejorar la visibilidad, la administración y la integración con otros sistemas. Una clave única identifica cada esquema compatible y define la estructura y los campos para un tipo específico de metadatos. Para ver estos metadatos, consulta Visualiza esquemas de metadatos extendidos.

apphub.googleapis.com/AgentProperties

Este esquema se usa para describir las propiedades de un agente de IA, lo que permite que otros sistemas lo encuentren y lo comprendan. Por lo general, se aplica a las cargas de trabajo que tienen una propiedad de tipo funcional de AGENT. El esquema es compatible con la tarjeta de agente de Agent2Agent (A2A).

Definición de esquema

A continuación, se muestra el esquema de este tipo de metadatos en formato 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"
            }
          }
        }
      }
    }
  }
}

Descripciones de los campos

Campo Tipo Descripción
displayName string Es el nombre visible del agente.
description string La descripción del agente.
version string Es la versión del agente.
framework string Es el framework que se usa para desarrollar el agente.
agentCardUri string Es el URI de la tarjeta del agente.
skills array Es una lista de las habilidades que posee el agente.
skills.id string Es un identificador único para la habilidad del agente.
skills.name string Es un nombre legible por humanos para la habilidad del agente.
skills.description string Es una descripción de la habilidad del agente.
skills.tags array de string Un conjunto de palabras clave que describen las capacidades de la habilidad.
skills.examples array de string Instrucciones o situaciones de ejemplo que esta habilidad puede controlar.

apphub.googleapis.com/McpServer

El esquema apphub.googleapis.com/McpServer define las propiedades de un servidor de Protocolo de contexto del modelo (MCP) y las herramientas que expone. App Hub aplica este esquema a los servicios que tienen una propiedad de tipo funcional de MCP_SERVER. El esquema incluye declaraciones de extremos de transporte y definiciones de herramientas que cumplen con la especificación de MCP, incluidas las sugerencias de comportamiento en annotations y las sugerencias de políticas en _meta.

Definición de esquema

A continuación, se muestra el esquema de este tipo de metadatos en formato 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"]
    }
  }
}

Descripciones de los campos

Campo Tipo Descripción
displayName string Es el nombre visible del servidor de MCP.
description string La descripción del servidor de MCP.
interfaces array Son los detalles de conexión del servidor de MCP.
interfaces.url string Es la URL del extremo de destino de la interfaz.
interfaces.protocolBinding string Es la vinculación de protocolo de la interfaz, por ejemplo, JSONRPC.
tools array Herramientas que proporciona el servidor de MCP.
tools.name string Es el nombre de la herramienta legible por humanos.
tools.description string Descripción de lo que hace la herramienta.
tools.annotations object Son las anotaciones estándar de MCP asociadas con la herramienta.
tools.annotations.title string Es un título legible por humanos para la herramienta.
tools.annotations.readOnlyHint boolean Sugerencia que indica si la herramienta solo recupera datos y no modifica su entorno.
tools.annotations.destructiveHint boolean Sugerencia que indica si la operación puede causar cambios destructivos.
tools.annotations.idempotentHint boolean Sugerencia que indica si la operación es idempotente y segura para reintentar.
tools.annotations.openWorldHint boolean Sugerencia que indica si la operación interactúa con sistemas externos.
tools._meta object Son metadatos a nivel del protocolo que cumplen con la especificación de _meta del MCP. Las claves deben seguir la notación de dominio inverso.
tools._meta.com.googleapis.iap/PolicyHints object Sugerencias de políticas de Identity-Aware Proxy (IAP) para la herramienta.
tools._meta.com.googleapis.iap/PolicyHints.authorization object Configuración de autorización y de intervención humana (HITL) para la herramienta.
tools._meta.com.googleapis.iap/PolicyHints.authorization.toolDisabled boolean Indica si la herramienta está inhabilitada para la invocación. Configúrala como true para inhabilitar la herramienta. El valor predeterminado es false cuando se omite, lo que significa que la herramienta está habilitada.
tools._meta.com.googleapis.iap/PolicyHints.authorization.hitlMode string Es el modo de ejecución con intervención humana (HITL). Los valores admitidos son HITL_MODE_UNSPECIFIED, HITL_MODE_DISABLED, HITL_MODE_ALWAYS y HITL_MODE_IF_UNSAFE.

discoveryengine.googleapis.com/agentregistry/connector

El esquema discoveryengine.googleapis.com/agentregistry/connector define los metadatos del proveedor para los conectores de datos de Gemini Enterprise. Cuando registras un servidor externo del Protocolo de contexto del modelo (MCP) a través de un conector de Gemini Enterprise, el Concentrador de aplicaciones adjunta estos metadatos extendidos al recurso de servicio subyacente.

El Registro de agentes muestra estos metadatos en el mapa attributes del recurso de descubrimiento McpServer correspondiente para que las aplicaciones cliente y los agentes de organización puedan inspeccionar las propiedades del conector, como type, state y instanceUri.

Definición de esquema

A continuación, se muestra el esquema de este tipo de metadatos en formato 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"]
      }
    }
  }
}

Descripciones de los campos

Campo Tipo Descripción
type string Es el tipo de conector de Gemini Enterprise como un identificador en minúsculas separado por guiones.
version string Es la versión de la definición del conector a partir de la cual se creó esta instancia.
state string Es el estado de aprovisionamiento de la instancia del conector.
instanceUri string Es la URL del sitio del cliente para los conectores que se direccionan por usuario.
tenantId string Es el identificador del usuario del cliente dentro del servicio externo.
skills array Son las revisiones de habilidades de Agent Registry adjuntas a un conector de MCP personalizado, hasta cinco entradas. Se omite para otros conectores y para conectores de MCP personalizados sin habilidades adjuntas.
skills.skill string Es el nombre del recurso de la habilidad, en el formato projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL.
skills.skillUid string Es el identificador único (uid) de la habilidad.
skills.revision string Es el nombre del recurso de la revisión de la habilidad, con el formato projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL/revisions/REVISION.
skills.revisionUid string Es el identificador único (uid) de la revisión de la habilidad.
skills.sha256 string Es el resumen SHA-256 de la carga útil de la revisión de la habilidad como 64 caracteres hexadecimales en minúscula.