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

Os plug-ins permitem que o Microsoft 365 Copilot interaja com servidores MCP ou APIs REST descritas por uma descrição de OpenAPI. Um plug-in inclui um arquivo de manifesto de plug-in que fornece metadados sobre o plug-in, como o nome, a descrição e a versão do plug-in. O manifesto do plug-in também inclui informações sobre os recursos do plug-in, como as ferramentas ou APIs do MCP que ele suporta e as operações que ele pode executar.

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

Alterações da versão anterior

Esta versão do esquema introduz as seguintes mudanças a partir da versão 2.3.

  • Adicionado suporte para servidores MCP (Model Context Protocol).
  • Objeto de semântica de resposta aprimorada para dar suporte a referências de arquivo para modelos estáticos.
    • A static_template propriedade agora pode fazer referência a um arquivo externo usando uma file propriedade.
  • Atualizado o comportamento da propriedade do objetoisNonConsequential de confirmação para ações GET do OpenAPI.

Esquema JSON

Para exibir o esquema JSON descrito neste documento, consulte schema.json.

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.3",
    "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.

Propriedade Tipo Descrição
schema_version Cadeia de caracteres Obrigatório. A versão do esquema. As versões anteriores são v1, v2, v2.1, v2.2e v2.3. Deve ser definida como v2.4.
name_for_human Cadeia de caracteres Obrigatório. Um nome curto e legível para o plug-in. Ele DEVE conter pelo menos um caractere que não seja espaço em branco. Caracteres além de 20 PODEM ser ignorados. Esta propriedade é localizável.
namespace Cadeia de caracteres Obrigatório. Contém um identificador usado para evitar conflitos de nome entre nomes de função de diferentes plug-ins. O valor DEVE corresponder ao regex ^[A-Za-z0-9]+.
description_for_model String Opcional. A descrição do plug-in fornecido ao modelo. Essa descrição deve descrever para que serve o plug-in e em quais circunstâncias suas funções são relevantes. Caracteres além de 2048 PODEM ser ignorados. Esta propriedade é localizável.
description_for_human Cadeia de caracteres Obrigatório. Uma descrição legível do plug-in. Caracteres acima de 100 PODEM ser ignorados. Esta propriedade é localizável.
logo_url String Opcional. Uma URL usada para buscar um logotipo que PODE ser usado pelo orquestrador. As implementações PODEM fornecer métodos alternativos para fornecer logotipos que atendam aos seus requisitos visuais. Esta propriedade é localizável.
contact_email String Opcional. Um endereço de email de um contato para segurança/moderação, suporte e desativação.
legal_info_url String Opcional. Uma URL absoluta que localiza um documento contendo os termos de serviço do plug-in. Esta propriedade é localizável.
privacy_policy_url String Opcional. Uma URL absoluta que localiza um documento que contém a política de privacidade do plug-in. Esta propriedade é localizável.
functions Matriz de objeto de função Opcional. Um conjunto de objetos de função que descrevem as funções disponíveis para o plug-in. Cada nome de objeto de função DEVE ser exclusivo dentro da matriz. A ordem da matriz não é significativa. Se a functions propriedade não estiver presente e houver um runtime de OpenAPI, as funções serão inferidas das operações de OpenAPI.
runtimes Matriz de objeto de Runtime Opcional. Um conjunto de objetos de tempo de execução que descrevem os tempos de execução usados pelo plug-in.
capabilities Objeto de recursos do plug-in Opcional. Descreve os recursos do plug-in.

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.

Propriedade Tipo Descrição
id String Opcional.
name Cadeia de caracteres Obrigatório. Uma cadeia de caracteres que identifica exclusivamente esta função. Os objetos de tempo de execução PODEM fazer referência a esse identificador para associar o tempo de execução à função. Quando a função é associada a um runtime OpenAPI, o valor deve corresponder a um operationId valor na descrição OpenAPI. O valor deve corresponder à ^[A-Za-z0-9_]+$ expressão regular.
description String Opcional. Uma descrição mais adaptada ao modelo, como considerações de comprimento de contexto de token ou uso de palavra-chave para prompting de plug-in aprimorado.
parameters Objeto de parâmetros de função Opcional. Um objeto que contém propriedades que descrevem os parâmetros de uma função de maneira independente do tempo de execução. Ele espelha a forma do json-schema , mas suporta apenas um pequeno subconjunto dos recursos do esquema JSON. Se a propriedade não estiver presente, as parameters funções descritas por um objeto de tempo de execução do tipo OpenApi usarão a descrição do OpenAPI para determinar os parâmetros. Cada membro no objeto JSON é um objeto de parâmetro de função que descreve a semântica do parâmetro.
returns Objeto de retorno OU Objeto de retorno avançado Opcional. Descreve a semântica do valor retornado da função.
states Objeto de estados de função Opcional. Define objetos de estado para estados do orquestrador.
capabilities Objeto de recursos da função Opcional. Contém uma coleção de dados usados para configurar recursos opcionais do orquestrador ao invocar a função.

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.

Propriedade Tipo Descrição
type String Opcional. O tipo de esquema JSON. Tem que ser definida como object.
properties Objeto de propriedades de parâmetros de função Obrigatório. Um objeto que mapeia nomes de parâmetros para suas definições.
required Matriz de cadeias de caracteres Opcional. Os nomes das propriedades que são parâmetros obrigatórios. Ao contrário do esquema JSON, os valores nesta matriz DEVEM corresponder aos nomes listados na properties propriedade.
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.

Propriedade Tipo Descrição
Correspondência de nomes ^[A-Za-z0-9_]+$ Objeto de parâmetro de função Opcional. A definição de parâmetro que corresponde ao parâmetro que corresponde ao nome da propriedade.

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.

Propriedade Tipo Descrição
type Cadeia de caracteres Obrigatório. Especifica o tipo do parâmetro. Os valores possíveis são: string, array, boolean, integer, number.
items Objeto de parâmetro de função Opcional. Um objeto de parâmetro de função que descreve um único elemento em uma matriz. DEVE estar presente apenas quando type estiver array.
enum Matriz de cadeias de caracteres Opcional. Uma matriz de valores válidos para esse parâmetro. DEVE estar presente apenas quando type estiver string.
description String Opcional. Uma descrição do parâmetro.
default Matriz, Booleano, Cadeia de caracteres, Número, Inteiro Opcional. Um valor do tipo especificado pela type propriedade que indica o valor que a API usa quando um valor para um parâmetro opcional não é fornecido.
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.

Propriedade Tipo Descrição
type Cadeia de caracteres Obrigatório. Especifica o tipo do valor retornado pela API. Os valores possíveis são: string.
description String Opcional. Uma descrição do valor retornado pela API.

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.

Propriedade Tipo Descrição
$ref Cadeia de caracteres Obrigatório. Tem que ser definida como https://copilot.microsoft.com/schemas/rich-response-v1.0.json.

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.

Propriedade Tipo Descrição
reasoning Objeto de estado Opcional. O estado no qual o modelo pode chamar funções e fazer cálculos.
responding Objeto de estado Opcional. O estado no qual o modelo pode gerar texto que é mostrado para o usuário. O modelo não pode invocar funções no estado de resposta.
disengaging Objeto de estado Opcional.

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.

Propriedade Tipo Descrição
description String Opcional. Descreve a finalidade de uma função quando usada em um estado de orquestrador específico.
instructions Matriz, Cadeia de Caracteres Opcional. Uma cadeia de caracteres ou uma matriz de cadeias de caracteres que são usadas para fornecer instruções ao orquestrador sobre como usar esta função enquanto estiver em um estado específico do orquestrador. Fornecer uma única cadeia de caracteres indica a intenção de fornecer um conjunto completo de instruções que substituiria quaisquer prompts de função internos. Fornecer uma matriz de cadeias de caracteres indica a intenção de aumentar o mecanismo interno de solicitação de função.
examples Matriz, Cadeia de Caracteres Opcional. Uma cadeia de caracteres ou uma matriz de cadeias de caracteres que são usadas para fornecer exemplos ao orquestrador sobre como essa função pode ser invocada.
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.

Propriedade Tipo Descrição
confirmation Objeto de confirmação Opcional. Descreve uma caixa de diálogo de confirmação que DEVE ser apresentada ao usuário antes de invocar a função.
response_semantics Objeto de semântica de resposta Opcional. Descreve como o orquestrador pode interpretar o conteúdo de resposta e fornecer uma renderização visual.
security_info Objeto de informações de segurança Opcional. Contém atestados sobre o comportamento do plug-in para avaliar os riscos de chamar a função. Se essa propriedade for omitida, a função não poderá interagir com outros plug-ins ou recursos do agente recipiente.

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.

Propriedade Tipo Descrição
type String Opcional. Especifica o tipo de confirmação. Os valores possíveis são: None e AdaptiveCard.
title String Opcional. O título da caixa de diálogo de confirmação. Esta propriedade é localizável.
body String Opcional. O texto da caixa de diálogo de confirmação. Esta propriedade é localizável.
isNonConsequential Booleano Opcional. Indica se a função é não consequente. Quando definida como true, a função é considerada não consequencial, permitindo que os usuários usem a opção "Sempre permitir" durante a confirmação. O valor padrão é false. Para ações OpenAPI: se a ação OpenAPI não for GET, esta propriedade não terá efeito. Se a ação OpenAPI for GET e x-oai-isConsequential estiver definida na especificação OpenAPI, essa propriedade não terá efeito. Se a ação OpenAPI for GET e x-oai-isConsequential não estiver definida na especificação OpenAPI, essa propriedade poderá definir a ação como não consequente.

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.

Propriedade Tipo Descrição
data_path Cadeia de caracteres Obrigatório. Uma consulta JSONPath RFC9535 que identifica um conjunto de elementos da resposta da função a ser renderizada usando o modelo especificado em cada item.
properties Objeto de propriedades de semântica de resposta Opcional. Permite o mapeamento de consultas JSONPath para elementos de dados conhecidos. Cada consulta JSONPath é relativa a um valor de resultado.
static_template Objeto Opcional. Um objeto JSON que está em conformidade com o esquema do Cartão Adaptável e a linguagem de modelagem ou contém uma file propriedade que faz referência a um arquivo que contém o esquema do Cartão Adaptável. Essa instância do Cartão Adaptável é usada para renderizar um resultado da resposta do plug-in. Esse valor será usado se o template_selector não estiver presente ou não for resolvido para um adaptive card. Se estiver usando a opção de referência de arquivo, o valor de DEVE ser um caminho relativo para um arquivo JSON que contém um esquema de file Cartão Adaptável válido. O caminho é relativo ao local do documento de manifesto.
oauth_card_path String Opcional.
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"
        }
      }
    }
  }
}
Exemplo de modelo estático de referência de arquivo
{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.resources",
        "properties": {
          "title": "$.name",
          "subtitle": "$.location",
          "url": "$.href"
        },
        "static_template": {
          "file": "./adaptive-cards/card.json"
        }
      }
    }
  }
}

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.

Propriedade Tipo Descrição
title String Opcional. Título de uma citação para o resultado.
subtitle String Opcional. Legenda de uma citação para o resultado.
url String Opcional. URL de uma citação para o resultado.
thumbnail_url String Opcional. URL de uma imagem em miniatura para o resultado.
information_protection_label String Opcional. Indicador de confidencialidade de dados do conteúdo do resultado.
template_selector String Opcional. Uma expressão JSONPath para uma instância de Cartão Adaptável a ser usada para renderizar o resultado.

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.

Propriedade Tipo Descrição
data_handling Array of String Obrigatório. Uma matriz de cadeias de caracteres que descreve o comportamento de manipulação de dados da função. Os valores válidos são GetPublicData, GetPrivateData, DataTransform, DataExporte ResourceStateUpdate.
Valores de tratamento de dados
Valor Descrição Exemplo
GetPublicData Indica que a função recupera dados de uma fonte externa que não requer autenticação. Uma função que faz uma chamada de serviço para recuperar dados de um site público.
GetPrivateData Indica que a função recupera dados de uma fonte externa que requer autenticação ou do aplicativo atual do usuário. Uma função que obtém dados de um banco de dados privado ou do documento aberto no momento pelo usuário.
DataTransform Indica que a função retorna apenas uma saída com base na entrada, sem introduzir novos dados ou causar uma atualização de recursos. Uma função que converte um número em uma palavra ou formata uma data.
DataExport Indica que a função envia ou grava dados em um local fora da própria função. Uma função que salva dados em um arquivo local ou na nuvem.
ResourceStateUpdate Indica que a função afeta um recurso iniciando uma transação, alterando um processo no mundo real, concedendo ou negando permissões ou executando qualquer outra ação que exija confirmação explícita do usuário. Uma função que reserva um quarto de hotel ou altera o estado de um item de trabalho de active para resolved.

Objeto de tempo de execução

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

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

Propriedade Tipo Descrição
type Cadeia de caracteres Obrigatório. Identifica o tipo de tempo de execução. Os valores válidos são OpenApi, LocalPlugin e RemoteMCPServer.
auth Objeto de autenticação de runtime Obrigatório. Informações de autenticação necessárias para invocar o tempo de execução.
run_for_functions Matriz de cadeias de caracteres Opcional. Os nomes das funções que estão disponíveis neste tempo de execução. Se essa propriedade for omitida, todas as funções descritas pelo runtime estarão disponíveis. Os valores de cadeia de caracteres fornecidos podem conter curingas. Mais de um runtime NÃO DEVE declarar suporte para a mesma função implícita ou explicitamente.
spec Objeto de especificação de OpenAPI, objeto de especificação de ponto de extremidade local ou objeto de especificação de servidor MCP Obrigatório. Contém as informações específicas do runtime necessárias para invocar o runtime.

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.

Propriedade Tipo Descrição
url String Opcional. A URL para buscar a especificação OpenAPI, chamada com uma solicitação GET. Este membro é necessário, a menos que api_description esteja presente.
api_description String Opcional. Uma cadeia de caracteres que contém uma descrição de OpenAPI. Se esse membro estiver presente, url não é necessário e será ignorado se estiver presente.
progress_style String Opcional. O estilo de progresso usado para exibir o progresso da função. Os valores possíveis são: None, ShowUsage, ShowUsageWithInput, ShowUsageWithInputAndOutput.
Exemplo de objeto de especificação de OpenAPI
{
  "runtimes":
  [
    {  
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://example.org/api/openapi.yaml",  
      }
    }
  ]
}  

Objeto de especificação de ponto de extremidade local

Contém informações de ponto de extremidade local necessárias para invocar o tempo de execução.

O objeto de especificação de ponto de extremidade local contém as propriedades a seguir.

Propriedade Tipo Descrição
local_endpoint Cadeia de caracteres Obrigatório. DEVE ser definido como Microsoft.Office.Addin.
allowed_host Matriz de cadeias de caracteres Opcional. Especifica os aplicativos host nos quais o plug-in pode ser executado. Os valores válidos são document, mail, presentatione workbook.

Objeto de especificação de servidor MCP

Contém informações de conexão de servidor MCP (Model Context Protocol) necessárias para invocar o tempo de execução.

O objeto de especificação do servidor MCP contém as propriedades a seguir.

Propriedade Tipo Descrição
url Cadeia de caracteres Obrigatório. A URL do servidor MCP. DEVE ser uma URL absoluta válida.
mcp_tool_description Objeto de descrição da ferramenta MCP Opcional. Contém uma referência a um arquivo de descrição de ferramenta MCP externo ou definições de ferramenta embutidas.
Objeto de descrição da ferramenta MCP

Contém descrições de ferramentas para um servidor MCP.

O objeto de descrição da ferramenta MCP contém as propriedades a seguir.

Propriedade Tipo Descrição
file String Opcional. Um caminho relativo para o arquivo de descrição da ferramenta MCP no pacote do aplicativo. O arquivo DEVE ser um JSON válido contendo descrições de ferramentas que correspondam ao formato retornado pelo método do tools/list servidor MCP. O caminho é relativo ao local do documento de manifesto. NÃO DEVE estar presente se tools estiver presente.
tools Matriz de Objeto Opcional. Uma matriz de definições de ferramentas. A estrutura DEVE corresponder ao formato retornado pelo método do tools/list servidor MCP. Cada objeto de ferramenta DEVE conter name, description, e propriedades inputSchema . NÃO DEVE estar presente se file estiver presente.
Exemplo de objeto de especificação de execução MCP (referência de arquivo)
{
  "runtimes": [
    {
      "type": "RemoteMCPServer",
      "spec": {
        "url": "https://mcp.example.org/",
        "mcp_tool_description": {
          "file": "mcp-tools.json"
        }
      }
    }
  ]
}
Exemplo de objeto de especificação de execução MCP (embutido)
{
  "runtimes": [
    {
      "type": "RemoteMCPServer",
      "spec": {
        "url": "https://mcp.example.org/",
        "mcp_tool_description": {
          "tools": [
            {
              "name": "get_weather",
              "description": "Get current weather for a location",
              "inputSchema": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "The city and state/country"
                  }
                },
                "required": ["location"]
              }
            }
          ]
        }
      }
    }
  ]
}

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.

Propriedade Tipo Descrição
type Cadeia de caracteres Obrigatório. Especifica o tipo de autenticação necessário para invocar uma função. Os valores possíveis são: None, OAuthPluginVault, ApiKeyPluginVault.
reference_id String Opcional. Um valor usado quando type é OAuthPluginVault ou ApiKeyPluginVault. O reference_id valor é adquirido independentemente ao fornecer os valores de configuração de autenticação necessários. Esse mecanismo existe para evitar a necessidade de armazenar valores secretos no manifesto do plug-in.
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.

Propriedade Tipo Descrição
conversation_starters Matriz de objeto inicial de conversa Opcional. Iniciadores de conversa que podem ser exibidos ao usuário para sugestões sobre como invocar o plug-in.

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.

Propriedade Tipo Descrição
text Cadeia de caracteres Obrigatório. O texto do início da conversa. Esta propriedade é localizável.
title String Opcional. O título do iniciador de conversa. Esta propriedade é localizável.
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.4",
  "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": {
        "confirmation": {
          "type": "AdaptiveCard",
          "title": "Search Properties",
          "body": "Search for properties matching your criteria?",
          "isNonConsequential": true
        },
        "response_semantics": {
          "data_path": "$.properties",
          "properties": {
            "title": "$.address",
            "subtitle": "$.price",
            "url": "$.listingUrl",
            "thumbnail_url": "$.imageUrl"
          },
          "static_template": {
            "file": "./adaptivecards/property-card.json"
          }
        },
        "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": {
        "confirmation": {
          "type": "AdaptiveCard",
          "title": "Delete Saved Search",
          "body": "Are you sure you want to delete this saved search?"
        },
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    },
    {
      "name": "getWeather",
      "description": "Get current weather information for a location using MCP server"
    },
    {
      "name": "FillColor",
      "description": "FillColor changes a single cell location to a specific color.",
      "parameters": {
        "type": "object",
        "properties": {
          "Cell": {
            "type": "string",
            "description": "A cell location in the format of A1, B2, etc.",
            "default": "B2"
          },
          "Color": {
            "type": "string",
            "description": "A color in hex format, e.g., #30d5c8",
            "default": "#30d5c8"
          }
        },
        "required": [
          "Cell",
          "Color"
        ]
      },
      "returns": {
        "type": "string",
        "description": "A string indicating the result of the action."
      },
      "states": {
        "reasoning": {
          "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
          "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
        },
        "responding": {
          "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
          "instructions": "If there is no error present, tell the user the cell location and color that was set."
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": {
        "type": "none"
      },
      "run_for_functions": [
        "getListings",
        "saveSearch",
        "deleteSavedSearch"
      ],
      "spec": {
        "url": "http://contoso.com/openapi.yaml"
      }
    },
    {
      "type": "LocalPlugin",
      "run_for_functions": [
        "FillColor"
      ],
      "spec": {
        "local_endpoint": "Microsoft.Office.Addin"
      }
    },
    {
      "type": "RemoteMCPServer",
      "auth": {
        "type": "none"
      },
      "run_for_functions": [
        "getWeather"
      ],
      "spec": {
        "url": "https://weather.contoso.com/mcp",
        "mcp_tool_description": {
          "tools": [
            {
              "name": "getWeather",
              "description": "Get current weather for a location",
              "inputSchema": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "The city and state/country"
                  }
                },
                "required": [
                  "location"
                ]
              }
            }
          ]
        }
      }
    }
  ],
  "logo_url": "http://contoso.com/logo.png",
  "contact_email": "contact@contoso.com",
  "legal_info_url": "https://contoso.com/legal/"
}

Conteúdo relacionado

  • Last updated on