Partilhar via

Use um chatbot clássico como uma habilidade em um bot do Bot Framework

  • Artigo

Observação

Este artigo é aplicável apenas aos chatbots clássicos. Esse recurso não está disponível na nova experiência do Copilot Studio.

Quando você usa um chatbot clássico como uma habilidade com um bot do Bot Framework, o bot do Bot Framework determina se alguma coisa que o usuário do bot diz corresponde às frases de gatilho do chatbot. Se houver uma correspondência, o bot do Bot Framework transfere a conversa para o chatbot clássico. O chatbot clássico extrai quaisquer entidades e dispara o tópico de correspondência.

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

Importante

É necessário ter uma licença de avaliação ou completa do Copilot Studio para usar chatbots clássicos como habilidades. Este recurso não está disponível com a licença do Teams do Copilot Studio.

Para configurar o chatbot clássico como uma habilidade:

  1. Adicione o bot do Bot Framework à lista de permitidos do chatbot clássico.

  2. Baixe o manifesto de habilidade do chatbot clássico.

  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

Adicione o bot do Bot Framework à lista de permitidos de seu chatbot clássico

Adicione a ID do aplicativo do bot do Bot Framework à lista de permitidos do chatbot clássico 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 Copilot Studio, abra o chatbot clássico 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 chatbot clássico não pode funcionar como uma habilidade para outros chatbots clássicos. Se você tentar adicionar uma ID de aplicativo que pertence a um bot do Power Virtual Agent à lista de permitidos, receberá um erro. Você só pode adicionar um ID de aplicativo para um bot do Bot Framework.

    O 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 permitidos.

  7. Selecione Salvar.

O bot do Bot Framework aparece 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 chatbot clássico para seu chatbot clássico

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

Todos os chatbots clássicos têm manifestos de habilidade. Um manifesto de habilidade é um arquivo JSON que tem 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 chatbot clássico (por exemplo, em resposta a algo que um usuário diz ao bot).

Os manifestos de habilidades do 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 chatbot clássico deve lidar com a solicitação do usuário, com base nos dados do manifesto. Ele passa para o chatbot clássico tudo o que o usuário disse. Em seguida, o chatbot clássico corresponde o que o usuário disse para um tópico do Copilot Studio, extrai quaisquer entidades necessárias para preencher o slot, e aciona o tópico do Copilot Studio.

Todos os manifestos de habilidades do Copilot Studio são gerados e atualizados automaticamente. Um chatbot clássico tem dois manifestos de habilidade:

  • Manifesto de teste: permite que bot do Bot Framework se conecte à versão de teste de seu chatbot clássico. 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 chatbot clássico criado.
    • Ele é atualizado automaticamente para refletir as mudanças sempre que você salvar seu chatbot clássico.

  • Manifesto publicado: permite que o bot do Bot Framework se conecte à versão publicada do bot do seu chatbot clássico.

    • O manifesto publicado está disponível apenas para os chatbots clássicos que foram publicados pelo menos uma vez.
    • Ele é atualizado automaticamente para refletir as mudanças sempre que você publicar seu agente.

Observação

O Manifesto publicado não está disponível para chatbots clássicos que nunca foram publicados.

Para gerar o Manifesto publicado do bot, publique seu chatbot clássico.

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 tem as caixas de diálogo tópicos do sistema e Composer que são adicionadas a um chatbot clássico. 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 Copilot Studio no Composer

Use os manifestos de habilidades do 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 Copilot Studio e então selecione Avançar.

  3. Selecione os tópicos ou intenções no seu chatbot clássico que deseja adicionar ao bot do Bot Framework, em seguida, selecione Avançar.

  4. Revise e edite as frases de gatilho do chatbot clássico e 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 Copilot Studio é adicionada ao bot do Bot Framework corretamente e um novo gatilho com o nome do chatbot clássico no projeto no Composer.

Localizar o tópico no manifesto de habilidade

Use um evento para acionar um tópico do 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 chatbot clássico.

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

    Neste exemplo, o nome da atividade do evento é dispatchTo_new_topic_87609dabd86049f7bc6507c6f7263aba_33d.

Chamar um tópico de habilidade do Copilot Studio

Em vez de depender do que um usuário diz para acionar um tópico de habilidade do Copilot Studio, você pode chamá-lo diretamente. Apenas os tópicos do 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 chatbot clássico.

  3. Encontre o nome da atividade do evento para o tópico do chatbot clássico que você deseja 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 Copilot Studio

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

Se um tópico do 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 chatbot clássico.

  3. Encontre o nome da atividade do evento para o tópico do chatbot clássico que você deseja 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 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 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 chatbot clássicodispatchTo_new_topic_127cdcdbbb4a480ea113c5101f309089_21a34f16.

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

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

  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 chatbot clássico.

  3. Encontre o nome da atividade do evento para o tópico do chatbot clássico que você deseja 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 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 Copilot Studio. Você os usará nas próximas etapas.

    Neste exemplo, o tópico do 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 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.

    Neste 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 chatbot clássico como uma habilidade com um bot do Bot Framework

Use o Emulador do Bot Framework para testar se o bot do Bot Framework está chamando adequadamente um chatbot clássico como uma habilidade.

Importante

O bot do Bot Framework deve ser adicionado à lista de permitidos do chatbot clássico para a conexão de habilidades funcionar.

Atualizar um bot multilocatário do Bot Framework para um bot de locatário único

A ilustração a seguir mostra o cenário em que um bot do Bot Framework criado no Bot Framework SDK está chamando um chatbot clássico para usá-lo como uma habilidade.

Ilustração mostrando as interações entre um Bot do Bot Framework e um chatbot clássico.

Tanto o bot do Bot Framework quanto o chatbot clássico têm um registro de aplicativo do Microsoft Entra ID, que é referenciado pelas instâncias de Bot do Azure. Esses registros de aplicativo do Microsoft Entra ID foram criados como multilocatário. O bot do Bot Framework solicita um token do locatário do Bot Framework e usa esse token para se autenticar para o Copilot Studio usando o Serviço de Bot do Azure. O Copilot Studio usa o mesmo mecanismo para entrar em contato com o bot do Bot Framework.

O registro do aplicativo do chatbot do Copilot Studio agora é criado como um único locatário, portanto, essa comunicação não funciona mais. O Microsoft Entra ID se recusa a criar tokens para registros de aplicativos de locatário único que não estão no mesmo locatário.

Além disso, o Copilot Studio valida o token de entrada e rejeita solicitações de locatários que ele não espera, como a ID do locatário na qual o registro de aplicativo do chatbot clássico foi criado.

Para resolver esse problema, há duas correções possíveis.

Chatbots clássicos no mesmo locatário que o bot do Bot Framework

Em cenários em que o chatbot do Copilot Studio já está implantado no mesmo locatário que o bot do Bot Framework e é usado apenas por esse bot, atualize o bot para uma configuração de locatário único e reimplante o bot do Bot Framework. Para obter mais informações sobre como configurar um bot do Bot Framework para locatário único, consulte Provisionar e publicar um bot.

O chatbot do Copilot Studio que não pode ser atualizado para locatário único

Em cenários em que o chatbot do Copilot Studio já está implantado no mesmo locatário que o bot do Bot Framework, mas o bot não pode ser atualizado para locatário único, você precisa atualizar o código no bot do Bot Framework para criar o token para se comunicar com o chatbot do Copilot Studio. O token precisa ser criado para o locatário no qual o chatbot do Copilot Studio também foi criado. Além disso, a resposta deve ser aceita, o que provavelmente requer que você siga as etapas em Converter uma habilidade existente de multilocatário para locatário único.

Saiba mais