Schemi JSON

Quando registri esplicitamente agenti o server Model Context Protocol (MCP) con Agent Registry utilizzando le API di servizi, devi fornire file di configurazione che descrivono le loro funzionalità.

Agent Registry convalida i file caricati in base alle specifiche esterne open source prima di indicizzarli per scoprire le competenze e gli strumenti degli agenti.

Questo documento fornisce esempi e link alle strutture JSON previste per le schede dell'agente e le specifiche dello strumento MCP.

Schema della scheda agente

Quando registri un agente conforme ad A2A, il payload agent-card.json deve rispettare la specifica Agent2Agent (A2A). La dimensione massima del file di specifica è 10 KB. I campi dell'array skills supportano l'indice di ricerca delle parole chiave.

Agent Registry supporta le versioni 0.3 e 1.0 della scheda dell'agente A2A.

Schema versione 1.0 (consigliato)

Per la versione 1.0 delle schede agente A2A, il payload deve rispettare la specifica v1.0 ufficiale di A2A. In questa specifica, dichiari gli endpoint di trasporto all'interno di un 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"
      ]
    }
  ]
}

Definizioni dei campi (versione 1.0)

  • name: Il nome dell'agente leggibile da una persona.
  • description: un riepilogo generale dello scopo dell'agente.
  • version: la versione dell'agente, ad esempio 1.0.0.
  • supportedInterfaces: un array di combinazioni di URL e trasporto supportati. Ogni interfaccia contiene quanto segue:
    • url: l'URL dell'endpoint in cui viene raggiunta questa interfaccia.
    • protocolBinding: l'associazione di protocollo supportata in questo URL, ad esempio HTTP+JSON, JSONRPC o GRPC.
    • protocolVersion: la versione del protocollo A2A esposta da questa interfaccia, ad esempio 1.0.0.
    • tenant: (Facoltativo) L'identificatore del proprietario dell'agente.
  • capabilities: (Facoltativo) Specifica le funzionalità operative supportate, ad esempio:
    • extensions: (Facoltativo) Un array di estensioni del protocollo.
    • streaming: (Facoltativo) Un valore booleano che indica se l'agente supporta le risposte in streaming.
    • pushNotifications: (Facoltativo) Un valore booleano che indica se le notifiche push sono supportate per gli aggiornamenti delle attività.
    • extendedAgentCard: (Facoltativo) Un valore booleano che indica se l'agente fornisce una scheda dell'agente estesa quando viene autenticato.
  • defaultInputModes: (Facoltativo) Un array di tipi MIME accettati come input.
  • defaultOutputModes: (Facoltativo) Un array di tipi MIME prodotti come output.
  • skills: un array di funzionalità dell'agente:
    • id: un identificatore programmatico univoco per la skill.
    • name: un nome leggibile per la skill.
    • description: una spiegazione dettagliata di cosa fa la skill.
    • tags: un array di stringhe di parole chiave utilizzate per classificare la skill.
    • examples: un array di prompt o scenari di esempio.

Schema della versione 0.3

Per la versione 0.3 delle schede dell'agente A2A, il payload deve rispettare la specifica v0.3.0. In questa specifica, l'URL di inferenza primario e la versione del protocollo sono dichiarati come campi di primo livello.

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

Definizioni dei campi (versione 0.3)

  • name: Il nome dell'agente leggibile da una persona.
  • description: un riepilogo generale dello scopo dell'agente.
  • version: la versione dell'agente, ad esempio 1.0.2.
  • protocolVersion: la versione del protocollo A2A implementata dall'agente. Poiché la versione 1.0 ritira questo campo di primo livello, il valore deve essere 0.3 o qualsiasi versione patch 0.3, ad esempio 0.3.1, per questo schema.
  • url: l'URL dell'endpoint in cui è possibile contattare l'agente.
  • capabilities: (Facoltativo) Specifica le funzionalità operative supportate, come streaming, pushNotifications o stateTransitionHistory.
  • defaultInputModes: (Facoltativo) Un array di tipi MIME accettati come input.
  • defaultOutputModes: (Facoltativo) Un array di tipi MIME prodotti come output.
  • skills: un array di funzionalità dell'agente:
    • id: un identificatore programmatico univoco per la skill.
    • name: un nome leggibile per la skill.
    • description: una spiegazione dettagliata di cosa fa la skill.
    • tags: un array di stringhe di parole chiave utilizzate per classificare la skill.
    • examples: un array di prompt o scenari di esempio.

Schema dello strumento MCP

Quando registri un server MCP, il payload toolspec.json deve includere un elenco di strumenti che rispettano lo schema dell'oggetto MCP Tool.

Il payload previsto è un oggetto JSON con un singolo campo tools, esattamente come viene restituito dalla richiesta di elenco o dagli strumenti MCP standard. La dimensione massima del file di specifica è 10 kB.

{
  "tools": [
    {
      "name": "string",
      "description": "string",
      "inputSchema": {
        "type": "object",
        "properties": {}
      },
      "annotations": {
        "title": "string",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      }
    }
  ]
}

Definizioni dei campi

  • tools: un array di strumenti forniti dal server:

    • name: l'identificatore programmatico dello strumento.
    • description: una spiegazione dello scopo dello strumento leggibile da una persona.
    • inputSchema: un oggetto JSON Schema che definisce i parametri previsti per lo strumento.

    • annotations: Suggerimenti comportamentali che guidano il modo in cui gli agenti orchestratori interagiscono con lo strumento:

      • title: un titolo leggibile per lo strumento.
      • readOnlyHint: se true, lo strumento recupera solo i dati e non modifica il suo ambiente. Il valore predefinito è false.
      • destructiveHint: se true, lo strumento esegue operazioni che potrebbero causare modifiche permanenti. Il valore predefinito è true.
      • idempotentHint: Se true, chiamare lo strumento ripetutamente non ha alcun effetto aggiuntivo. Il valore predefinito è false.
      • openWorldHint: Se true, lo strumento interagisce con sistemi esterni. Il valore predefinito è true.