Escrever um manifesto de habilidade

  • Artigo

APLICA-SE A: SDK v4

Um manifesto de habilidade é um arquivo JSON que descreve as ações que uma habilidade pode executar, seus parâmetros de entrada e saída e os pontos de extremidade da habilidade. O manifesto contém as informações legíveis por computador que um desenvolvedor pode usar para acessar a habilidade por meio de outro bot.

Este artigo descreve as versões compatíveis do esquema de manifesto de habilidade do Bot Framework.

Versão Observações
versão 2.2 Atualizadas algumas propriedades de URI para aceitar referências de URI.
versão 2.1 Adiciona a capacidade de descrever atividades proativas que a habilidade pode enviar e os modelos de expedição que a habilidade usa.
versão 2.0 versão inicial.

Os esquemas de manifesto de habilidade do Bot Framework usam o rascunho 7 do vocabulário do esquema JSON.

Pré-requisitos

O manifesto de habilidades

O manifesto de habilidades contém diferentes categorias de informações:

  • Metadados que descrevem a habilidade em um nível geral.
  • Uma lista dos pontos de extremidade fornecidos pela habilidade.
  • Listas opcionais das atividades que a habilidade pode receber e enviar de maneira proativa.
  • Um objeto de definições opcional que contém esquemas para os objetos referenciados por outras partes do documento.
  • Uma lista opcional dos modelos de expedição aos quais a habilidade dá suporte.

A tabela a seguir descreve o esquema completo da v2.2 do manifesto de habilidade do Bot Framework.

Categoria/Campo Tipo/Formato Obrigatório Descrição
Metadados
$id String Obrigatório O identificador do manifesto de habilidades.
$schema Sequência/URI Obrigatório O URI HTTPS de um recurso de esquema JSON que descreve o formato do manifesto. Para a versão 2.2, o URI é https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
copyright String Opcional A notificação de direitos autorais da habilidade.
descrição String Opcional Uma descrição legível da habilidade.
iconUrl Sequência/URI-referência Opcional O URI do ícone a ser mostrado para a habilidade.
license String Opcional O contrato de licença da habilidade.
name String Obrigatório O nome da habilidade.
privacyUrl Sequência/URI-referência Opcional O URI da descrição de privacidade da habilidade.
publisherName String Obrigatório O nome do editor de habilidades.
marcas Matriz de cadeia de caracteres Opcional Um conjunto de marcas para a habilidade. Se ele estiver presente, cada marca precisará ser exclusiva.
version String Obrigatório A versão da habilidade descrita pelo manifesto.
Pontos de extremidade
pontos de extremidade matriz de ponto de extremidade Obrigatório A lista de pontos de extremidade compatível com a habilidade. Pelo menos um ponto de extremidade precisa ser definido. Cada ponto de extremidade precisa ser exclusivo.
Atividades
atividades Objeto que contém objetos de atividade nomeados Opcional O conjunto de atividades iniciais aceitas pela habilidade.
activitiesSent Objeto que contém objetos de atividade nomeados Opcional Descreve as atividades proativas que podem ser enviadas pela habilidade.
Definições
definitions Objeto Opcional Um objeto que contém subesquemas para os objetos usados no manifesto.
Modelos de expedição
dispatchModels Objeto dispatchModels Opcional Descreve os modelos de linguagem e as intenções de nível superior compatíveis com a habilidade. Confira Modelos de expedição para obter o esquema desse objeto.

Pontos de extremidade

Cada objeto de ponto de extremidade descreve um ponto de extremidade compatível com a habilidade.

Este exemplo lista dois pontos de extremidade para uma habilidade.

"endpoints": [
    {
        "name": "americas",
        "protocol": "BotFrameworkV3",
        "description": "Production endpoint for SkillBot in the Americas",
        "endpointUrl": "http://myskill.contoso.com/api/messages",
        "msAppId": "00000000-0000-0000-0000-000000000000"
    },
    {
        "name": "eu",
        "protocol": "BotFrameworkV3",
        "description": "Production endpoint for SkillBot in Europe",
        "endpointUrl": "http://myskill.contoso.com/api/messages",
        "msAppId": "11111111-0000-0000-0000-000000000000"
    }
],

Objeto endpoint

Descreve um ponto de extremidade compatível com a habilidade.

Campo Tipo/Formato Obrigatório Descrição
descrição String Opcional Uma descrição do ponto de extremidade.
endpointUrl Sequência/URI Obrigatório O ponto de extremidade do URI da habilidade.
msAppId String Obrigatório A ID do Aplicativo (GUID) da Microsoft da habilidade, usada para autenticar solicitações. Deve corresponder à expressão regular: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$.
name String Obrigatório O nome exclusivo do ponto de extremidade.
protocolo String Opcional Protocolo do Bot compatível. O padrão é “BotFrameworkV3”, que representa a API do Bot Connector versão 3. Use o valor padrão, a menos que sua habilidade use especificamente um protocolo diferente.

Atividades

Cada objeto de atividade descreve uma atividade aceita pela habilidade. A habilidade inicia uma ação ou uma tarefa com base na atividade inicial que ela recebe. O nome associado ao objeto de atividade indica a ação ou a tarefa que a habilidade executará.

Alguns tipos de atividades têm uma propriedade de valor que pode ser usada para fornecer entrada extra para a habilidade. Quando a habilidade é encerrada (conclui a ação), ela pode fornecer um valor retornado na propriedade de valor da atividade de fim de conversa associada.

Os tipos de atividade permitidos são: mensagem, evento, invocação e outras atividades. Uma habilidade pode receber uma atividade de invocação, mas não pode enviar uma.

Veja um exemplo de descrição da atividade.

"bookFlight": {
    "description": "Books a flight",
    "type": "event",
    "name": "BookFlight",
    "value": {
        "$ref": "#/definitions/bookingInfo"
    },
    "resultValue": {
        "$ref": "#/definitions/bookingInfo"
    }
},

Objeto eventActivity

Descreve uma atividade de evento aceita ou enviada pela habilidade. O significado de uma atividade de evento é definido pelo campo do nome, que é significativo dentro do escopo da habilidade.

Campo Type Obrigatória Descrição
descrição String Opcional Uma descrição da ação que o evento deve iniciar.
name String Obrigatório O valor da propriedade de nome da atividade de evento.
resultValue Objeto Opcional Uma definição de esquema JSON do tipo de objeto que a ação pode retornar.
tipo String Obrigatório O tipo de atividade. Precisa ser "event".
value Objeto Opcional Uma definição de esquema JSON do tipo de objeto que essa ação espera como entrada.

Objeto invokeActivity

Descreve uma atividade de invocação aceita pela habilidade. O significado de uma atividade de invocação é definido pelo campo do nome, que é significativo dentro do escopo da habilidade.

Campo Type Obrigatória Descrição
descrição String Opcional Uma descrição da ação que a invocação deve iniciar.
name String Obrigatório O valor da propriedade de nome da atividade de invocação.
resultValue Objeto Opcional Uma definição de esquema JSON do tipo de objeto que a ação associada pode retornar.
tipo String Obrigatório O tipo de atividade. Precisa ser "invoke".
value Objeto Opcional Uma definição de esquema JSON do tipo de objeto que essa ação espera como entrada.

Objeto messageActivity

Descreve uma atividade de mensagem aceita ou enviada pela habilidade. A propriedade de texto da atividade de mensagem contém o enunciado do usuário ou do bot.

Campo Type Obrigatória Descrição
descrição String Opcional Uma descrição da ação.
resultValue Objeto Opcional Uma definição de esquema JSON do tipo de objeto que a ação associada pode retornar.
tipo String Obrigatório O tipo de atividade. Precisa ser "message".
value Objeto Opcional Uma definição de esquema JSON do tipo de objeto que essa ação espera como entrada.

Objeto otherActivities

Descreve qualquer outro tipo de atividade aceita ou enviada pela habilidade.

Campo Type Obrigatória Descrição
type String Obrigatório O tipo de atividade. Precisa ser um dos outros tipos de atividades do Bot Framework: “contactRelationUpdate”, “conversationUpdate”, “deleteUserData”, “endOfConversation”, “handoff”, “installationUpdate”, “messageDelete”, “messageReaction”, “messageUpdate”, “suggestion”, “trace” ou “typing”.

O objeto otherActivities pode incluir outras propriedades, mas o esquema do manifesto de habilidade não define o significado delas.

Definições

Cada definição descreve um subesquema que pode ser consumido por outras partes do documento.

Veja um exemplo de subesquema para informações de reserva de voo.

"bookingInfo": {
    "type": "object",
    "required": [
        "origin"
    ],
    "properties": {
        "origin": {
            "type": "string",
            "description": "this is the origin city for the flight"
        },
        "destination": {
            "type": "string",
            "description": "this is the destination city for the flight"
        },
        "date": {
            "type": "string",
            "description": "The date for the flight in YYYY-MM-DD format"
        }
    }
},

Modelos de expedição

O modelo de expedição contém uma lista de modelos de linguagem e uma lista de intenções de nível superior compatível com a habilidade. É um recurso avançado para permitir que um desenvolvedor de um consumidor de habilidades crie um modelo de linguagem que combine os recursos dos bots de consumidor e de habilidades.

Cada modelo de linguagem usa o formato de arquivo .lu ou .qna. Para obter mais informações sobre esses formatos, confira Formato de arquivo .lu e Formato de arquivo .qna.

Um nome de localidade é uma combinação de um código de cultura em letras minúsculas ISO 639 associado a um idioma e um código de subcultura em letras maiúsculas ISO 3166 opcional associado a um país ou uma região, por exemplo, "en" ou "en-US".

Campo Type Obrigatória Descrição
intenções Matriz de cadeia de caracteres Opcional Uma lista das intenções de nível superior compatíveis com a habilidade. Cada intenção precisa ser exclusiva.
idiomas Objeto que contém matrizes languageModel nomeadas Opcional Uma lista dos modelos de linguagem compatíveis com a habilidade. Cada nome é a localidade à qual os modelos de linguagem se referem e a matriz contém os modelos de linguagem desta localidade. Um modelo de expedição precisa dar suporte a, pelo menos, uma localidade. Cada localidade dentro do campo de linguagens precisa ser exclusiva.

Veja um exemplo de modelo de expedição que contém dois modelos de linguagem em três localidades. Ele também descreve duas intenções de nível superior que podem ser reconhecidas pela habilidade.

"dispatchModels": {
    "languages": {
        "en": [
            {
                "name": "SkillBot LU (English)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-en.lu",
                "description": "English language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (English)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-en.qna",
                "description": "English language model for the skill (QnAMaker)"
            }
        ],
        "es-ES": [
            {
                "name": "SkillBot LU (Spanish-Spain)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-es-ES.lu",
                "description": "Spanish (Spain) language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (Spanish-Spain)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-es-ES.qna",
                "description": "Spanish (Spain) language model for the skill (QnAMaker)"
            }
        ],
        "es-MX": [
            {
                "name": "SkillBot LU (Spanish-Mexico)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-es-MX.lu",
                "description": "Spanish (Mexico) language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (Spanish-Mexico)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-es-MX.qna",
                "description": "Spanish (Mexico) language model for the skill (QnAMaker)"
            }
        ]
    },
    "intents": [
        "bookFlight",
        "getWeather"
    ]
},

Objeto languageModel

Descreve um modelo de linguagem para determinada cultura. O nome é um nome de localidade.

Campo Tipo/Formato Obrigatório Descrição
contentType String Obrigatório Tipo do modelo de linguagem.
descrição String Opcional Uma descrição do modelo de linguagem.
name String Obrigatório Nome do modelo de linguagem.
url Sequência/URI-referência Obrigatório A URL do modelo de linguagem.

Exemplo de manifesto

Veja um exemplo completo de manifesto v2.2 para uma habilidade que expõe várias atividades.

{
    "$schema": "https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json",
    "$id": "SkillBot",
    "name": "Sample skill definition that can handle multiple types of activities",
    "version": "1.0",
    "description": "This is a sample skill definition for multiple activity types",
    "publisherName": "Microsoft",
    "privacyUrl": "https://myskill.contoso.com/privacy.html",
    "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
    "license": "",
    "iconUrl": "skillIcon.png",
    "tags": [
        "sample",
        "travel",
        "weather"
    ],
    "endpoints": [
        {
            "name": "americas",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for SkillBot in the Americas",
            "endpointUrl": "http://myskill.contoso.com/api/messages",
            "msAppId": "00000000-0000-0000-0000-000000000000"
        },
        {
            "name": "eu",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for SkillBot in Europe",
            "endpointUrl": "http://myskill.contoso.com/api/messages",
            "msAppId": "11111111-0000-0000-0000-000000000000"
        }
    ],
    "dispatchModels": {
        "languages": {
            "en": [
                {
                    "name": "SkillBot LU (English)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-en.lu",
                    "description": "English language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (English)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-en.qna",
                    "description": "English language model for the skill (QnAMaker)"
                }
            ],
            "es-ES": [
                {
                    "name": "SkillBot LU (Spanish-Spain)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-es-ES.lu",
                    "description": "Spanish (Spain) language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (Spanish-Spain)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-es-ES.qna",
                    "description": "Spanish (Spain) language model for the skill (QnAMaker)"
                }
            ],
            "es-MX": [
                {
                    "name": "SkillBot LU (Spanish-Mexico)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-es-MX.lu",
                    "description": "Spanish (Mexico) language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (Spanish-Mexico)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-es-MX.qna",
                    "description": "Spanish (Mexico) language model for the skill (QnAMaker)"
                }
            ]
        },
        "intents": [
            "bookFlight",
            "getWeather"
        ]
    },
    "activities": {
        "bookFlight": {
            "description": "Books a flight",
            "type": "event",
            "name": "BookFlight",
            "value": {
                "$ref": "#/definitions/bookingInfo"
            },
            "resultValue": {
                "$ref": "#/definitions/bookingInfo"
            }
        },
        "getWeather": {
            "description": "Retrieves and returns the weather for the user's location",
            "type": "invoke",
            "name": "GetWeather",
            "value": {
                "$ref": "#/definitions/location"
            },
            "resultValue": {
                "$ref": "#/definitions/weatherReport"
            }
        },
        "message": {
            "type": "message",
            "description": "Receives the user's' utterance and attempts to resolve it using the skill's LU models"
        },
        "typing": {
            "type": "typing"
        },
        "conversationUpdate": {
            "type": "conversationUpdate"
        }
    },
    "definitions": {
        "localeValue": {
            "type": "object",
            "properties": {
                "locale": {
                    "type": "string",
                    "description": "The current user's locale ISO code"
                }
            }
        },
        "bookingInfo": {
            "type": "object",
            "required": [
                "origin"
            ],
            "properties": {
                "origin": {
                    "type": "string",
                    "description": "this is the origin city for the flight"
                },
                "destination": {
                    "type": "string",
                    "description": "this is the destination city for the flight"
                },
                "date": {
                    "type": "string",
                    "description": "The date for the flight in YYYY-MM-DD format"
                }
            }
        },
        "weatherReport": {
            "type": "array",
            "description": "Array of forecasts for the next week.",
            "items": [
                {
                    "type": "string"
                }
            ]
        },
        "location": {
            "type": "object",
            "description": "Location metadata",
            "properties": {
                "latitude": {
                    "type": "number",
                    "title": "Latitude"
                },
                "longitude": {
                    "type": "number",
                    "title": "Longitude"
                },
                "postalCode": {
                    "type": "string",
                    "title": "Postal code"
                }
            }
        }
    },
    "activitiesSent": {
        "flightUpdated": {
            "type": "event",
            "name": "FlightUpdated",
            "description": "Event which is sent by the skill when there is an update in flight info",
            "value": {
                "type": "object",
                "description": "Flight update information",
                "properties": {
                    "flightNumber": {
                        "type": "string"
                    },
                    "departureDate": {
                        "type": "string",
                        "description": "The departure date for the flight in YYYY-MM-DD format"
                    },
                    "departureTime": {
                        "type": "string",
                        "description": "The departure time for the flight in HH-MM format"
                    }
                }
            }
        }
    }
}

Próximas etapas