JSON-Schemas

Wenn Sie Agenten oder MCP-Server (Model Context Protocol) manuell in der Agent Registry registrieren, indem Sie eine Service-Ressource erstellen, stellen Sie JSON-Konfigurationsdateien bereit, in denen ihre Funktionen deklariert werden. Die Agent Registry validiert diese Dateien anhand von Open-Source-Spezifikationen, bevor sie indexiert werden, damit Nutzer die A2A-Fähigkeiten und MCP-Tools des Agenten finden können. Verwenden Sie die folgenden JSON-Strukturen und ‑Beispiele, um Ihre Agentenkarten und MCP-Toolspezifikationen zu formatieren.

Agentenkarte-Schema

Beim Registrieren eines A2A-konformen KI-Agenten muss die Nutzlast von agent-card.json der offiziellen Agent2Agent-Spezifikation (A2A) entsprechen. Die maximale Dateigröße für die Spezifikationsdatei beträgt 150 KB. Die skills-Arrayfelder unterstützen den Suchindex für Keywords.

Die Agent Registry unterstützt die Versionen 1.0 und 0.3 der A2A-Agentenkarte. Wählen Sie eine Version aus, um das JSON-Schema und die Felddefinitionen aufzurufen:

Für Version 1.0 von A2A-Agentenkarten muss die Nutzlast der offiziellen A2A-Spezifikation v1.0 entsprechen. In dieser Spezifikation deklarieren Sie Transportendpunkte in einem supportedInterfaces-Array:

{
  "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"
      ]
    }
  ]
}

Felddefinitionen

  • name: Der menschenlesbare Name des KI-Agenten.
  • description: Eine allgemeine Zusammenfassung des Zwecks des KI-Agenten.
  • version: die Version des Agenten, z. B. 1.0.0.
  • supportedInterfaces: ein Array unterstützter Transport- und URL-Kombinationen. Jede Schnittstelle enthält Folgendes:
    • url: die Endpunkt-URL, über die diese Schnittstelle erreicht wird.
    • protocolBinding: die Protokollbindung, die unter dieser URL unterstützt wird, z. B. HTTP+JSON, JSONRPC oder GRPC.
    • protocolVersion: die A2A-Protokollversion, die diese Schnittstelle bereitstellt, z. B. 1.0.0.
    • tenant (optional): die ID des Agenteninhabers.
  • capabilities (optional): Gibt unterstützte Betriebsfunktionen an, z. B.:
    • extensions (optional): ein Array von Protokollerweiterungen.
    • streaming (optional): Ein boolescher Wert, der angibt, ob der Agent Streamingantworten unterstützt.
    • pushNotifications (optional): Ein boolescher Wert, der angibt, ob Push-Benachrichtigungen für Aufgabenaktualisierungen unterstützt werden.
    • extendedAgentCard (optional): Ein boolescher Wert, der angibt, ob der Agent nach der Authentifizierung eine erweiterte Agentenkarte bereitstellt.
  • defaultInputModes (optional): ein Array von MIME-Typen, die als Eingabe akzeptiert werden.
  • defaultOutputModes (optional): Ein Array von MIME-Typen, die als Ausgabe erzeugt werden.
  • skills: ein Array mit beschreibenden A2A-Fähigkeiten, die der Agent besitzt:
    • id: Eine eindeutige programmatische Kennung für den A2A-Skill.
    • name: Ein menschenlesbarer Name für den A2A-Skill.
    • description: eine detaillierte Erklärung der Funktion des A2A-Skills.
    • tags: Ein Array von Keyword-Strings, die zur Kategorisierung des A2A-Skills verwendet werden.
    • examples: Ein Array von Beispiel-Prompts oder ‑Szenarien, die dieser A2A-Skill verarbeitet.

Version 0.3

Für Version 0.3 von A2A-Agentenkarten muss die Nutzlast der Spezifikation v0.3.0 entsprechen. In dieser Spezifikation werden die primäre Inferenz-URL und die Protokollversion als Felder der obersten Ebene deklariert:

{
  "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"
  ]
}

Felddefinitionen

  • name: Der menschenlesbare Name des KI-Agenten.
  • description: Eine allgemeine Zusammenfassung des Zwecks des KI-Agenten.
  • version: die Version des Agenten, z. B. 1.0.2.
  • protocolVersion: die Version des A2A-Protokolls, die der Agent implementiert. Da dieses Feld auf oberster Ebene in Version 1.0 verworfen wird, muss der Wert für dieses Schema 0.3 oder eine beliebige 0.3-Patchversion sein, z. B. 0.3.1.
  • url: die Endpunkt-URL, unter der der Agent erreichbar ist.
  • capabilities (optional): Ein Objekt, das die unterstützten Betriebsfunktionen des Agenten angibt, z. B. streaming, pushNotifications oder stateTransitionHistory.
  • defaultInputModes (optional): Ein Array von Strings, die die Standard-MIME-Typen definieren, die der Agent als Eingabe akzeptiert, z. B. ["text/plain"].
  • defaultOutputModes (optional): ein Array von Strings, die die Standard-MIME-Typen definieren, die der Agent als Ausgabe erzeugt, z. B. ["text/plain"].
  • skills: ein Array mit beschreibenden A2A-Fähigkeiten, die der Agent besitzt:
    • id: Eine eindeutige programmatische Kennung für den A2A-Skill.
    • name: Ein menschenlesbarer Name für den A2A-Skill.
    • description: eine detaillierte Erklärung der Funktion des A2A-Skills.
    • tags: Ein Array von Keyword-Strings, die zur Kategorisierung des A2A-Skills verwendet werden.
    • examples: Ein Array von Beispiel-Prompts oder ‑Szenarien, die dieser A2A-Skill verarbeitet.

MCP-Toolschema

Beim Registrieren eines MCP-Servers muss die Nutzlast von toolspec.json eine Liste von Tools umfassen, die dem Objektschema für MCP-Tool entsprechen.

Die erwartete Nutzlast ist ein JSON-Objekt mit einem einzelnen tools-Feld, genau wie es von der Standard-MCP-Tools- oder Listenanfrage zurückgegeben wird. Die maximale Dateigröße für diese Spezifikationsdatei beträgt 150 KB.

{
  "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"
          }
        }
      }
    }
  ]
}

Felddefinitionen

  • tools: ein Array von Tools, die vom Server bereitgestellt werden:

    • name: die programmatische Kennung für das Tool.
    • description: eine menschenlesbare Erklärung des Zwecks des Tools.
    • inputSchema: Ein JSON-Schemaobjekt, das die erwarteten Parameter für das Tool definiert.
    • annotations: Verhaltenshinweise, die festlegen, wie Orchestrator-Agenten mit dem Tool interagieren:

      • title: ein menschenlesbarer Titel für das Tool.
      • readOnlyHint: Wenn true, ruft das Tool nur Daten ab und ändert seine Umgebung nicht. Der Standardwert ist false.
      • destructiveHint: Wenn true, führt das Tool Vorgänge aus, die zu dauerhaften Änderungen führen können. Der Standardwert ist true.
      • idempotentHint: Wenn true festgelegt ist, hat das wiederholte Aufrufen des Tools keine zusätzlichen Auswirkungen. Der Standardwert ist false.
      • openWorldHint: Wenn true, interagiert das Tool mit externen Systemen. Der Standardwert ist true.
    • _meta (optional): Metadaten auf Protokollebene, die der MCP-Spezifikation (Model Context Protocol) entsprechen, um Tools strukturierte Metadaten anzuhängen. Da das Standard-annotations ein geschlossenes Objekt ist, das auf vordefinierte Hinweise beschränkt ist, bietet _meta einen erweiterbaren Container für zusätzliche Metadaten, während die Kompatibilität mit Standard-MCP-Clients erhalten bleibt.

      Um Namenskonflikte zwischen Anbietern zu vermeiden, wird für Schlüssel der obersten Ebene in _meta die umgekehrte Domainnotation verwendet. Die Agent Registry validiert _meta anhand des erweiterten Metadatenschemas von apphub.googleapis.com/McpServer und unterstützt den folgenden Namespace:

      • com.googleapis.iap/PolicyHints (optional): Richtlinienhinweise, die von Identity-Aware Proxy (IAP) und Agent Gateway ausgewertet werden, um die Toolautorisierung und Human-in-the-Loop-Steuerelemente (HITL) zu erzwingen:

        • authorization (optional): Autorisierungskonfiguration für das Tool:
          • toolDisabled (optional): Ein boolescher Wert, der angibt, ob das Tool für den Aufruf deaktiviert ist. Legen Sie true fest, um das Tool zu deaktivieren. Der Standardwert ist false. Das bedeutet, dass das Tool aktiviert ist, wenn Sie dieses Feld weglassen.
          • hitlMode (optional): Ein String, der den Human-in-the-Loop-Ausführungsmodus (HITL) für das Tool angibt:
            • HITL_MODE_UNSPECIFIED: Der HITL-Modus ist nicht angegeben.
            • HITL_MODE_DISABLED: Das Tool wird ohne interaktive Genehmigung durch einen Menschen ausgeführt.
            • HITL_MODE_ALWAYS: Das Tool erfordert vor der Ausführung immer eine interaktive Genehmigung durch einen Menschen.
            • HITL_MODE_IF_UNSAFE: Das Tool erfordert nur dann eine interaktive menschliche Genehmigung, wenn der Vorgang als unsicher eingestuft wird.