Schémas JSON

Lorsque vous enregistrez manuellement des agents ou des serveurs MCP (Model Context Protocol) dans Agent Registry en créant une ressource Service, vous fournissez des fichiers de configuration JSON qui déclarent leurs fonctionnalités. Le registre d'agents valide ces fichiers par rapport aux spécifications Open Source avant de les indexer, afin que les consommateurs puissent découvrir les compétences A2A et les outils MCP de l'agent. Utilisez les structures et exemples JSON suivants pour mettre en forme vos fiches d'agent et vos spécifications d'outils MCP.

Schéma de la fiche d'agent

Lorsque vous enregistrez un agent compatible A2A, votre charge utile agent-card.json doit respecter la spécification Agent2Agent (A2A) officielle. La taille maximale du fichier de spécification est de 150 Ko. Les champs de tableau skills sont compatibles avec l'index de recherche par mot clé.

Agent Registry est compatible avec les versions 1.0 et 0.3 de la carte d'agent A2A. Sélectionnez une version pour afficher son schéma JSON et ses définitions de champs :

Pour la version 1.0 des fiches d'agent A2A, la charge utile doit respecter la spécification v1.0 officielle d'A2A. Dans cette spécification, vous déclarez des points de terminaison de transport dans un tableau supportedInterfaces :

{
  "name": "string",
  "description": "string",
  "version": "string",
  "supportedInterfaces": [
    {
      "url": "string",
      "protocolBinding": "string",
      "protocolVersion": "string",
      "tenant": "string"
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ],
  "skills": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "examples": [
        "string"
      ]
    }
  ]
}

Définition des champs

  • name : nom lisible par l'humain de l'agent.
  • description : résumé général de l'objectif de l'agent.
  • version : version de l'agent, par exemple 1.0.0.
  • supportedInterfaces : tableau de combinaisons de transport et d'URL compatibles. Chaque interface contient les éléments suivants :
    • url : URL du point de terminaison où cette interface est accessible.
    • protocolBinding : liaison de protocole compatible avec cette URL, par exemple HTTP+JSON, JSONRPC ou GRPC.
    • protocolVersion : version du protocole A2A exposée par cette interface, par exemple 1.0.0.
    • tenant (facultatif) : identifiant du propriétaire de l'agent.
  • capabilities (facultatif) : spécifie les fonctionnalités opérationnelles compatibles, telles que les suivantes :
    • extensions (facultatif) : tableau d'extensions de protocole.
    • streaming (facultatif) : valeur booléenne indiquant si l'agent accepte les réponses en streaming.
    • pushNotifications (facultatif) : valeur booléenne indiquant si les notifications push sont acceptées pour les mises à jour de tâches.
    • extendedAgentCard (facultatif) : valeur booléenne indiquant si l'agent fournit une carte d'agent étendue lorsqu'il est authentifié.
  • defaultInputModes (facultatif) : tableau de types MIME acceptés en entrée.
  • defaultOutputModes (facultatif) : tableau de types MIME générés en sortie.
  • skills : tableau de compétences A2A descriptives que possède l'agent :
    • id : identifiant programmatique unique de la compétence A2A.
    • name : nom lisible par l'humain de la compétence A2A.
    • description : explication détaillée de ce que fait la compétence A2A.
    • tags : tableau de chaînes de mots clés utilisées pour catégoriser la compétence A2A.
    • examples : tableau d'exemples de requêtes ou de scénarios gérés par cette compétence A2A.

Version 0.3

Pour la version 0.3 des fiches d'agent A2A, la charge utile doit respecter la spécification v0.3.0. Dans cette spécification, l'URL d'inférence principale et la version du protocole sont déclarées en tant que champs de premier niveau :

{
  "name": "string",
  "description": "string",
  "version": "string",
  "protocolVersion": "string",
  "url": "string",
  "skills": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "examples": [
        "string"
      ]
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

Définition des champs

  • name : nom lisible par l'humain de l'agent.
  • description : résumé général de l'objectif de l'agent.
  • version : version de l'agent, par exemple 1.0.2.
  • protocolVersion : version du protocole A2A implémentée par l'agent. Étant donné que la version 1.0 abandonne ce champ de premier niveau, la valeur doit être 0.3 ou toute version de correctif 0.3, telle que 0.3.1, pour ce schéma.
  • url : URL du point de terminaison où l'agent est accessible.
  • capabilities (facultatif) : objet spécifiant les capacités opérationnelles de l'agent, telles que streaming, pushNotifications ou stateTransitionHistory.
  • defaultInputModes (facultatif) : tableau de chaînes définissant les types MIME par défaut que l'agent accepte en entrée, par exemple ["text/plain"].
  • defaultOutputModes (facultatif) : tableau de chaînes définissant les types MIME par défaut que l'agent produit en sortie, par exemple ["text/plain"].
  • skills : tableau de compétences A2A descriptives que possède l'agent :
    • id : identifiant programmatique unique de la compétence A2A.
    • name : nom lisible par l'humain de la compétence A2A.
    • description : explication détaillée de ce que fait la compétence A2A.
    • tags : tableau de chaînes de mots clés utilisées pour catégoriser la compétence A2A.
    • examples : tableau d'exemples de requêtes ou de scénarios gérés par cette compétence A2A.

Schéma de l'outil MCP

Lors de l'enregistrement d'un serveur MCP, votre charge utile toolspec.json doit inclure une liste d'outils conformes au schéma d'objet MCP Tool.

La charge utile attendue est un objet JSON avec un seul champ tools, exactement comme il est renvoyé par la requête d'outils ou de liste MCP standard. La taille maximale de ce fichier de spécifications est de 150 Ko.

{
  "tools": [
    {
      "name": "string",
      "description": "string",
      "inputSchema": {
        "type": "object",
        "properties": {}
      },
      "annotations": {
        "title": "string",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      },
      "_meta": {
        "com.googleapis.iap/PolicyHints": {
          "authorization": {
            "toolDisabled": false,
            "hitlMode": "HITL_MODE_ALWAYS"
          }
        }
      }
    }
  ]
}

Définition des champs

  • tools : tableau d'outils fournis par le serveur :

    • name : identifiant programmatique de l'outil.
    • description : explication lisible par l'humain de l'objectif de l'outil.
    • inputSchema : objet de schéma JSON définissant les paramètres attendus pour l'outil.
    • annotations : indices comportementaux qui guident la façon dont les agents d'orchestration interagissent avec l'outil :

      • title : titre lisible par l'humain de l'outil.
      • readOnlyHint : si la valeur est true, l'outil ne récupère que les données et ne modifie pas son environnement. La valeur par défaut est false.
      • destructiveHint : si la valeur est true, l'outil effectue des opérations susceptibles d'entraîner des modifications permanentes. La valeur par défaut est true.
      • idempotentHint : si la valeur est true, l'appel répété de l'outil n'a aucun effet supplémentaire. La valeur par défaut est false.
      • openWorldHint : si la valeur est true, l'outil interagit avec des systèmes externes. La valeur par défaut est true.
    • _meta (facultatif) : métadonnées au niveau du protocole conformes à la spécification du protocole MCP (Model Context Protocol) pour associer des métadonnées structurées aux outils. Étant donné que l'objet annotations standard est un objet fermé limité à des indications prédéfinies, _meta fournit un conteneur extensible pour les métadonnées supplémentaires tout en maintenant la compatibilité avec les clients MCP standards.

      Pour éviter les conflits de noms entre les fournisseurs, les clés de premier niveau dans _meta utilisent la notation de domaine inversé. Le registre d'agents valide _meta par rapport au schéma de métadonnées étendu apphub.googleapis.com/McpServer et accepte l'espace de noms suivant :

      • com.googleapis.iap/PolicyHints (facultatif) : indications de stratégie évaluées par Identity-Aware Proxy (IAP) et Agent Gateway pour appliquer l'autorisation des outils et les contrôles avec intervention humaine (HITL) :

        • authorization (facultatif) : configuration de l'autorisation pour l'outil :
          • toolDisabled (facultatif) : valeur booléenne indiquant si l'outil est désactivé pour l'appel. Définissez sur true pour désactiver l'outil. La valeur par défaut est false, ce qui signifie que l'outil est activé lorsque vous omettez ce champ.
          • hitlMode (facultatif) : chaîne spécifiant le mode d'exécution human-in-the-loop (HITL) pour l'outil :
            • HITL_MODE_UNSPECIFIED : le mode HITL n'est pas spécifié.
            • HITL_MODE_DISABLED : l'outil s'exécute sans nécessiter d'approbation humaine interactive.
            • HITL_MODE_ALWAYS : l'outil nécessite toujours une approbation humaine interactive avant l'exécution.
            • HITL_MODE_IF_UNSAFE : l'outil ne nécessite une approbation humaine interactive que lorsque l'opération est évaluée comme non sécurisée.