Crie seus próprios plug-ins personalizados

Artigo
05/17/2024

Importante

Algumas informações neste artigo estão relacionadas ao produto pré-lançado que pode ser modificado substancialmente antes de ser lançado comercialmente. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.

Dica

Se você precisar de ajuda com os plug-ins que não são da Microsoft, consulte sua documentação e suporte técnico.

Criando novos plug-ins

Dependendo de como os administradores configuram o Copilot para Segurança, você poderá criar novos plug-ins executando as seguintes etapas:

Crie um plug-in da lista de plug-ins com suporte.
Crie um arquivo de manifesto do plug-in YAML ou JSON, que descreve metadados sobre o plug-in e como invocá-lo.
Publique o manifesto do plug-in no Copilot para Segurança.

Requisitos de plug-in

Cada plug-in do Copilot para Segurança requer um arquivo de manifesto formatado em YAML ou JSON (por exemplo: plugin.yaml ou plugin.json) que descreve metadados sobre o conjunto de habilidades e como invocar as habilidades.

Um manifesto consiste de duas chaves de nível superior necessárias, Descriptor e SkillGroups, todas com pares de subchave ou valor e campos obrigatórios/opcionais, dependendo do formato de habilidade.

Para obter informações sobre plug-ins do OpenAI, consulte Introdução.

Resumo do campo descritor

Campo	Tipo	Descrição	Obrigatório
`Name`	string	Nome interno do Plug-in. Não permite `/ \ ? # @`.	Sim
`DisplayName`	string	Nome legível por humanos do plug-in.	Recomendado
`Description`	string	Descrição legível do plug-in.	Sim
`DescriptionDisplay`	string	Descrição alternativa legível do plug-in se a Descrição não for especificada.	Não
`Category`	string	Observação: atualmente, esse valor é forçado a `Plugin` durante o processo de carregamento do plug-in personalizado.	Não
`Prerequisites`	string		Não
`Icon`	cadeia de caracteres	URL usada para buscar o ícone principal do Conjunto de Habilidades.	Recomendado

Resumo do campo SkillGroups

Consiste em uma lista de grupos de habilidades, incluindo Format, Settings e Skills.

Campo	Tipo	Descrição	Obrigatório
`Format`	string	Consulte a seção Formatar para obter as opções disponíveis.	Sim
`Settings`	objeto	Consulte a seção Configurações para obter a estrutura do objeto.	Sim, para formatos: `API`, `DOTNET`, `CONTAINER`
`Skills`	objeto	Consulte a seção Habilidades para obter a estrutura do objeto.	Sim, para formatos: `GPT`, `DOTNET`, `KQL`, `LogicApp`

Formato (campo SkillGroups)

Opções do campo Format:

API
GPT
KQL

Configurações (campo SkillGroups)

Estrutura do objeto do campo Settings.

Campo	Tipo	Descrição	Obrigatório
`OpenApiSpecUrl`	string	URL para especificação pública de OpenAPI.	Sim
`EndpointUrl`	cadeia de caracteres	URL do ponto de extremidade público.	Não

Habilidades (campo SkillGroups)

Estrutura do objeto do campo Skills.

Campo	Tipo	Descrição	Obrigatório
`Description`	string	Descrição legível para essa habilidade.	Recomendado
`DescriptionForModel`	cadeia de caracteres	Descrição detalhada da habilidade usada para seleção de habilidades	Não
`Inputs`	objeto	Lista dos objetos `Name`, `Description`, `Required` e `DefaultValue` (opcional) da entrada do usuário na habilidade.
`Settings`	objeto	Configurações personalizadas com base no Formato de habilidade.

Diferenças entre o OpenAI e os manifestos do Copilot para Segurança

Plug-ins OpenAI criados seguindo a documentação do plug-in ChatGPT normalmente usam um formato de manifesto diferente do formato de manifesto do Copilot para Segurança. O Copilot para Segurança dá suporte a ambos os formatos.

Quando carregado, o manifesto do plug-in OpenAI é convertido no manifesto do Copilot para Segurança.

Observação

Os detalhes de mapeamento, especialmente em relação às restrições nas anotações, podem ser alterados no futuro. Atualmente, a plataforma dá suporte apenas a plug-ins nas versões 3.0 ou 3.0.1 do OpenAPI.

Mapeamento de campo de plug-in

Campo plug-in	Tipo	Campo descritor	Obrigatório	Observações
`schema_version`	string		Não	É a versão do esquema de manifesto OpenAI, por exemplo, "v1". Não usado no momento.
`name_for_model`	string	Nome	Sim	Restrito ao comprimento de 100 caracteres. Nome interno do conjunto de habilidades. Não permite `/ \ ? #`.
`name_for_human`	string	DisplayName	Sim	Nome legível por humanos do plug-in. Restrito ao comprimento de 40 caracteres.
`description_for_model`	string	Descrição	Sim	Restrito ao comprimento de 16.000 caracteres. Descrição interna para uso com LLM.
`description_for_human`	string	DescriptionDisplay	Sim	Descrição legível do plug-in. Restrito ao comprimento de 200 caracteres.
`logo_url`	cadeia de caracteres	Ícone	Recomendado	URL usada para buscar o ícone principal do Plug-in.
`contact_email`	string		Não	Contato de email para o plug-in. Não usado no momento.
`legal_info_url`	string		Não	Link para informações de plug-in. Não usado no momento.
`api`	objeto	Consulte a seção API do plug-in para obter a estrutura de objetos	Sim
`auth`	objeto		Sim	`authorization_type` está restrito a `bearer`. Detalhes a serem seguidos relativos ao suporte a diferentes autenticações `type` como none, oauth, api_key, aad, aad_delegated.

Plug-in (campo de API)

Estrutura do objeto do campo api

Campo	Tipo	Descrição	Obrigatório
`type`	string	O único tipo com suporte atualmente é `openapi`.	Sim
`url`	cadeia de caracteres	Link para o documento de Especificação do OpenAPI da API.	Sim

Diretrizes de criação de plug-in

Há muitas considerações sobre a criação de plug-in. Este documento destina-se a capturar algumas das diretrizes e práticas recomendadas para escrever plug-ins para o Copilot para Segurança.