Partilhar via

Configurar uma capacidade para utilização em agentes do Copilot Studio

O Copilot Studio permite-lhe expandir o seu agente usando capacidades. Se já tiver agentes criados e com implementação na sua organização (usando o SDK de Agentes do Microsoft 365 ou outras ferramentas de código profissional) para cenários específicos, pode converter esses bots numa capacidade e registar essa capacidade num agente do Copilot Studio.

Nota

Para adicionar uma capacidade dentro da aplicação Copilot Studio no Microsoft Teams, deve ter uma subscrição autónoma do Microsoft Copilot Studio.

Este artigo destina-se a administradores de sistemas ou profissionais de TI que estejam familiarizados com competências do .

Depois de registar uma capacidade com um agente do Copilot Studio, pode facilmente acionar ações de capacidade na conversação.

Pré-requisitos

Importante

Os agentes do Copilot Studio suportam apenas capacidades desenvolvidas usando o SDK do Bot Framework Legado versão 4.12.0+ e o SDK de Agentes do Microsoft 365 v1.0.0+. Novas capacidades devem ser desenvolvidas usando o SDK de Agentes do Microsoft 365.

Para configurar uma capacidade, defina o registo associado da aplicação no Microsoft Entra ID para a sua capacidade como configuração de inquilino único.

Quando usar fluxos de agentes vs capacidades

A tabela seguinte ajuda a determinar quando usar fluxos ou capacidades de agente para uma conversação.

Fator Quando usar fluxos de agentes Quando utilizar capacidades
Persona Os criadores de agentes podem construir fluxos reutilizáveis para incorporar em qualquer conversação de agente. Os programadores podem criar, implementar e alojar capacidades personalizadas no seu próprio ambiente.
Tipo de conversação Utilize fluxos para operações simples e de turno único. Por exemplo, faça um pedido ou obtenha o estado da encomenda. Use competências para operações multiturnos complexas. Por exemplo, marcar uma reunião ou reservar um voo.
Resposta Utilize fluxos para emitir uma resposta do agente. Por exemplo, mostrar uma mensagem personalizada ou imagens inline. Utilize capacidades para emitir qualquer resposta de agente suportada. Por exemplo, mostrar um cartão adaptativo ou enviar respostas aleatórias.
Ações Utilize fluxos para acionar ações de turno único do lado do servidor. Por exemplo, chamar uma API HTTP ou acionar um conector personalizado. Use competências para acionar eventos e ações do lado do servidor e do lado do cliente. Por exemplo, navegue para uma página após resposta do agente.

Configurar uma capacidade

Primeiro, utilize o Copilot Studio para criar um agente e criar e implementar uma capacidade usando ferramentas pró-código na sua organização. Consulte estes exemplos:

Antes de registar a capacidade, forneça o ID do agente ao seu programador de capacidades para autorizar que o agente chame ações na capacidade. Saiba mais sobre a lista de autorizados da capacidade. Pode obter o ID do agente na janela Adicionar uma capacidade.

Para adicionar uma capacidade ao seu agente:

  1. Aceda ao seu agente.

  2. Selecione Definições>Capacidades para aceder à página de capacidades.

  3. Selecione Adicionar uma capacidade.

  4. Copie o seu ID de agente. Tem de fornecer o ID do agente ao seu programador de capacidades.

  5. Introduza o URL no manifesto de capacidade. O manifesto de capacidade contém a informação de que o seu agente precisa para acionar ações dentro de uma capacidade.

  6. Selecione Seguinte para iniciar o processo de validação. Quando a validação é concluída com êxito, a sua capacidade é adicionada ao seu agente. Agora pode utilizar esta competência nos seus tópicos.

Considerações de conformidade

Para proteger a privacidade do utilizador, exigimos que as capacidades sejam registadas como uma aplicação no inquilino do Microsoft Entra ID do utilizador com sessão iniciada.

Resolução de erros durante o registo de capacidades

Uma série de verificações de validação são efetuadas contra o URL. Estas verificações garantem a conformidade, governação e usabilidade da capacidade que está a ser adicionada ao seu agente. Deve corrigir estes erros antes de registar uma capacidade.

Mensagem de erro Resolução de problemas / Mitigação
Tivemos problemas para obter o manifesto de capacidade.
(MANIFEST_FETCH_FAILED)		 Tente abrir o seu manifesto de URL num browser Web. Se o URL compuser a página dentro de 10 segundos, volte a registar a sua competência.
O manifesto é incompatível.
(MANIFEST_MALFORMED)		 (a) Verifique se o manifesto é um ficheiro JSON válido.
(b) Verifique se o manifesto contém as propriedades necessárias
Por exemplo, (name, msaAppId, endpoint único, activities/id, activities/description, activities/type (só suportado event ou message)).
Há uma incompatibilidade nos seus pontos finais
(MANIFEST_ENDPOINT_ORIGIN_MISMATCH)		 Verifique se o seu ponto final de capacidade corresponde ao seu registo de aplicações do Microsoft Entra ID Publisher domain (preferido) ou campo do Home page URL. Saiba mais sobre a definição da home page para pontos finais.
Para adicionar uma capacidade, primeiro tem de ser registada
(APPID_NOT_IN_TENANT)		 Verifique se o ID de aplicação da sua capacidade está registado no inquilino do Microsoft Entra ID da sua organização.
A ligação não é válida; a ligação deve começar com https://
(URL_MALFORMED, URL_NOT_HTTPS)		 Reveja a ligação para adicionar um URL seguro.
O manifesto é demasiado grande;
(MANIFEST_TOO_LARGE)		 Verifique o tamanho do manifesto. Tem de ser menor ou igual a 500 KB.
Esta capacidade já foi adicionada ao seu agente.
(MANIFEST_ALREADY_IMPORTED)		 Elimine a competência e tente registar-se novamente.
A competência está limitada a 100 ações.
(LIMITS_TOO_MANY_ACTIONS)		 Existem demasiadas ações de competência definidas no manifesto de competências. Remova ações e tente novamente.
As ações estão limitadas a 25 entradas.
(LIMITS_TOO_MANY_INPUTS)		 Há demasiados parâmetros de entrada de ação de competência. Remova parâmetros e tente novamente.
As ações estão limitadas a 25 saídas.
(LIMITS_TOO_MANY_OUTPUTS)		 Há demasiados parâmetros de saída de ação de competência. Remova parâmetros e tente novamente.
O seu agente pode ter um máximo de 100 capacidades.
(LIMITS_TOO_MANY_SKILLS)		 Há demasiadas capacidades adicionadas a um agente. Remova uma competência existente e tente novamente.
Parece que algo correu mal.
(AADERROR_OTHER)		 Houve um erro transitório ao validar a sua competência. Repetir.
Ocorreu um problema ao verificar a sua competência.
(ENDPOINT_HEALTHCHECK_FAILED, HEALTH_PING_FAILED)		 Verifique se o seu ponto final de competência está online e responde às mensagens. Verifique também se o registo da aplicação da capacidade de um único inquilino foi implementado para o mesmo inquilino.
Esta capacidade não colocou o seu agente na lista de autorizados
(ENDPOINT_HEALTHCHECK_UNAUTHORIZED)		 Verifique se o seu agente foi adicionado à lista de autorizados das capacidades.
  • Last updated on