Aracılığıyla paylaş

Beceri kullanmak için iletişim kutusu kullanma

  • Makale

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Bu makalede, beceri tüketicisi içinde beceri iletişim kutusunun nasıl kullanılacağı gösterilmektedir. Beceri iletişim kutusu, üst bottan beceri botunun etkinliklerine gönderiler ve beceri yanıtlarını kullanıcıya döndürür. Bu tüketici tarafından erişilen beceri botu hem ileti hem de olay etkinliklerini işleyebilir. Örnek beceri bildirimi ve beceriyi uygulama hakkında bilgi için bkz . Beceri içindeki iletişim kutularını kullanma.

İletişim kutularının dışında beceri botu kullanma hakkında bilgi için bkz. Beceri tüketicisi uygulama.

Not

Bot Framework JavaScript, C# ve Python SDK'ları desteklenmeye devam edecektir, ancak Java SDK'sı son uzun vadeli destek Kasım 2023'te sona erecek şekilde kullanımdan kaldırılacaktır.

Java SDK ile oluşturulan mevcut botlar çalışmaya devam edecektir.

Yeni bot derlemesi için Microsoft Copilot Studio'yu kullanmayı göz önünde bulundurun ve doğru copilot çözümünü seçme hakkında bilgi edinin.

Daha fazla bilgi için bkz . Bot oluşturmanın geleceği.

Önkoşullar

Bu örnek hakkında

Beceri becerileriDialog örneği iki bota yönelik projeleri içerir:

  • Beceriyi kullanmak için beceri iletişim kutusu sınıfını kullanan iletişim kutusu kök botu.
  • Beceri tüketicilerinden gelen etkinlikleri işlemek için bir iletişim kutusu kullanan iletişim kutusu beceri botu.

Bu makalede, beceriyi yönetmek, ileti ve olay etkinlikleri göndermek ve beceriyi iptal etmek için kök botta beceri iletişim kutusu sınıfının nasıl kullanılacağına odaklanmaktadır.

Beceri tüketicisi oluşturmanın diğer yönleri hakkında bilgi için bkz. Beceri tüketicisi uygulama.

İletişim kutusu beceri botu hakkında bilgi için bkz. Beceri içindeki iletişim kutularını kullanma.

Kaynaklar

Dağıtılan botlar için bot-bot kimlik doğrulaması, katılan her bot için geçerli bir kimliğe sahip olmasını gerektirir. Ancak kimlik bilgileri olmadan Bot Framework Öykünücüsü ile becerileri ve beceri tüketicilerini yerel olarak test edebilirsiniz.

Uygulama yapılandırması

  1. İsteğe bağlı olarak, kök botunun kimlik bilgilerini yapılandırma dosyasına ekleyin.
  2. Becerilerin beceri tüketicisine yanıt vermesi gereken beceri ana bilgisayar uç noktasını (hizmet veya geri çağırma URL'si) ekleyin.
  3. Beceri tüketicisinin kullanacağı her beceri için bir giriş ekleyin. Her girdi şunları içerir:
    • Tüketicinin her beceriyi tanımlamak için kullanacağı bir kimlik.
    • İsteğe bağlı olarak, beceri botunun uygulaması veya istemci kimliği.
    • Becerinin mesajlaşma uç noktası.

Not

Beceri veya beceri tüketicisi bir kimlik belirtiyorsa, her ikisi de belirtmelidir.

DialogRootBot\appsettings.json

İsteğe bağlı olarak kök botunun kimlik bilgilerini ekleyin ve yankı beceri botu için uygulama veya istemci kimliğini diziye BotFrameworkSkills ekleyin.

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",

  "SkillHostEndpoint": "http://localhost:3978/api/skills/",
  "BotFrameworkSkills": [
    {
      "Id": "DialogSkillBot",
      "AppId": "",
      "SkillEndpoint": "http://localhost:39783/api/messages"
    }
  ]
}

İletişim kutusu mantığı

Bot'un ana iletişim kutusu, bu botta tükettiği her beceri için bir beceri iletişim kutusu içerir. Beceri iletişim kutusu, beceri istemcisi ve beceri konuşma kimliği fabrika nesneleri gibi beceriyle ilgili çeşitli nesneler aracılığıyla beceriyi yönetir. Ana iletişim kutusunda ayrıca kullanıcı girişine göre becerinin (beceri iletişim kutusu aracılığıyla) nasıl iptal edileceği de gösterilmektedir.

Bu botta kullanılan beceri birkaç farklı özelliği destekler. Bir uçuş rezervasyonu yapabilir veya bir şehrin hava durumunu alabilir. Buna ek olarak, bu bağlamlardan birinin dışında bir ileti alırsa ve bir LUIS tanıyıcı yapılandırılırsa, kullanıcının amacını yorumlamaya çalışır.

Not

Language Understanding (LUIS) 1 Ekim 2025'te kullanımdan kaldırılacaktır. 1 Nisan 2023'e kadar yeni LUIS kaynakları oluşturamayacaksınız. Dil anlamanın daha yeni bir sürümü artık Azure AI Dili'nin bir parçası olarak kullanılabilir.

Azure AI Dili'nin bir özelliği olan konuşma dili anlama (CLU), LUIS'in güncelleştirilmiş sürümüdür. Bot Framework SDK'sında dil anlama desteği hakkında daha fazla bilgi için bkz . Doğal dil anlama.

Beceri bildirimi (C#, JavaScript, Java, Python), becerinin gerçekleştirebileceği eylemleri, giriş ve çıkış parametrelerini ve becerinin uç noktalarını açıklar. Not: Beceri bir "BookFlight" veya "GetWeather" olayını işleyebilir. İletileri de işleyebilir.

Ana iletişim kutusu şunların kodunu içerir:

Ana iletişim kutusu, bileşen iletişim kutusu sınıfından devralınır. Bileşen iletişim kutuları hakkında daha fazla bilgi için bkz. İletişim kutusu karmaşıklığını yönetme.

Ana iletişim kutusunu başlatma

Ana iletişim kutusu iletişim kutularını (konuşma akışını becerinin dışında yönetmek için) ve beceri iletişim kutusunu (becerileri yönetmek için) içerir. Şelale, sonraki birkaç bölümde daha ayrıntılı olarak açıklanan aşağıdaki adımları içerir.

  1. Kullanıcıdan kullanılacak beceriyi seçmesini iste. (Kök bot bir beceri tüketir.)
  2. Kullanıcıdan bu beceri için kullanılacak eylemi seçmesini iste. (Beceri botu üç eylem tanımlar.)
  3. Seçilen beceriyi, seçilen eyleme göre bir başlangıç etkinliğiyle başlatın.
  4. Beceri tamamlandıktan sonra, varsa sonuçları görüntüleyin. Ardından şelaleyi yeniden başlatın.

DialogRootBot\Dialogs\MainDialog.cs

MainDialog sınıfı öğesinden ComponentDialogtüretilir. Konuşma durumuna ek olarak, iletişim kutusu kök botunun kimliğine ve beceri konuşma kimliği fabrikasına, beceri HTTP istemcisine ve beceri yapılandırma nesnelerine başvurular gerektirir.

İletişim kutusu oluşturucu giriş parametrelerini denetler, beceri iletişim kutuları ekler, konuşma akışını becerinin dışında yönetmek için istem ve şelale iletişim kutuları ekler ve varsa etkin beceriyi izlemek için bir özellik erişimcisi oluşturur.

Oluşturucu, yapılandırma dosyasından bir nesneye okundukça yapılandırma dosyasına dahil edilen her beceri için bir SkillDialog oluşturmak üzere bir SkillsConfiguration yardımcı yöntemi olarak çağırırAddSkillDialogs.

// Helper method that creates and adds SkillDialog instances for the configured skills.
private void AddSkillDialogs(ConversationState conversationState, SkillConversationIdFactoryBase conversationIdFactory, SkillsConfiguration skillsConfig, string botId)
{
    foreach (var skillInfo in _skillsConfig.Skills.Values)
    {
        // Create the dialog options.
        var skillDialogOptions = new SkillDialogOptions
        {
            BotId = botId,
            ConversationIdFactory = conversationIdFactory,
            SkillClient = _auth.CreateBotFrameworkClient(),
            SkillHostEndpoint = skillsConfig.SkillHostEndpoint,
            ConversationState = conversationState,
            Skill = skillInfo
        };

        // Add a SkillDialog for the selected skill.
        AddDialog(new SkillDialog(skillDialogOptions, skillInfo.Id));
    }
}

Bir beceri seçin

İlk adımında, ana iletişim kutusu kullanıcıya çağırmak istediği beceriyi sorar ve yanıtı almak için "SkillPrompt" seçim istemini kullanır. (Bu bot yalnızca bir beceri tanımlar.)

DialogRootBot\Dialogs\MainDialog.cs

// Render a prompt to select the skill to call.
private async Task<DialogTurnResult> SelectSkillStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // Create the PromptOptions from the skill configuration which contain the list of configured skills.
    var messageText = stepContext.Options?.ToString() ?? "What skill would you like to call?";
    var repromptMessageText = "That was not a valid choice, please select a valid skill.";
    var options = new PromptOptions
    {
        Prompt = MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput),
        RetryPrompt = MessageFactory.Text(repromptMessageText, repromptMessageText, InputHints.ExpectingInput),
        Choices = _skillsConfig.Skills.Select(skill => new Choice(skill.Value.Id)).ToList()
    };

    // Prompt the user to select a skill.
    return await stepContext.PromptAsync("SkillPrompt", options, cancellationToken);
}

Beceri eylemi seçme

Sonraki adımda ana iletişim kutusu:

  1. Kullanıcının seçtiği beceri hakkındaki bilgileri kaydeder.
  2. Kullanıcıdan kullanmak istediği beceri eylemini sorar ve yanıtı almak için "SkillActionPrompt" seçim istemini kullanır.
    • Aralarından seçim yapabileceğiniz eylemlerin listesini almak için bir yardımcı yöntemi kullanır.
    • Kullanıcının girişi seçeneklerden biriyle eşleşmiyorsa, bu istemle ilişkili istem doğrulayıcı varsayılan olarak beceriye bir ileti gönderir.

Bu bottaki seçenekler, bu beceri için tanımlanan eylemlerin test edilmesine yardımcı olur. Daha genel olarak, becerinin bildirimindeki seçenekleri okur ve bu listeyi temel alan seçenekleri kullanıcıya sunarsınız.

DialogRootBot\Dialogs\MainDialog.cs

// Render a prompt to select the action for the skill.
private async Task<DialogTurnResult> SelectSkillActionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // Get the skill info based on the selected skill.
    var selectedSkillId = ((FoundChoice)stepContext.Result).Value;
    var selectedSkill = _skillsConfig.Skills.FirstOrDefault(s => s.Value.Id == selectedSkillId).Value;

    // Remember the skill selected by the user.
    stepContext.Values[_selectedSkillKey] = selectedSkill;

    // Create the PromptOptions with the actions supported by the selected skill.
    var messageText = $"Select an action # to send to **{selectedSkill.Id}** or just type in a message and it will be forwarded to the skill";
    var options = new PromptOptions
    {
        Prompt = MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput),
        Choices = GetSkillActions(selectedSkill)
    };

    // Prompt the user to select a skill action.
    return await stepContext.PromptAsync("SkillActionPrompt", options, cancellationToken);
}
// Helper method to create Choice elements for the actions supported by the skill.
private IList<Choice> GetSkillActions(BotFrameworkSkill skill)
{
    // Note: the bot would probably render this by reading the skill manifest.
    // We are just using hardcoded skill actions here for simplicity.

    var choices = new List<Choice>();
    switch (skill.Id)
    {
        case "DialogSkillBot":
            choices.Add(new Choice(SkillActionBookFlight));
            choices.Add(new Choice(SkillActionBookFlightWithInputParameters));
            choices.Add(new Choice(SkillActionGetWeather));
            break;
    }

    return choices;
}
// This validator defaults to Message if the user doesn't select an existing option.
private Task<bool> SkillActionPromptValidator(PromptValidatorContext<FoundChoice> promptContext, CancellationToken cancellationToken)
{
    if (!promptContext.Recognized.Succeeded)
    {
        // Assume the user wants to send a message if an item in the list is not selected.
        promptContext.Recognized.Value = new FoundChoice { Value = SkillActionMessage };
    }

    return Task.FromResult(true);
}

Beceriye başlama

Sonraki adımda ana iletişim kutusu:

  1. Kullanıcının seçtiği beceri ve beceri etkinliği hakkındaki bilgileri alır.
  2. Başlangıçta beceriye gönderilecek etkinliği oluşturmak için bir yardımcı yöntemi kullanır.
  3. Beceri iletişim kutusunun başlatıldığı iletişim kutusu seçeneklerini oluşturur. Bu, gönderilecek ilk etkinliği içerir.
  4. Beceriyi çağırmadan önce durumu kaydeder. (Beceri yanıtı, beceri tüketicisinin farklı bir örneğine gelebileceğinden bu gereklidir.)
  5. Aranacak beceri kimliğini ve çağrılacak seçenekleri geçirerek beceri iletişim kutusunu başlatır.

DialogRootBot\Dialogs\MainDialog.cs

// Starts the SkillDialog based on the user's selections.
private async Task<DialogTurnResult> CallSkillActionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var selectedSkill = (BotFrameworkSkill)stepContext.Values[_selectedSkillKey];

    Activity skillActivity;
    switch (selectedSkill.Id)
    {
        case "DialogSkillBot":
            skillActivity = CreateDialogSkillBotActivity(((FoundChoice)stepContext.Result).Value, stepContext.Context);
            break;

        // We can add other case statements here if we support more than one skill.
        default:
            throw new Exception($"Unknown target skill id: {selectedSkill.Id}.");
    }

    // Create the BeginSkillDialogOptions and assign the activity to send.
    var skillDialogArgs = new BeginSkillDialogOptions { Activity = skillActivity };

    // Save active skill in state.
    await _activeSkillProperty.SetAsync(stepContext.Context, selectedSkill, cancellationToken);

    // Start the skillDialog instance with the arguments. 
    return await stepContext.BeginDialogAsync(selectedSkill.Id, skillDialogArgs, cancellationToken);
}

Beceri sonucunu özetleme

Son adımda ana iletişim kutusu:

  1. Beceri bir değer döndürdüyse, sonucu kullanıcıya görüntüleyin.
  2. İletişim kutusundan etkin beceriyi temizler.
  3. Etkin beceri özelliğini konuşma durumundan kaldırır.
  4. Kendisini yeniden başlatır (ana iletişim kutusu).

DialogRootBot\Dialogs\MainDialog.cs

// The SkillDialog has ended, render the results (if any) and restart MainDialog.
private async Task<DialogTurnResult> FinalStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var activeSkill = await _activeSkillProperty.GetAsync(stepContext.Context, () => null, cancellationToken);

    // Check if the skill returned any results and display them.
    if (stepContext.Result != null)
    {
        var message = $"Skill \"{activeSkill.Id}\" invocation complete.";
        message += $" Result: {JsonConvert.SerializeObject(stepContext.Result)}";
        await stepContext.Context.SendActivityAsync(MessageFactory.Text(message, message, inputHint: InputHints.IgnoringInput), cancellationToken: cancellationToken);
    }

    // Clear the skill selected by the user.
    stepContext.Values[_selectedSkillKey] = null;

    // Clear active skill in state.
    await _activeSkillProperty.DeleteAsync(stepContext.Context, cancellationToken);

    // Restart the main dialog with a different message the second time around.
    return await stepContext.ReplaceDialogAsync(InitialDialogId, $"Done with \"{activeSkill.Id}\". \n\n What skill would you like to call?", cancellationToken);
}

Kullanıcının beceriyi iptal etmesine izin ver

Ana iletişim kutusu, kullanıcının varsa geçerli beceriyi iptal etmesine izin vermek için devam etme iletişim kutusu yönteminin varsayılan davranışını geçersiz kılar. yönteminde:

  • Etkin bir beceri varsa ve kullanıcı "iptal" iletisi gönderirse, tüm iletişim kutularını iptal edin ve baştan yeniden başlatmak için ana iletişim kutusunu kuyruğa alın.
  • Ardından, geçerli dönüşü işlemeye devam etmek için devam et iletişim kutusunun temel uygulamasını çağırın.

DialogRootBot\Dialogs\MainDialog.cs

protected override async Task<DialogTurnResult> OnContinueDialogAsync(DialogContext innerDc, CancellationToken cancellationToken = default)
{
    // This is an example on how to cancel a SkillDialog that is currently in progress from the parent bot.
    var activeSkill = await _activeSkillProperty.GetAsync(innerDc.Context, () => null, cancellationToken);
    var activity = innerDc.Context.Activity;
    if (activeSkill != null && activity.Type == ActivityTypes.Message && activity.Text.Equals("abort", StringComparison.OrdinalIgnoreCase))
    {
        // Cancel all dialogs when the user says abort.
        // The SkillDialog automatically sends an EndOfConversation message to the skill to let the
        // skill know that it needs to end its current dialogs, too.
        await innerDc.CancelAllDialogsAsync(cancellationToken);
        return await innerDc.ReplaceDialogAsync(InitialDialogId, "Canceled! \n\n What skill would you like to call?", cancellationToken);
    }

    return await base.OnContinueDialogAsync(innerDc, cancellationToken);
}

Etkinlik işleyici mantığı

Her dönüş için beceri mantığı bir ana iletişim kutusu tarafından işlendiğinden, etkinlik işleyicisi diğer iletişim kutusu örnekleri için olduğu gibi görünür.

DialogRootBot\Bots\RootBot.cs

public class RootBot<T> : ActivityHandler
    where T : Dialog

private readonly ConversationState _conversationState;
private readonly Dialog _mainDialog;

public RootBot(ConversationState conversationState, T mainDialog)
{
    _conversationState = conversationState;
    _mainDialog = mainDialog;
}

public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default)
{
    if (turnContext.Activity.Type != ActivityTypes.ConversationUpdate)
    {
        // Run the Dialog with the Activity.
        await _mainDialog.RunAsync(turnContext, _conversationState.CreateProperty<DialogState>("DialogState"), cancellationToken);
    }
    else
    {
        // Let the base class handle the activity.
        await base.OnTurnAsync(turnContext, cancellationToken);
    }

    // Save any state changes that might have occurred during the turn.
    await _conversationState.SaveChangesAsync(turnContext, false, cancellationToken);
}

Hizmet kaydı

Beceri iletişim kutusunu kullanmak için gereken hizmetler, genel olarak beceri tüketicisi için gereken hizmetlerle aynıdır. Gerekli hizmetlerle ilgili bir tartışma için beceri tüketicisi uygulamayı öğrenin.

Kök botu test edin

Emulator'da beceri tüketicisini normal bir bot gibi test edebilirsiniz; ancak hem beceri hem de beceri tüketici botlarını aynı anda çalıştırmanız gerekir. Beceriyi yapılandırma hakkında bilgi için bir beceri içindeki iletişim kutularının nasıl kullanılacağını öğrenin.

En son Bot Framework Öykünücüsü'ne indirin ve yükleyin.

  1. İletişim kutusu beceri botunu ve iletişim kutusu kök botunu makinenizde yerel olarak çalıştırın. Yönergelere ihtiyacınız varsa C#, JavaScript, Java ve Python örneklerine README bakın.
  2. Botu test etmek için Öykünücü'yü kullanın.
    • Konuşmaya ilk katıldığınızda bot bir karşılama iletisi görüntüler ve size hangi beceriyi çağırmak istediğinizi sorar. Bu örnek için beceri botunun tek bir becerisi vardır.
    • DialogSkillBot'ı seçin.
  3. Ardından bot, beceri için bir eylem seçmenizi ister. "BookFlight" öğesini seçin.
    1. istemleri yanıtlayın.
    2. Beceri tamamlanıp kök bot, aramak istediğiniz beceriyi yeniden sormadan önce rezervasyon ayrıntılarını görüntüler.
  4. DialogSkillBot'ı yeniden ve "BookFlight" öğesini seçin.
    1. İlk istemi yanıtlayın, ardından beceriyi kesmek için "abort" yazın.
    2. Kök bot, beceriyi iptal eder ve çağırmak istediğiniz beceriyi ister.

Hata ayıklama hakkında daha fazla bilgi

Beceri ve beceri tüketicileri arasındaki trafiğin kimliği doğrulandığından, bu tür botlarda hata ayıklama sırasında ek adımlar vardır.

  • Beceri tüketicisi ve doğrudan veya dolaylı olarak tükettiği tüm beceriler çalışıyor olmalıdır.
  • Botlar yerel olarak çalışıyorsa ve botlardan herhangi birinin uygulama kimliği ve parolası varsa, tüm botların geçerli kimlikleri ve parolaları olmalıdır.
  • Botların tümü dağıtıldıysa ngrok kullanarak herhangi bir kanaldan bir botta hata ayıklamayı öğrenin.
  • Botlardan bazıları yerel olarak çalışıyorsa ve bazıları dağıtıldıysa, beceri veya beceri tüketicisinde hata ayıklamayı öğrenin.

Aksi takdirde, bir beceri tüketicisinde veya beceride, diğer botlarda hata ayıkladığınız gibi hata ayıklayabilirsiniz. Daha fazla bilgi için bkz. Botta hata ayıklama ve Bot Framework Öykünücüsü ile Hata Ayıklama.

Ek bilgi

Genel olarak bir beceri tüketicisi uygulamak için beceri tüketicisini uygulamayı öğrenin.