Configurar habilidades para uso em agentes do Copilot Studio

O Copilot Studio permite que você estenda seu agente usando habilidades. Se você já tiver agentes criados e implantados em sua organização (usando o SDK de Agentes do Microsoft 365 ou outras ferramentas pró-código) para cenários específicos, você poderá converter esses bots em uma habilidade e registrar essa habilidade em um agente do Copilot Studio.

Note

Para adicionar uma habilidade no aplicativo Copilot Studio no Microsoft Teams, você deve ter uma assinatura Microsoft Copilot Studio autônoma.

Este artigo destina-se a administradores de sistema ou profissionais de TI familiarizados com as habilidades.

Depois de registrar uma habilidade com um agente do Copilot Studio, você pode disparar as ações de habilidade na conversa sem problemas.

Pré-requisitos

Importante

Os agentes do Copilot Studio só dão suporte a habilidades criadas usando o SDK do Legacy Bot Framework versão 4.12.0+ e o SDK do Microsoft 365 Agents v1.0.0+. Novas habilidades devem ser criadas usando SDK de Agentes do Microsoft 365.

Para configurar uma skill, defina o registro do aplicativo associado no Microsoft Entra ID para que a skill tenha uma configuração de locatário único.

Quando usar fluxos ou habilidades do agente

A tabela a seguir ajuda você a determinar quando usar fluxos de agente ou habilidades para uma conversa.

Fator Quando usar fluxos de agentes Quando usar habilidades
Persona Os criadores de agente podem criar fluxos reutilizáveis para inseri-los em qualquer conversa do agente. Os desenvolvedores podem criar, implantar e hospedar habilidades personalizadas em seu próprio ambiente.
Tipo de conversação Use fluxos para operações simples de um turno. Por exemplo, fazer um pedido ou obter o status do pedido. Use habilidades para operações complexas de múltiplas etapas. Por exemplo, agendar uma reunião ou reservar um voo.
Resposta Use fluxos para emitir uma resposta do agente. Por exemplo, mostrar uma mensagem personalizada ou imagens integradas. Use habilidades para emitir qualquer resposta de agente compatível. Por exemplo, mostre um cartão adaptável ou envie respostas aleatórias.
Ações Use fluxos para disparar ações de turno único no servidor. Por exemplo, chame uma API HTTP ou dispare um conector personalizado. Use habilidades para disparar eventos e ações do lado do servidor e do cliente. Por exemplo, acesse uma página após a resposta do agente.

Configurar uma habilidade

Primeiro, use o Copilot Studio para criar um agente e criar e implantar uma skill usando ferramentas de programação avançada em sua organização. Consulte estes exemplos:

Antes de registrar a habilidade, forneça a ID do agente ao desenvolvedor de habilidades para autorizar o agente a chamar ações na habilidade. Saiba mais sobre a lista de permissão para uma habilidade. Você pode obter a ID do agente na janela Adicionar uma habilidade.

Para adicionar uma habilidade ao seu agente:

  1. Vá para o seu agente.

  2. Selecione Configurações>Habilidades para ir até a página de habilidades.

  3. Selecione Adicionar uma habilidade.

  4. Copie o ID do agente. Você precisa fornecer o ID do agente para o seu desenvolvedor de habilidades.

  5. Insira a URL para o manifesto da habilidade. O manifesto de uma habilidade contém as informações necessárias para seu agente disparar ações dentro de uma habilidade.

  6. Selecione Avançar para iniciar o processo de validação. Uma vez que a validação é bem-sucedida, sua habilidade é adicionada ao seu agente. Agora você pode usar essa habilidade em seus tópicos.

Considerações de conformidade

Para proteger a privacidade do usuário, precisamos que as habilidades sejam registradas como um aplicativo no locatário Microsoft Entra ID do usuário conectado.

Solucionar erros durante o registro de habilidades

O sistema executa uma série de verificações de validação na URL. Essas verificações garantem a conformidade, a governança e a usabilidade da habilidade que você está adicionando ao seu agente. Você deve corrigir esses erros antes de registrar uma habilidade.

Mensagem de erro Solucionar problemas/mitigação
Tivemos problemas para conseguir o manifesto de habilidades.
(MANIFEST_FETCH_FAILED)		 Tente abrir a URL do seu manifesto em um navegador da Web. Se o URL renderizar a página em 10 segundos, registre novamente a habilidade.
O manifesto é incompatível.
(MANIFEST_MALFORMED)		 (a) Verifique se o manifesto é um arquivo JSON válido.
(b) Verificar se o manifesto contém propriedades exigidas
Por exemplo, (name, msaAppId, single endpoint, activities/id, activities/description,activities/type (apenas event ou message suportado)).
Há um descompasso nos seus endpoints
(MANIFEST_ENDPOINT_ORIGIN_MISMATCH)		 Verifique se o endpoint da sua habilidade corresponde ao campo Publisher domain (preferencial) ou Home page URL no registro do aplicativo Microsoft Entra ID. Saiba mais sobre como definir a página inicial para endereços terminais.
Para adicionar uma habilidade, ela deve primeiro ser registrada
(APPID_NOT_IN_TENANT)		 Verifique se o ID do aplicativo da sua habilidade está registrado no tenant Microsoft Entra ID da sua organização.
O link não é válido; O link deve começar com https://
(URL_MALFORMED, URL_NOT_HTTPS)		 Revise o link para adicionar uma URL segura.
O manifesto é grande demais;
(MANIFEST_TOO_LARGE)		 Verifique o tamanho do manifesto. Ele deve ser menor ou igual a 500 KB.
Esta habilidade já foi adicionada ao seu agente.
(MANIFEST_ALREADY_IMPORTED)		 Exclua a habilidade e tente registrá-la novamente.
A habilidade está limitada a 100 ações.
(LIMITS_TOO_MANY_ACTIONS)		 Existem muitas ações de habilidade definidas no manifesto da habilidade. Remova as ações e tente novamente.
As ações são limitadas a 25 entradas.
(LIMITS_TOO_MANY_INPUTS)		 Existem muitos parâmetros de entrada de ação da habilidade. Remova os parâmetros e tente novamente.
As ações são limitadas a 25 resultados.
(LIMITS_TOO_MANY_OUTPUTS)		 Existem muitos parâmetros de saída de ação de habilidade. Remova os parâmetros e tente novamente.
Seu agente pode ter, no máximo, 100 habilidades.
(LIMITS_TOO_MANY_SKILLS)		 Existem demasiadas habilidades atribuídas a um agente. Remova uma habilidade existente e tente novamente.
Parece que algo deu errado.
(AADERROR_OTHER)		 Ocorreu um erro transitório ao validar sua habilidade. Tente novamente.
Ocorreu um erro ao verificar sua habilidade.
(ENDPOINT_HEALTHCHECK_FAILED, HEALTH_PING_FAILED)		 Verifique se o ponto de extremidade de sua habilidade está online e respondendo a mensagens. Verifique também se o registro do aplicativo da habilidade de locatário único tenha sido implantado no mesmo locatário.
Essa habilidade não permitiu listar seu agente
(ENDPOINT_HEALTHCHECK_UNAUTHORIZED)		 Verifique se o agente foi adicionado à lista de permissões de habilidades.
  • Last updated on