Esquemas JSON

Ao registrar explicitamente agentes ou servidores de Protocolo de Contexto de Modelo (MCP) com o Registro de agentes usando as APIs dos Serviços, você precisa fornecer arquivos de configuração que descrevam os recursos deles.

O Registro de agentes valida os arquivos enviados em relação a especificações externas de código aberto antes de indexá-los para descobrir habilidades e ferramentas do agente.

Este documento fornece exemplos e links para as estruturas JSON esperadas para cards de agentes e especificações de ferramentas do MCP.

Esquema do card do agente

Ao registrar um agente compatível com A2A, o payload agent-card.json precisa seguir a especificação oficial do A2A. O tamanho máximo do arquivo para esse arquivo de especificação é de 10 KB. Os campos da matriz skills oferecem suporte ao índice de pesquisa de palavras-chave.

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

Definições dos campos

  • name: o nome legível do agente.
  • description: um resumo de alto nível da finalidade do agente.
  • version: a versão do agente, por exemplo, 1.0.2.
  • protocolVersion: a versão do protocolo Agent2Agent que o agente implementa, por exemplo, 0.3.0.
  • url: o URL do endpoint em que o agente pode ser acessado.
  • capabilities: opcional. Um objeto que especifica os recursos operacionais com suporte do agente, como streaming, pushNotifications ou stateTransitionHistory.
  • defaultInputModes: opcional. Uma matriz de strings que define os tipos MIME padrão que o agente aceita como entrada, por exemplo, ["text/plain"].
  • defaultOutputModes: opcional. Uma matriz de strings que define os tipos MIME padrão que o agente produz como saída, por exemplo, ["text/plain"].

  • skills: uma matriz de recursos que o agente possui:

    • id: um identificador programático exclusivo da habilidade.
    • name: um nome legível para a habilidade.
    • description: uma explicação detalhada do que a habilidade faz.
    • tags: uma matriz de strings de palavras-chave usadas para categorizar a habilidade.
    • examples: uma matriz de exemplos de comandos ou cenários que essa habilidade processa.

Esquema de ferramentas do MCP

Ao registrar um servidor MCP, o payload toolspec.json precisa incluir uma lista de ferramentas que aderem ao esquema de objeto Tool do MCP.

O payload esperado é um objeto JSON com um único tools campo, exatamente como ele é retornado por as ferramentas padrão do MCP ou solicitação de lista. O tamanho máximo do arquivo para esse arquivo de especificação é de 10 KB.

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

Definições dos campos

  • tools: uma matriz de ferramentas fornecidas pelo servidor:

    • name: o identificador programático da ferramenta.
    • description: uma explicação legível da finalidade da ferramenta.
    • inputSchema: um objeto de esquema JSON que define os parâmetros esperados para a ferramenta.

    • annotations: dicas de comportamento que orientam como os agentes do orquestrador interagem com a ferramenta:

      • title: um título legível para a ferramenta.
      • readOnlyHint: se for true, a ferramenta só recupera dados e não modifica o ambiente. O padrão é false.
      • destructiveHint: se for true, a ferramenta realiza operações que podem causar mudanças permanentes. O padrão é true.
      • idempotentHint: se for true, chamar a ferramenta repetidamente não terá efeito adicional. O padrão é false.
      • openWorldHint: se for true, a ferramenta interage com sistemas externos. O padrão é true.