Schemi JSON

Quando registri esplicitamente agenti o server Model Context Protocol (MCP) con Agent Registry utilizzando le API Services, 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 dell'agente

Quando registri un agente conforme ad A2A, il payload agent-card.json deve rispettare la specifica A2A ufficiale. I campi dell'array skills supportano l'indice di ricerca delle parole chiave.

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

  • 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 Agent2Agent implementata dall'agente, ad esempio 0.3.0.
  • url: l'URL dell'endpoint in cui è possibile contattare l'agente.
  • capabilities: (Facoltativo) Un oggetto che specifica le funzionalità operative supportate dall'agente, ad esempio streaming, pushNotifications o stateTransitionHistory.
  • defaultInputModes: (Facoltativo) Un array di stringhe che definiscono i tipi MIME predefiniti che l'agente accetta come input, ad esempio ["text/plain"].
  • defaultOutputModes: (Facoltativo) Un array di stringhe che definiscono i tipi MIME predefiniti prodotti dall'agente come output, ad esempio ["text/plain"].

  • 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 gestiti da questa skill.

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.

{
  "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 schema JSON 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.