Esquema de manifesto de plug-in 2.2 para Microsoft 365 Copilot

Os plug-ins de API permitem que o Microsoft 365 Copilot interaja com APIs REST descritas por uma descrição de OpenAPI. A descrição do OpenAPI em um plug-in de API descreve as APIs REST com as quais o Copilot pode interagir. Além disso, um plug-in de API inclui um arquivo de manifesto de plug-in que fornece metadados sobre o plug-in, como nome, descrição e versão do plug-in. O manifesto do plug-in também inclui informações sobre os recursos do plug-in, como as APIs que ele suporta e as operações que ele pode executar.

O artigo a seguir descreve o esquema 2.2 usado pelos arquivos de manifesto do plugin de API. Para obter mais informações sobre plug-ins de API, consulte Plug-ins do Microsoft 365 Copilot.

Alterações da versão anterior

Esta versão do esquema introduz as seguintes alterações da versão 2.1.

• Adicionou a security_info propriedade ao objeto de recursos da função. Essa propriedade permite atestar o comportamento do plug-in para avaliar os riscos de chamar a função.
• Removida a propriedade preterida localization do objeto de recursos do plug-in. Os manifestos gerados com o Microsoft 365 Agents Toolkit usando o esquema 2.1 incluíam a propriedade preterida localization . Os manifestos que usam o esquema 2.2 falharão na validação se essa propriedade estiver incluída.

Esquema JSON

O esquema descrito neste documento pode ser encontrado no formato JSON Schemaaqui.

Convenções

Referências relativas em URLs

A menos que especificado de outra forma, todas as propriedades que são URLs PODEM ser referências relativas. As referências relativas no documento de manifesto são relativas ao local do documento de manifesto.

Comprimento da cadeia de caracteres

A menos que especificado de outra forma, todas as propriedades da cadeia de caracteres DEVEM ser limitadas a caracteres 4K. Esse comprimento de cadeia de caracteres não confere nenhum tamanho aceitável para todo o documento. As implementações são livres para impor seus próprios limites práticos sobre o comprimento do manifesto.

Propriedades não reconhecidas

Os objetos JSON definidos neste documento dão suporte apenas às propriedades descritas. Propriedades não reconhecidas em qualquer objeto JSON DEVEM tornar todo o documento inválido.

Localização de cadeia de caracteres

Cadeias de caracteres localizáveis podem usar uma chave de localização em vez de um valor literal. A sintaxe é [[key_name]], onde key_name está o nome da localizationKeys chave na propriedade em seus arquivos de localização. Para obter detalhes sobre localização, consulte Localizar seu agente.

Exemplo de cadeia de caracteres localizada

{
    "schema_version": "v2.2",
    "name_for_human": "[[plugin_name]]",
    "description_for_human": "[[plugin_description]]"
}

Objeto de manifesto do plug-in

A raiz do documento de manifesto do plug-in é um objeto JSON que contém propriedades que descrevem o plug-in.

O objeto de manifesto do plug-in contém as propriedades a seguir.

Objeto de função

Informações relacionadas a como o modelo deve interagir com uma função.

O objeto de função contém as propriedades a seguir.

Exemplo de objeto de função

{
  "functions": [
    {
      "name": "add_todo",
      "description": "Adds a new Todo",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          }
        },
        "required": [
          "description"
        ]
      },
      "returns": {
        "type": "string"
      }
    }
  ]
}

Objeto de parâmetros de função

Um objeto usado para identificar o conjunto de parâmetros que podem ser passados para a função. Esse objeto é estruturado para espelho a forma de um objeto de esquema JSON, mas suporta apenas um subconjunto de palavras-chave de esquema JSON.

O objeto parâmetros de função contém as propriedades a seguir.

Exemplo de objeto de parâmetros de função

{
  "type": "object",
  "properties": {
    "param1": {
      "type": "string"
    },
    "param2": {
      "type": "number"
    }
  },
  "required": [
    "param1"
  ]
}

Objeto de propriedades de parâmetros de função

Um objeto que mapeia nomes de parâmetros para suas definições.

O objeto de propriedades de parâmetros de função contém as propriedades a seguir.

Objeto de parâmetro de função

Um objeto que descreve a semântica de um parâmetro de função.

O objeto de parâmetro de função contém as propriedades a seguir.

Exemplo de parâmetro de função

{
  "type": "string",
  "description": "The color of the item",
  "enum": [
    "green",
    "blue",
    "orange"
  ]
}

Objeto de retorno

Contém a semântica do valor retornado da função.

O objeto de retorno contém as propriedades a seguir.

Objeto de retorno avançado

Indica que a função retorna uma resposta compatível com o protocolo de Rich Responses.

O objeto de retorno avançado contém as propriedades a seguir.

Objeto de estados de função

Define objetos de estado para estados do orquestrador.

O objeto de estados de função contém as propriedades a seguir.

Objeto de estado

Contém instruções específicas para quando uma função é invocada em um estado de orquestrador específico.

O objeto state contém as propriedades a seguir.

Exemplo de objeto de estado

{
  "functions": [
    {
      "name": "searchEmails",
      "description": "search for Emails from using 3S search Service",
      "states": {
        "responding": {
          "description": "",
          "instructions": [
            "Examine the output of searchEmails",
            "Do not include any information that is not present in the JSON results.",
            "Exclude any irrelevant data from the JSON results",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message extracted from the response JSON.",
            "If there is no error, extract and include as much relevant information as possible from the JSON result to meet the user's needs."
          ],
          "examples": []
        }
      }
    }
  ]
}

Objeto de recursos da função

Contém uma coleção de dados usados para configurar recursos opcionais do orquestrador ao invocar a função.

O objeto de recursos da função contém as propriedades a seguir.

Objeto de confirmação

Descreve como o orchestrator solicita que o usuário confirme antes de chamar uma função.

O objeto de confirmação contém as propriedades a seguir.

Objeto de semântica de resposta

Contém informações para identificar a semântica do conteúdo de resposta e habilitar a renderização dessas informações em uma experiência visual avançada usando Cartões Adaptáveis.

O objeto de semântica de resposta contém as propriedades a seguir.

Exemplo de modelo estático

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.resources",
        "properties": {
          "title": "$.name",
          "subtitle": "$.location",
          "url": "$.href",
          "information_protection_label": "$.ipLabel"
        },
        "static_template": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "type": "AdaptiveCard",
          "version": "1.5",
          "body": [
            {
              "type": "TextBlock",
              "text": "${name}",
              "weight": "Bolder"
            },
            {
              "type": "TextBlock",
              "text": "${description}"
            }
          ],
          "action": [
            {
              "type": "Action.OpenUrl",
              "title": "View",
              "text": "${href}"
            }
          ]
        }
      }
    }
  }
}

Exemplo de modelo dinâmico

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.attachments",
        "properties": {
          "title": "$.title",
          "subtitle": "$.subtitle",
          "url": "$.url",
          "thumbnail_url": "$.thumbnailUrl",
          "template_selector": "$.template"
        }
      }
    }
  }
}

Objeto de propriedades de semântica de resposta

Permite o mapeamento de consultas JSONPath para elementos de dados conhecidos. Cada consulta JSONPath é relativa a um valor de resultado.

O objeto de propriedades de semântica de resposta contém as propriedades a seguir.

Objeto de informações de segurança

Contém informações usadas para determinar o risco relativo de invocar a função.

O objeto de informações de segurança contém as propriedades a seguir.

Valores de tratamento de dados

Objeto de tempo de execução de OpenAPI

Descreve como o plug-in invoca funções OpenAPI.

O objeto de tempo de execução OpenAPI contém as propriedades a seguir.

Objeto de especificação de OpenAPI

Contém as informações de OpenAPI necessárias para invocar o tempo de execução.

O objeto de especificação OpenAPI contém as propriedades a seguir.

Exemplo de objeto de especificação de OpenAPI

{
  "runtimes":
  [
    {  
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://example.org/api/openapi.yaml",  
      }
    }
  ]
}  

Objeto de autenticação de runtime

Contém informações usadas pelo plug-in para autenticar o tempo de execução.

O objeto de autenticação de tempo de execução contém as propriedades a seguir.

Exemplo de objeto de autenticação de runtime

{
  "type": "OAuthPluginVault",
  "reference_id": "0123456-abcdef"
}

Objeto de recursos do plug-in

Descreve os recursos do plug-in.

O objeto de recursos do plug-in contém as propriedades a seguir.

Objeto de início de conversa

Um exemplo de uma pergunta que o plug-in pode responder.

O objeto inicial de conversa contém as seguintes propriedades.

Exemplo de objeto inicial de conversa

{
  "conversation_starters": [
    {
      "title": "Developer tasks",
      "text": "What issues are assigned to me?"
    }
  ]
}

Exemplo de manifesto

Aqui está um exemplo de um arquivo de manifesto de plug-in que usa a maioria das propriedades de manifesto e de objeto descritas no artigo:

{
  "schema_version": "v2.2",
  "name_for_human": "Contoso Real Estate",
  "description_for_human": "Find up-to-date, detailed real estate properties for sale on the market",
  "description_for_model": "Plugin for finding properties for sale. Use it whenever a user asks about real estate properties for sale on the market. This plugin can be used to search for properties in a particular city, and with a given number of bedrooms, bathrooms, and amenities.",
  "capabilities": {
    "conversation_starters": [
      {
        "title": "Available listings",
        "text": "What listings are available in my area?"
      }
    ]
  },
  "functions": [
    {
      "name": "getListings",
      "description": "Get a list of properties matching the specified criteria",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search properties in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms the property should have"
          },
          "bathrooms": {
            "type": "number",
            "description": "The number of bathrooms the property should have"
          },
          "amenities": {
            "type": "array",
            "description": "The list of amenities the property should have",
            "items": {
              "type": "string",
              "description": "One amenity the property should have",
              "enum": [
                "air conditioning",
                "balcony",
                "dishwasher",
                "elevator",
                "fireplace",
                "furniture",
                "garden",
                "gym",
                "heating",
                "jacuzzi",
                "laundry room",
                "microwave",
                "no furniture",
                "parking",
                "patio",
                "sauna",
                "swimming pool",
                "terrace",
                "wi-fi"
              ]
            }
          }
        }
      },
      "returns": {
        "type": "string",
        "description": "A list of properties"
      },
      "states": {
        "reasoning": {
          "description": "`getListings` returns a list of real estate properties for sale based on the specified criteria.",
          "instructions": [
            "If the user mentions a city in their question, only search in that city by using the city parameter.",
            "If the user asks for properties with things like parking space, heating, jacuzzi, or similar amenities, use the amenities parameter to filter the results.",
            "Only use the list of amenities provided in the amenities parameter enum. If the user asked for an amenity that is not in the list, find the closest match from the list, or ignore it if no match can be found."
          ]
        },
        "responding": {
          "description": "`getListings` returns a list of real estate properties for sale based on the specified criteria.",
          "instructions": [
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message from the JSON response to the user.",
            "If there is no error, extract and include as much relevant information as possible from the JSON response to meet the users needs."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "GetPublicData",
            "GetPrivateData"
          ]
        }
      }
    },
    {
      "name": "saveSearch",
      "description": "Save a search for properties for sale",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms"
          }
        },
        "required": [
          "city"
        ]
      },
      "returns": {
        "type": "string",
        "description": "The unique ID for the saved search"
      },
      "states": {
        "responding": {
          "description": "`saveSearch` returns a unique ID that identifies the newly saved search.",
          "instructions": [
            "Examine the output of the `saveSearch` function.",
            "Extract the unique ID integer from the output and include it in your response to the user."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    },
    {
      "name": "deleteSavedSearch",
      "description": "Delete a previously saved search",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique ID of the saved search"
          }
        },
        "required": [
          "id"
        ]
      },
      "returns": {
        "type": "string",
        "description": "True if the saved search was deleted, false otherwise"
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": {
        "type": "none"
      },
      "run_for_functions": [
        "getListings",
        "saveSearch",
        "deleteSavedSearch"
      ],
      "spec": {
        "url": "http://contoso.com/openapi.yaml"
      }
    }
  ],
  "logo_url": "http://contoso.com/logo.png",
  "contact_email": "contact@contoso.com",
  "legal_info_url": "https://contoso.com/legal/"
}

Conteúdo relacionado

• Plug-ins do Microsoft 365 Copilot