Use um chatbot clássico como uma habilidade

Importante

As capacidades e os recursos do Power Virtual Agents agora fazem parte do Microsoft Copilot Studio após investimentos significativos em IA generativa e integrações aprimoradas no Microsoft Copilot.

Alguns artigos e capturas de tela podem fazer referência ao Power Virtual Agents enquanto atualizamos a documentação e o conteúdo do treinamento.

Observação

Este artigo inclui informações aplicáveis apenas a chatbots clássicos do Microsoft Copilot Studio. Esse recurso não está disponível na nova experiência do Microsoft Copilot Studio.

Quando você usa um copiloto do Microsoft Copilot Studio como uma habilidade com um bot do Bot Framework, o bot do Bot Framework determinará se alguma coisa que o usuário do bot diz corresponde às frases de gatilho no copiloto do Microsoft Copilot Studio. Se houver uma correspondência, o bot do Bot Framework passa a conversa para o bot do Microsoft Copilot Studio. O copiloto do Microsoft Copilot Studio extrai qualquer entidade e aciona o tópico correspondente.

Você também pode passar uma variável para um tópico de habilidade do Microsoft Copilot Studio como uma entrada do Bot Framework Composer e usar as saídas que ele retornar.

Importante

É necessária uma licença de avaliação ou completa do Microsoft Copilot Studio para usar bots do Microsoft Copilot Studio como habilidades. Este recurso não está disponível com a licença do Teams do Microsoft Copilot Studio.

Para configurar o copiloto do Microsoft Copilot Studio como uma habilidade:

1. Adicionar o bot do Bot Framework à lista de permissões do copiloto do Microsoft Copilot Studio.
2. Baixe o manifesto de habilidade do copiloto do Microsoft Copilot Studio.
3. Use o manifesto de habilidade baixado no Composer do Bot Framework para criar uma conexão entre os bots
4. Usar o Bot Framework Emulator para confirmar que o bot funciona como uma habilidade.

Pré-requisitos

• Entenda como as habilidades do Bot Framework funcionam.
• Entenda como usar o Bot Framework Composer.
• Entenda como usar as habilidades no Bot Framework Composer.
• Obtenha a ID do aplicativo do bot do Bot Framework.

Adicione o bot do Bot Framework à lista de permissões do copiloto do Microsoft Copilot Studio

Adicione a ID do aplicativo do bot do Bot Framework à lista de permissões do copiloto do Microsoft Copilot Studio que você deseja usar como uma habilidade. Os bots precisam estar no mesmo locatário.

1. No Bot Framework Compositor, abra o bot que usará a habilidade. Selecionar Configurar e, em seguida, selecione Recursos de desenvolvimento. Copie o ID em ID do Aplicativo da Microsoft.

   

2. No Microsoft Copilot Studio, abra o copiloto que você deseja usar como uma habilidade.

3. No menu de navegação, acesse Configurações e selecione Segurança. Depois, selecione Lista de permitidos.

   

4. Selecione Adicionar chamador permitido.

   

5. Cole a ID do aplicativo do bot do Bot Framework e selecione Avançar.

   

   Cuidado

   Um copiloto do Microsoft Copilot Studio não pode agir como uma habilidade para outros copilotos do Microsoft Copilot Studio. Se você tentar adicionar uma ID de aplicativo que pertence a um bot do Power Virtual Agent à lista de permissões, receberá um erro. Você só pode adicionar um ID de aplicativo para um bot do Bot Framework.

   O Microsoft Copilot Studio valida a ID do aplicativo do bot do Bot Framework e confirma se ele pertence a um bot no mesmo locatário.

6. (Opcional) Adicione um Nome de exibição ao bot que você adicionou à lista de permissões.

   

7. Selecione Salvar.

O bot do Bot Framework é mostrado por seu nome de exibição, caso você tenha inserido um, ou por seu ID de aplicativo, caso você não tenha. Para excluí-lo ou editá-lo a qualquer momento, selecione o ícone à direita do nome de exibição do bot ou do ID do aplicativo.

Nota

Os bots do Bot Framework adicionados à lista de permissões não são exportados como parte do conteúdo do bot.

Baixe o manifesto de habilidade do copiloto de seu copiloto do Microsoft Copilot Studio

Os bots do Bot Framework podem usar um manifesto de habilidades dos Microsoft Copilot Studio para configurar uma conexão com o copiloto que produziu o manifesto.

Todos os copilotos do Microsoft Copilot Studio têm manifestos de habilidade. Esses são arquivos JSON que incluem o nome, a interface e as frases de gatilho de uma habilidade.

O bot do Bot Framework pode usar um manifesto de habilidade para saber quando acionar o bot dos Microsoft Copilot Studio (por exemplo, em resposta a algo que um usuário diz ao bot).

Os manifestos de habilidades do Microsoft Copilot Studio seguem a versão 2.2 do esquema de manifesto de habilidades do Bot Framework e consistem nos arquivos intents.lu e manifest.json.

Um bot do Bot Framework pode decidir que um copiloto do Microsoft Copilot Studio deve lidar com a solicitação do usuário, com base nos dados do manifesto. Ele passa para o copiloto tudo o que o usuário disse. Em seguida, o copiloto do Microsoft Copilot Studio corresponderá o que o usuário disse a um tópico do Microsoft Copilot Studio, extrairá quaisquer entidades necessárias para preencher o slot e acionará o tópico dos Microsoft Copilot Studio.

Todos os manifestos de habilidades do Microsoft Copilot Studio são gerados e atualizados automaticamente. Um copiloto dos Microsoft Copilot Studio tem dois manifestos de habilidade:

• Manifesto de teste: permite que o bot do Bot Framework se conecte à versão de teste do copiloto dos Microsoft Copilot Studio. Use o manifesto de teste para validar as mudanças em sua habilidade antes de publicá-la.

  • O manifesto de teste está imediatamente disponível para cada bot dos Microsoft Copilot Studio recém-criado.
  • Ele é atualizado automaticamente para refletir as mudanças sempre que você salvar seu copiloto.

• Manifesto publicado: permite que o bot do Bot Framework se conecte à versão publicada do copiloto dos Microsoft Copilot Studio.

  • O manifesto publicado está disponível apenas para os copilotos dos Microsoft Copilot Studio que foram publicados pelo menos uma vez.
  • Ele é atualizado automaticamente para refletir as mudanças sempre que você publicar seu copiloto.

Observação

O Manifesto publicado não está disponível para copilotos do Microsoft Copilot Studio que nunca foram publicados.

Para gerar o Manifesto publicado do seu bot, você precisa publicar o copiloto do Microsoft Copilot Studio.

Ambos os manifestos são mostrados no painel Gerenciar lista de permissões.

Os manifestos de habilidade também são mostrados na página Detalhes do copiloto. No menu de navegação, selecione Configurações e Detalhes. A página Detalhes mostra outros metadados, incluindo o ID do ambiente, ID do Inquilino e ID do aplicativo do bot.

Para baixar um manifesto, selecione-o. Ele é baixado como um arquivo .zip denominado <bot name>_manifest para o Manifesto publicado ou <bot name>_test__manifest para o Manifesto de teste.

Observação

O manifesto de habilidade não inclui as caixas de diálogo Tópicos do sistema e Composer adicionadas a um copiloto do Microsoft Copilot Studio. Apenas tópicos que foram criados por autores do copiloto e gatilhos de intenção do Composer que os autores adicionam ao bot são incluídos.

Conectar-se a uma habilidade dos Microsoft Copilot Studio no Composer

Use os manifestos de habilidades do Microsoft Copilot Studio para criar uma conexão de habilidade em seu bot do Bot Framework no Composer.

1. Em um projeto do Bot Framework Composer, selecione Adicionar e então Conectar-se a uma habilidade.

   

2. Procure e selecione um manifesto do arquivo .zip do Microsoft Copilot Studio e então selecione Avançar.

   

3. Selecione os tópicos ou intenções no seu copiloto do Microsoft Copilot Studio que deseja adicionar ao bot do Bot Framework e selecione Avançar.

   

4. Revise e edite as frases de gatilho de seu copiloto do Microsoft Copilot Studio e então selecione Avançar.

   

5. Certifique-se de que a opção Usar o Orchestrator para projetos com vários bots esteja selecionado e selecione Continuar.

   

6. Verifique se a habilidade do Microsoft Copilot Studio é adicionada ao bot do Bot Framework corretamente e um novo gatilho com o nome do copiloto do Microsoft Copilot Studio aparece no projeto no Composer.

   

Localizar o tópico no manifesto de habilidade

Use um evento para acionar um tópico do Microsoft Copilot Studio na habilidade. Para chamar um tópico específico do Composer, consulte o tópico pelo nome do evento associado no manifesto da habilidade.

1. Selecione a ação Conectar a uma habilidade.

2. Em Nome do diálogo da habilidade, selecione Mostrar manifesto de habilidade.

   

3. Encontrar atividades no manifesto. Esta propriedade contém propriedades aninhadas que representam os tópicos disponíveis no seu copiloto do Microsoft Copilot Studio.

   

4. Encontre o tópico que deseja chamar e procure sua propriedade nome. Quando a habilidade do Microsoft Copilot Studio recebe um evento com este nome, ela aciona o tópico.

   No exemplo a seguir, o nome da atividade do evento é dispatchTo_new_topic_87609dabd86049f7bc6507c6f7263aba_33d.

   

Chamar um tópico de habilidade do Microsoft Copilot Studio

Em vez de depender do que um usuário diz para acionar um tópico de habilidade do Microsoft Copilot Studio, você pode chamá-lo diretamente. Apenas os tópicos do Microsoft Copilot Studio que estiverem listados no manifesto de habilidade podem ser chamados diretamente.

1. Na tela de criação do Composer, selecione Adicionar, depois Acessar recursos externos e então Conectar-se a uma habilidade.

   

2. Na lista Nome do diálogo da habilidade, selecione seu copiloto do Microsoft Copilot Studio.

   

3. Encontre o nome da atividade do evento para o tópico do bot do Microsoft Copilot Studio que você quer chamar. Copie o valor, omitindo as aspas, e salve-o para usar nas próximas etapas.

4. Selecione Fechar.

5. Na seção Atividade, selecione Mostrar código.

   

6. Digite ou cole o código a seguir. Substitua TOPIC_ACTIVITY_NAME pelo o nome da atividade de evento do seu tópico. Certifique-se de que não há aspas na propriedade nome.

   [Activity
       type = event
       name = TOPIC_ACTIVITY_NAME
   ]
   

   

Passar uma variável de entrada para um tópico de habilidade do Microsoft Copilot Studio

O Bot Framework Composer pode passar uma variável para um tópico de habilidade do Microsoft Copilot Studio como entrada. Para saber como criar os tópicos do Microsoft Copilot Studio que aceitam variáveis de entrada, consulte Passar variáveis entre tópicos.

Se um tópico do Microsoft Copilot Studio que pode receber uma variável de entrada for listado em seu manifesto de habilidade, você pode passar uma variável do Composer para ele.

1. Na tela de criação do Composer, selecione Adicionar, depois Acessar recursos externos e então Conectar-se a uma habilidade.

   

2. Na lista Nome do diálogo da habilidade, selecione seu copiloto do Microsoft Copilot Studio.

   

3. Encontre o nome da atividade do evento para o tópico do copiloto do Microsoft Copilot Studio que você quer chamar. Copie o valor, omitindo as aspas, e salve-o para usar nas próximas etapas.

4. Encontre a propriedade valor do tópico. A propriedade valor contém uma propriedade $ref. Copie esse valor e salve-o para usar na próxima etapa.

   Aviso

   Se um tópico do Microsoft Copilot Studio não tiver entradas, ele não terá uma propriedade valor.

   

5. Encontre a propriedade definições e, em seguida, procure uma propriedade aninhada que corresponda ao valor $ref encontrado na etapa anterior. Anote os nomes e tipos das entradas do tópico do Microsoft Copilot Studio. Você os usará nas próximas etapas.

   

6. Selecione Fechar.

7. Na seção Atividade, selecione Mostrar código.

   

8. Digite ou cole o código a seguir. Substitua estes valores:

   1. Substitua TOPIC_ACTIVITY_NAME pelo o nome da atividade de evento do seu tópico.
   2. Substitua PVA_INPUT_VARIABLE por uma variável de entrada do seu tópico.
   3. Substitua COMPOSER_INPUT_VARIABLE por uma variável do Composer que fornecerá um valor.

   [Activity
       Type = event
       Name = TOPIC_ACTIVITY_NAME
       Value = ${addProperty(json("{}"), 'PVA_INPUT_VARIABLE', COMPOSER_INPUT_VARIABLE)}
   ]
   

   No exemplo a seguir, a variável do Composer dialog.storeLocation fornece um valor para a variável de entrada pva_StoreLocation no tópico do copiloto do Microsoft Copilot Studio dispatchTo_new_topic_127cdcdbbb4a480ea113c5101f309089_21a34f16.

   

Receber uma variável de saída de um tópico de habilidade do Microsoft Copilot Studio

É possível receber saídas de um tópico de habilidade do Microsoft Copilot Studio no Composer. Para saber como criar tópicos do Microsoft Copilot Studio que retornam saídas, consulte Passar variáveis entre tópicos.

1. Na tela de criação do Composer, selecione Adicionar, depois Acessar recursos externos e então Conectar-se a uma habilidade.

   

2. Na lista Nome do diálogo da habilidade, selecione seu copiloto do Microsoft Copilot Studio.

   

3. Encontre o nome da atividade do evento para o tópico do seu bot do Microsoft Copilot Studio que você quer chamar. Copie o valor, omitindo as aspas, e salve-o para usar nas próximas etapas.

4. Encontre a propriedade resultValue do tópico. A propriedade resultValue contém uma propriedade $ref. Copie esse valor e salve-o para usar na próxima etapa.

   Aviso

   Se um tópico do Microsoft Copilot Studio não tiver saídas, ele não terá uma propriedade resultValue.

   

5. Encontre a propriedade definições e, em seguida, procure uma propriedade aninhada que corresponda ao valor $ref encontrado na etapa anterior. Anote os nomes e tipos das variáveis de saída do tópico do Microsoft Copilot Studio. Você os usará nas próximas etapas.

   No exemplo a seguir, o tópico do Microsoft Copilot Studio retorna duas saídas do tipo String, pva_State e pva_Item.

   

6. Selecione Fechar.

7. Na seção Atividade, selecione Mostrar código.

   

8. Digite ou cole o código a seguir. Substitua TOPIC_ACTIVITY_NAME pelo o nome da atividade de evento do seu tópico. Certifique-se de que não há aspas na propriedade nome.

   [Activity
       type = event
       name = TOPIC_ACTIVITY_NAME
   ]
   

   

9. Na área do código, defina Propriedade como uma variável do Composer para receber e armazenar os valores de saída do tópico de habilidade do Microsoft Copilot Studio.

   

10. Na tela de criação do Composer, selecione Adicionar, em seguida, selecione Gerenciar propriedades e, em seguida, selecione Definir propriedades.

    

11. Defina Propriedade como o valor do Composer que deve armazenar o valor extraído. Em seguida, defina Valor como a variável Composer na qual você armazenou as saídas do tópico.

    No exemplo a seguir, os valores de saída de dialog.skillResult.pvaState e dialog.skillResult.pvaItem são extraídos em novas variáveis do Composer dialog.State e dialog.Item.

    

Testar seu copiloto do Microsoft Copilot Studio como uma habilidade com um bot do Bot Framework

Use o Bot Framework Emulator pare testar se o bot do Bot Framework está chamando corretamente um copiloto do Microsoft Copilot Studio como uma habilidade.

Importante

O bot do Bot Framework deve ser adicionado à lista de permissões do copiloto dos Microsoft Copilot Studio para a conexão de habilidades funcionar.

Saiba mais

• Visão geral de habilidades
• Manifesto de habilidades
• Documentação do Bot Framework Composer
• Habilidades no Composer
• Conectar-se a uma habilidade remota no Composer
• Teste uma habilidade no Emulator