Schemi di metadati estesi

App Hub aggiunge automaticamente metadati estesi ad alcuni servizi e workload per migliorare la rilevabilità, la governance e l'integrazione con altri sistemi. Una chiave univoca identifica ogni schema supportato e definisce la struttura e i campi per un tipo specifico di metadati. Per visualizzare questi metadati, consulta Visualizza gli schemi dei metadati estesi.

apphub.googleapis.com/AgentProperties

Questo schema viene utilizzato per descrivere le proprietà di un agente AI, consentendo ad altri sistemi di trovarlo e comprenderlo. In genere viene applicato ai workload che hanno una proprietà di tipo funzionale AGENT. Lo schema è compatibile con la scheda agente Agent2Agent (A2A).

Definizione schema

Di seguito è riportato lo schema per questo tipo di metadati in 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"
            }
          }
        }
      }
    }
  }
}

Descrizioni dei campi

Campo Tipo Descrizione
displayName string Il nome visualizzato dell'agente.
description string La descrizione dell'agente.
version string La versione dell'agente.
framework string Il framework utilizzato per sviluppare l'agente.
agentCardUri string L'URI della scheda dell'agente.
skills array Un elenco di skill possedute dall'agente.
skills.id string Un identificatore univoco della competenza dell'agente.
skills.name string Un nome leggibile per la skill dell'agente.
skills.description string Una descrizione della skill dell'agente.
skills.tags array di string Un insieme di parole chiave che descrivono le funzionalità della skill.
skills.examples array di string Esempi di prompt o scenari che questa skill può gestire.

apphub.googleapis.com/McpServer

Lo schema apphub.googleapis.com/McpServer definisce le proprietà di un server Model Context Protocol (MCP) e gli strumenti che espone. App Hub applica questo schema ai servizi che hanno una proprietà di tipo funzionale MCP_SERVER. Lo schema include dichiarazioni di endpoint di trasporto e definizioni di strumenti conformi alla specifica MCP, inclusi suggerimenti comportamentali in annotations e suggerimenti di policy in _meta.

Definizione schema

Di seguito è riportato lo schema per questo tipo di metadati in 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"]
    }
  }
}

Descrizioni dei campi

Campo Tipo Descrizione
displayName string Il nome visualizzato del server MCP.
description string La descrizione del server MCP.
interfaces array I dettagli di connessione per il server MCP.
interfaces.url string L'URL dell'endpoint di destinazione per l'interfaccia.
interfaces.protocolBinding string L'associazione del protocollo dell'interfaccia, ad esempio JSONRPC.
tools array Strumenti forniti dal server MCP.
tools.name string Nome dello strumento leggibile.
tools.description string Descrizione di ciò che fa lo strumento.
tools.annotations object Annotazioni MCP standard associate allo strumento.
tools.annotations.title string Un titolo leggibile per lo strumento.
tools.annotations.readOnlyHint boolean Suggerimento che indica se lo strumento recupera solo i dati e non modifica il suo ambiente.
tools.annotations.destructiveHint boolean Suggerimento che indica se l'operazione può causare modifiche distruttive.
tools.annotations.idempotentHint boolean Suggerimento che indica se l'operazione è idempotente e se è sicuro riprovare.
tools.annotations.openWorldHint boolean Suggerimento che indica se l'operazione interagisce con sistemi esterni.
tools._meta object Metadati a livello di protocollo conformi alla specifica MCP _meta. Le chiavi devono seguire la notazione del dominio inverso.
tools._meta.com.googleapis.iap/PolicyHints object Suggerimenti per le policy di Identity-Aware Proxy (IAP) per lo strumento.
tools._meta.com.googleapis.iap/PolicyHints.authorization object Configurazione dell'autorizzazione e di human-in-the-loop (HITL) per lo strumento.
tools._meta.com.googleapis.iap/PolicyHints.authorization.toolDisabled boolean Indica se lo strumento è disabilitato per la chiamata. Imposta il criterio su true per disattivare lo strumento. Se omesso, il valore predefinito è false, il che significa che lo strumento è abilitato.
tools._meta.com.googleapis.iap/PolicyHints.authorization.hitlMode string Modalità di esecuzione human-in-the-loop (HITL). I valori supportati sono HITL_MODE_UNSPECIFIED, HITL_MODE_DISABLED, HITL_MODE_ALWAYS e HITL_MODE_IF_UNSAFE.

discoveryengine.googleapis.com/agentregistry/connector

Lo schema discoveryengine.googleapis.com/agentregistry/connector definisce i metadati del provider per i connettori dati di Gemini Enterprise. Quando registri un server Model Context Protocol (MCP) esterno tramite un connettore Gemini Enterprise, App Hub associa questi metadati estesi alla risorsa di servizio sottostante.

Agent Registry mostra questi metadati nella mappa attributes della risorsa di rilevamento McpServer corrispondente, in modo che le applicazioni client e gli agenti orchestratore possano ispezionare le proprietà del connettore, come type, state e instanceUri.

Definizione schema

Di seguito è riportato lo schema per questo tipo di metadati in 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"]
      }
    }
  }
}

Descrizioni dei campi

Campo Tipo Descrizione
type string Il tipo di connettore Gemini Enterprise come identificatore in minuscolo separato da trattini.
version string La versione della definizione del connettore da cui è stata creata questa istanza.
state string Lo stato di provisioning dell'istanza del connettore.
instanceUri string L'URL del sito del cliente per i connettori indirizzati per tenant.
tenantId string L'identificatore del tenant del cliente all'interno del servizio esterno.
skills array Le revisioni delle skill di Agent Registry collegate a un connettore MCP personalizzato, fino a cinque voci. Omesso per altri connettori e per i connettori MCP personalizzati senza skill collegate.
skills.skill string Il nome della risorsa della skill, nel formato projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL.
skills.skillUid string L'identificatore univoco (uid) della skill.
skills.revision string Il nome risorsa della revisione della skill, nel formato projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL/revisions/REVISION.
skills.revisionUid string L'identificatore univoco (uid) della revisione della skill.
skills.sha256 string Il digest SHA-256 del payload della revisione della skill come 64 caratteri esadecimali minuscoli.