Skema JSON

Saat Anda mendaftarkan agen atau server Model Context Protocol (MCP) secara manual di Agent Registry dengan membuat resource Service, Anda menyediakan file konfigurasi JSON yang mendeklarasikan kemampuannya. Registry Agen memvalidasi file ini berdasarkan spesifikasi open source sebelum mengindeksnya sehingga konsumen dapat menemukan kemampuan A2A dan alat MCP agen. Gunakan struktur dan contoh JSON berikut untuk memformat Kartu Agen dan spesifikasi alat MCP Anda.

Skema Kartu Agen

Saat mendaftarkan agen yang mematuhi A2A, payload agent-card.json Anda harus mematuhi spesifikasi Agent2Agent (A2A) resmi. Ukuran file maksimum untuk file spesifikasi adalah 150 KB. Kolom array skills mendukung indeks penelusuran kata kunci.

Registry Agen mendukung versi 1.0 dan 0.3 dari Kartu Agen A2A. Pilih versi untuk melihat skema JSON dan definisi kolomnya:

Untuk Kartu Agen A2A versi 1.0, payload harus mematuhi spesifikasi v1.0 A2A resmi. Dalam spesifikasi ini, Anda mendeklarasikan endpoint transpor dalam array 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"
      ]
    }
  ]
}

Definisi kolom

  • name: nama agen yang dapat dibaca manusia.
  • description: ringkasan tingkat tinggi tentang tujuan agen.
  • version: versi agen, misalnya, 1.0.0.
  • supportedInterfaces: array kombinasi transpor dan URL yang didukung. Setiap antarmuka berisi hal berikut:
    • url: URL endpoint tempat antarmuka ini dijangkau.
    • protocolBinding: binding protokol yang didukung di URL ini, misalnya, HTTP+JSON, JSONRPC, atau GRPC.
    • protocolVersion: versi A2A protocol yang diekspos antarmuka ini, misalnya, 1.0.0.
    • tenant (opsional): ID pemilik agen.
  • capabilities (opsional): menentukan kemampuan operasional yang didukung seperti berikut:
    • extensions (opsional): array ekstensi protokol.
    • streaming (opsional): boolean yang menunjukkan apakah agen mendukung respons streaming.
    • pushNotifications (opsional): boolean yang menunjukkan apakah notifikasi push didukung untuk update tugas.
    • extendedAgentCard (opsional): boolean yang menunjukkan apakah agen menyediakan Kartu Agen yang diperluas saat diautentikasi.
  • defaultInputModes (opsional): array jenis MIME yang diterima sebagai input.
  • defaultOutputModes (opsional): array jenis MIME yang dihasilkan sebagai output.
  • skills: array kemampuan A2A deskriptif yang dimiliki agen:
    • id: ID terprogram yang unik untuk kemampuan A2A.
    • name: nama yang dapat dibaca manusia untuk kemampuan A2A.
    • description: penjelasan mendetail tentang fungsi keahlian A2A.
    • tags: array string kata kunci yang digunakan untuk mengategorikan kemampuan A2A.
    • examples: array contoh perintah atau skenario yang ditangani oleh keterampilan A2A ini.

Versi 0.3

Untuk Kartu Agen A2A versi 0.3, payload harus mematuhi spesifikasi v0.3.0. Dalam spesifikasi ini, URL inferensi utama dan versi protokol dideklarasikan sebagai kolom tingkat atas:

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

Definisi kolom

  • name: nama agen yang dapat dibaca manusia.
  • description: ringkasan tingkat tinggi tentang tujuan agen.
  • version: versi agen, misalnya, 1.0.2.
  • protocolVersion: versi protokol A2A yang diterapkan agen. Karena versi 1.0 menghentikan penggunaan kolom tingkat teratas ini, nilainya harus berupa 0.3 atau versi patch 0.3 apa pun, seperti 0.3.1, untuk skema ini.
  • url: URL endpoint tempat agen dapat dijangkau.
  • capabilities (opsional): objek yang menentukan kemampuan operasional agen yang didukung, seperti streaming, pushNotifications, atau stateTransitionHistory.
  • defaultInputModes (opsional): array string yang menentukan jenis MIME default yang diterima agen sebagai input, misalnya, ["text/plain"].
  • defaultOutputModes (opsional): array string yang menentukan jenis MIME default yang dihasilkan agen sebagai output, misalnya, ["text/plain"].
  • skills: array kemampuan A2A deskriptif yang dimiliki agen:
    • id: ID terprogram yang unik untuk kemampuan A2A.
    • name: nama yang dapat dibaca manusia untuk kemampuan A2A.
    • description: penjelasan mendetail tentang fungsi keahlian A2A.
    • tags: array string kata kunci yang digunakan untuk mengategorikan kemampuan A2A.
    • examples: array contoh perintah atau skenario yang ditangani oleh keterampilan A2A ini.

Skema alat MCP

Saat mendaftarkan server MCP, payload toolspec.json Anda harus menyertakan daftar alat yang mematuhi skema objek Tool MCP.

Payload yang diharapkan adalah objek JSON dengan satu kolom tools, persis seperti yang ditampilkan oleh alat MCP standar atau permintaan daftar. Ukuran file maksimum untuk file spesifikasi ini adalah 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"
          }
        }
      }
    }
  ]
}

Definisi kolom

  • tools: array alat yang disediakan oleh server:

    • name: ID terprogram untuk alat.
    • description: penjelasan yang dapat dibaca manusia tentang tujuan alat.
    • inputSchema: objek JSON Schema yang menentukan parameter yang diharapkan untuk alat.
    • annotations: petunjuk perilaku yang memandu cara agen orchestrator berinteraksi dengan alat:

      • title: judul yang dapat dibaca manusia untuk alat.
      • readOnlyHint: jika true, alat hanya mengambil data dan tidak mengubah lingkungannya. Jumlah defaultnya adalah false
      • destructiveHint: jika true, alat akan melakukan operasi yang mungkin menyebabkan perubahan permanen. Jumlah defaultnya adalah true
      • idempotentHint: jika true, memanggil alat berulang kali tidak akan memberikan efek tambahan. Jumlah defaultnya adalah false
      • openWorldHint: jika true, alat akan berinteraksi dengan sistem eksternal. Jumlah defaultnya adalah true
    • _meta (opsional): metadata tingkat protokol yang mematuhi spesifikasi Model Context Protocol (MCP) untuk melampirkan metadata terstruktur ke alat. Karena annotations standar adalah objek tertutup yang terbatas pada petunjuk yang telah ditentukan, _meta menyediakan container yang dapat diperluas untuk metadata tambahan sekaligus mempertahankan kompatibilitas dengan klien MCP standar.

      Untuk mencegah konflik penamaan di seluruh penyedia, kunci level teratas dalam _meta menggunakan notasi domain terbalik. Registry Agen memvalidasi _meta terhadap apphub.googleapis.com/McpServer skema metadata yang diperluas dan mendukung namespace berikut:

      • com.googleapis.iap/PolicyHints (opsional): petunjuk kebijakan yang dievaluasi oleh Identity-Aware Proxy (IAP) dan Agent Gateway untuk menerapkan kontrol otorisasi alat dan human-in-the-loop (HITL):

        • authorization (opsional): konfigurasi otorisasi untuk alat:
          • toolDisabled (opsional): boolean yang menunjukkan apakah alat dinonaktifkan untuk pemanggilan. Tetapkan ke true untuk menonaktifkan alat. Defaultnya adalah false, yang berarti alat ini diaktifkan saat Anda menghapus kolom ini.
          • hitlMode (opsional): string yang menentukan mode eksekusi human-in-the-loop (HITL) untuk alat:
            • HITL_MODE_UNSPECIFIED: mode HITL tidak ditentukan.
            • HITL_MODE_DISABLED: alat berjalan tanpa memerlukan persetujuan manusia yang interaktif.
            • HITL_MODE_ALWAYS: alat ini selalu memerlukan persetujuan manusia interaktif sebelum dieksekusi.
            • HITL_MODE_IF_UNSAFE: alat ini memerlukan persetujuan manusia interaktif hanya jika operasi dievaluasi sebagai tidak aman.