Partilhar via

Escrever um manifesto de habilidades

  • Artigo

APLICA-SE A: SDK v4

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

Este artigo descreve as versões suportadas do esquema de manifesto de habilidades do Bot Framework.

Versão Notas
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 despacho 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 finais que a habilidade fornece.
  • Listas opcionais das atividades que a habilidade pode receber e enviar proativamente.
  • Um objeto de definições opcional que contém esquemas para objetos referenciados por outras partes do documento.
  • Uma lista opcional dos modelos de despacho suportados pela habilidade.

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

Categoria/Campo Tipo/Formato Obrigatório Descrição
Metadados
$id String Necessária O identificador do manifesto de habilidade.
$schema String/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.
direitos de autor String Opcional O aviso de direitos autorais para a habilidade.
descrição String Opcional Uma descrição legível por humanos da habilidade.
iconUrl String/referência de URI Opcional O URI do ícone a ser exibido para a habilidade.
license String Opcional O contrato de licença para a habilidade.
nome Cadeia (de carateres) Necessária O nome da habilidade.
privacidadeUrl String/referência de URI Opcional O URI da descrição de privacidade para a habilidade.
publisherName String Necessária O nome do editor de habilidades.
etiquetas Matriz de cadeias de carateres Opcional Um conjunto de tags para a habilidade. Se estiver presente, cada tag deve ser exclusiva.
versão Cadeia (de carateres) Necessária A versão da habilidade que o manifesto descreve.
Parâmetros de avaliação
pontos finais matriz de pontos finais Obrigatório A lista de pontos de extremidade suportados pela habilidade. Pelo menos um ponto final deve ser definido. Cada ponto de extremidade deve ser exclusivo.
Atividades
atividades Objeto que contém objetos de atividade nomeados Opcional O conjunto de atividades iniciais aceitas pela habilidade.
atividadesEnviado Objeto que contém objetos de atividade nomeados Opcional Descreve as atividades proativas que a habilidade pode enviar.
Definições
Definições Objeto Opcional Um objeto que contém subesquemas para objetos usados no manifesto.
Modelos de expedição
dispatchModels [en] objeto dispatchModels Opcional Descreve os modelos de linguagem e as intenções de nível superior suportadas pela habilidade. Consulte Modelos de despacho para o esquema deste objeto.

Pontos finais

Cada objeto de ponto de extremidade descreve um ponto de extremidade suportado pela 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 de ponto de extremidade

Descreve um ponto de extremidade suportado pela habilidade.

Campo Tipo/Formato Obrigatório Descrição
descrição String Opcional Uma descrição do parâmetro de avaliação.
endpointUrl String/URI Obrigatório O ponto de extremidade URI para a habilidade.
msAppId String Necessária O Microsoft AppId (GUID) para a habilidade, usado 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}$.
nome Cadeia (de carateres) Necessária O nome exclusivo para o ponto de extremidade.
protocolo String Opcional O protocolo Bot suportado. 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 tarefa com base na atividade inicial que recebe. O nome associado ao objeto de atividade indica a ação ou tarefa que a habilidade executará.

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

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

Aqui está uma descrição de atividade de exemplo.

"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 seu campo de nome, que é significativo dentro do escopo da habilidade.

Campo Tipo Necessário Descrição
descrição String Opcional Uma descrição da ação que o evento deve iniciar.
nome Cadeia (de carateres) Necessária O valor da propriedade name da atividade de evento.
resultadoValor Objeto Opcional Uma definição de esquema JSON do tipo de objeto que a ação pode retornar.
tipo String Necessária O tipo de atividade. Deve ser "evento".
valor Objeto Opcional Uma definição de esquema JSON do tipo de objeto que esta 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 seu campo de nome, que é significativo dentro do escopo da habilidade.

Campo Tipo Necessário Descrição
descrição String Opcional Uma descrição da ação que a invocação deve iniciar.
nome Cadeia (de carateres) Necessária O valor da propriedade name da atividade de invocação.
resultadoValor Objeto Opcional Uma definição de esquema JSON do tipo de objeto que a ação associada pode retornar.
tipo String Necessária O tipo de atividade. Deve ser "invocar".
valor Objeto Opcional Uma definição de esquema JSON do tipo de objeto que esta ação espera como entrada.

objeto messageActivity

Descreve uma atividade de mensagem aceita ou enviada pela habilidade. A propriedade text da atividade de mensagem contém a expressão do usuário ou bot.

Campo Tipo Necessário Descrição
descrição String Opcional Uma descrição da ação.
resultadoValor Objeto Opcional Uma definição de esquema JSON do tipo de objeto que a ação associada pode retornar.
tipo String Necessária O tipo de atividade. Deve ser "mensagem".
valor Objeto Opcional Uma definição de esquema JSON do tipo de objeto que esta ação espera como entrada.

outroObjeto Atividades

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

Campo Tipo Necessário Descrição
tipo String Necessária O tipo de atividade. Deve ser um dos outros tipos de atividade 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 de manifesto de habilidade não define seu significado.

Definições

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

Aqui está um subesquema de exemplo 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 despacho contém uma lista de modelos de linguagem e uma lista de intenções de nível superior suportadas pela habilidade. É um recurso avançado para permitir que um desenvolvedor de um consumidor de habilidades componha um modelo de linguagem que combina os recursos do consumidor e bots de habilidades.

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

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

Campo Tipo Necessário Descrição
intenções Matriz de cadeias de carateres Opcional Uma lista das intenções de nível superior suportadas pela habilidade. Cada intenção deve ser única.
Idiomas  Objeto que contém matrizes languageModel nomeadas Opcional Uma lista dos modelos de linguagem suportados pela habilidade. Cada nome é a localidade para a qual os modelos de idioma se destinam, e a matriz contém os modelos de idioma para essa localidade. Um modelo de despacho deve suportar pelo menos uma localidade. Cada localidade dentro do campo idiomas deve ser exclusiva.

Aqui está um modelo de despacho de exemplo que contém dois modelos de idiomas em três localidades. Ele também descreve duas intenções de alto nível que a habilidade pode reconhecer.

"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 uma determinada cultura. O nome é um nome de localidade.

Campo Tipo/Formato Obrigatório Descrição
contentType String Necessária Tipo do modelo de linguagem.
descrição String Opcional Uma descrição do modelo de linguagem.
nome Cadeia (de carateres) Necessária Nome do modelo de linguagem.
URL String/referência de URI Obrigatório A URL do modelo de idioma.

Exemplo de manifesto

Aqui está 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óximos passos