Implementace příjemce dovedností

PLATÍ PRO: SDK v4

Dovednosti můžete využít k rozšíření dalšího robota. Dovednost je robot, který může provádět sadu úloh pro jiného robota a používá manifest k popisu jeho rozhraní. Kořenový robot je robot orientovaný na uživatele, který může vyvolat jednu nebo více dovedností. Kořenový robot je typ příjemce dovedností.

• Spotřebitel dovedností musí k řízení, ke kterým dovednostem má přístup, používat ověřování deklarací identity.
• Spotřebitel dovedností může používat více dovedností.
• Vývojáři, kteří nemají přístup ke zdrojovému kódu dovednosti, můžou informace v manifestu dovednosti použít k návrhu příjemce dovedností.

Tento článek ukazuje, jak implementovat příjemce dovedností, který používá dovednosti echo k ozvěnu vstupu uživatele. Ukázkový manifest dovednosti a informace o implementaci dovednosti ozvěny najdete v tématu implementace dovednosti.

Informace o používání dialogového okna dovednosti ke využívání dovednosti najdete v tématu Použití dialogového okna ke zpracování dovednosti.

Některé typy uživatelů dovedností nemůžou používat některé typy robotů dovedností. Následující tabulka popisuje podporované kombinace.

	Dovednosti s více tenanty	Dovednost s jedním tenantem	Dovednost spravované identity přiřazené uživatelem
Příjemce s více tenanty	Podporováno	Nepodporováno	Nepodporováno
Příjemce s jedním tenantem	Nepodporováno	Podporováno, pokud obě aplikace patří do stejného tenanta	Podporováno, pokud obě aplikace patří do stejného tenanta
Příjemce spravované identity přiřazené uživatelem	Nepodporováno	Podporováno, pokud obě aplikace patří do stejného tenanta	Podporováno, pokud obě aplikace patří do stejného tenanta

Poznámka:

Sady SDK služby Bot Framework JavaScript, C# a Python budou nadále podporovány, ale sada Java SDK se vyřazuje s konečnou dlouhodobou podporou končící v listopadu 2023.

Stávající roboti sestavení pomocí sady Java SDK budou i nadále fungovat.

Pro nové vytváření robotů zvažte použití Power Virtual Agents a přečtěte si o výběru správného řešení chatovacího robota.

Další informace najdete v tématu Budoucnost vytváření robotů.

Požadavky

• Znalost základů robotů, fungování robotů dovedností a implementace dovednosti
• Volitelně můžete předplatné Azure. Pokud ho nemáte, vytvořte si bezplatný účet před tím, než začnete.
• Kopie ukázky jednoduchých dovedností robota k robotovi v jazyce C#, JavaScript, Java nebo Python

Poznámka:

Od verze 4.11 nepotřebujete ID a heslo aplikace k místnímu otestování příjemce dovedností v bot Framework Emulatoru. Předplatné Azure se stále vyžaduje k nasazení vašeho uživatele do Azure nebo ke využívání nasazené dovednosti.

O této ukázce

Ukázka jednoduchých dovedností robota-robota zahrnuje projekty pro dva roboty:

• Robot dovedností echo, který implementuje dovednosti.
• Jednoduchý kořenový robot, který implementuje kořenového robota, který tuto dovednost využívá.

Tento článek se zaměřuje na kořenového robota, který zahrnuje logiku podpory v objektech robota a adaptérů a obsahuje objekty používané k výměně aktivit s dovedností. Tady jsou některé z nich:

• Kvalifikovaný klient, který se používá k odesílání aktivit do dovednosti.
• Obslužná rutina dovedností, která slouží k získávání aktivit z dovednosti.
• Továrna PRO ID konverzace dovedností, kterou používá klient dovedností a obslužná rutina k překladu mezi odkazem na konverzaci root uživatele a odkazem na konverzaci s kořenovou dovedností.

C#

JavaScript

Java

Python

Informace o robotovi dovedností echo najdete v tématu Implementace dovednosti.

Zdroje informací

U nasazených robotů vyžaduje ověřování robota k robotovi, aby měl každý účastník platné informace o identitě. Můžete ale otestovat dovednosti s více tenanty a uživatele dovedností místně pomocí emulátoru bez ID aplikace a hesla.

Konfigurace aplikací

1. Volitelně můžete do konfiguračního souboru přidat informace o identitě kořenového robota. Pokud dovednost nebo spotřebitel dovedností poskytuje informace o identitě, musí být obojí.
2. Přidejte koncový bod hostitele dovedností (adresu URL služby nebo zpětného volání), do kterého by měly dovednosti odpovídat příjemci dovedností.
3. Přidejte položku pro každou dovednost, která bude spotřebitel dovedností používat. Každá položka zahrnuje:
   • ID, které příjemce dovednosti použije k identifikaci jednotlivých dovedností.
   • Volitelně je možné, že aplikace dovednosti nebo ID klienta.
   • Koncový bod zasílání zpráv dovednosti.

Poznámka:

Pokud dovednost nebo spotřebitel dovedností poskytuje informace o identitě, musí být obojí.

C#

SimpleRootBot\appsettings.json

Volitelně můžete přidat informace o identitě kořenového robota a přidat aplikaci nebo ID klienta pro robota dovedností echo.

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "SkillHostEndpoint": "http://localhost:3978/api/skills/",
  "BotFrameworkSkills": [
    {
      "Id": "EchoSkillBot",
      "AppId": "",
      "SkillEndpoint": "http://localhost:39783/api/messages"
    }
  ]
}

JavaScript

echo-skill-bot/.env

Volitelně můžete přidat informace o identitě kořenového robota a přidat aplikaci nebo ID klienta pro robota dovedností echo.

MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
SkillHostEndpoint=http://localhost:3978/api/skills/

SkillId=EchoSkillBot
SkillAppId=
SkillEndpoint=http://localhost:39783/api/messages

Java

DialogRootBot\application.properties

Volitelně můžete přidat ID a heslo aplikace kořenového robota a přidat ID aplikace pro robota dovednosti echo do BotFrameworkSkills pole.

MicrosoftAppId=
MicrosoftAppPassword=
server.port=3978
SkillhostEndpoint=http://localhost:3978/api/skills/
#replicate these three entries, incrementing the index value [0] for each successive Skill that is added.
BotFrameworkSkills[0].Id=EchoSkillBot
BotFrameworkSkills[0].AppId= "Add the App ID for the skill here"
BotFrameworkSkills[0].SkillEndpoint=http://localhost:39783/api/messages

Python

simple_root_bot/config.py

Volitelně můžete přidat ID aplikace a heslo kořenového robota a přidat ID aplikace pro robota dovednosti echo.

APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
SKILL_HOST_ENDPOINT = "http://localhost:3978/api/skills"
SKILLS = [
    {
        "id": "EchoSkillBot",
        "app_id": "",
        "skill_endpoint": "http://localhost:39783/api/messages",
    },
]

# Callers to only those specified, '*' allows any caller.

Konfigurace dovedností

Tato ukázka čte informace pro každou dovednost v konfiguračním souboru do kolekce objektů dovedností .

C#

SimpleRootBot\SkillsConfiguration.cs

public class SkillsConfiguration
{
    public SkillsConfiguration(IConfiguration configuration)
    {
        var section = configuration?.GetSection("BotFrameworkSkills");
        var skills = section?.Get<BotFrameworkSkill[]>();
        if (skills != null)
        {
            foreach (var skill in skills)
            {
                Skills.Add(skill.Id, skill);
            }
        }

        var skillHostEndpoint = configuration?.GetValue<string>(nameof(SkillHostEndpoint));
        if (!string.IsNullOrWhiteSpace(skillHostEndpoint))
        {
            SkillHostEndpoint = new Uri(skillHostEndpoint);
        }
    }

    public Uri SkillHostEndpoint { get; }

    public Dictionary<string, BotFrameworkSkill> Skills { get; } = new Dictionary<string, BotFrameworkSkill>();
}

JavaScript

simple-root-bot/skillsConfiguration.js

class SkillsConfiguration {
    constructor() {
        this.skillsData = {};

        // Note: we only have one skill in this sample but we could load more if needed.
        const botFrameworkSkill = {
            id: process.env.SkillId,
            appId: process.env.SkillAppId,
            skillEndpoint: process.env.SkillEndpoint
        };

        this.skillsData[botFrameworkSkill.id] = botFrameworkSkill;

        this.skillHostEndpointValue = process.env.SkillHostEndpoint;
        if (!this.skillHostEndpointValue) {
            throw new Error('[SkillsConfiguration]: Missing configuration parameter. SkillHostEndpoint is required');
        }
    }

    get skills() {
        return this.skillsData;
    }

    get skillHostEndpoint() {
        return this.skillHostEndpointValue;
    }
}

Java

DialogRootBot\SkillsConfiguration.java

public class SkillsConfiguration {

    private URI skillHostEndpoint;

    private Map<String, BotFrameworkSkill> skills = new HashMap<String, BotFrameworkSkill>();

    public SkillsConfiguration(Configuration configuration) {

        boolean noMoreEntries = false;
        int indexCount = 0;
        while (!noMoreEntries) {
            String botID = configuration.getProperty(String.format("BotFrameworkSkills[%d].Id", indexCount));
            String botAppId = configuration.getProperty(String.format("BotFrameworkSkills[%d].AppId", indexCount));
            String skillEndPoint =
                configuration.getProperty(String.format("BotFrameworkSkills[%d].SkillEndpoint", indexCount));
            if (
                StringUtils.isNotBlank(botID) && StringUtils.isNotBlank(botAppId)
                    && StringUtils.isNotBlank(skillEndPoint)
            ) {
                BotFrameworkSkill newSkill = new BotFrameworkSkill();
                newSkill.setId(botID);
                newSkill.setAppId(botAppId);
                try {
                    newSkill.setSkillEndpoint(new URI(skillEndPoint));
                } catch (URISyntaxException e) {
                    e.printStackTrace();
                }
                skills.put(botID, newSkill);
                indexCount++;
            } else {
                noMoreEntries = true;
            }
        }

        String skillHost = configuration.getProperty("SkillhostEndpoint");
        if (!StringUtils.isEmpty(skillHost)) {
            try {
                skillHostEndpoint = new URI(skillHost);
            } catch (URISyntaxException e) {
                e.printStackTrace();
            }
        }
    }

    /**
     * @return the SkillHostEndpoint value as a Uri.
     */
    public URI getSkillHostEndpoint() {
        return this.skillHostEndpoint;
    }

    /**
     * @return the Skills value as a Dictionary<String, BotFrameworkSkill>.
     */
    public Map<String, BotFrameworkSkill> getSkills() {
        return this.skills;
    }

}

Python

simple-root-bot/config.py

SKILLS: Dict[str, BotFrameworkSkill] = {
    skill["id"]: BotFrameworkSkill(**skill) for skill in DefaultConfig.SKILLS
}

Objekt pro vytváření ID konverzace

Tím se vytvoří ID konverzace pro použití s dovedností a může obnovit původní ID konverzace uživatele z ID konverzace dovednosti.

Továrna ID konverzace pro tuto ukázku podporuje jednoduchý scénář, ve kterém:

• Kořenový robot je navržený tak, aby spotřebovával jednu konkrétní dovednost.
• Kořenový robot má současně jenom jednu aktivní konverzaci s dovedností.

C#

Sada SDK poskytuje třídu, kterou je možné použít napříč libovolnou SkillConversationIdFactory dovedností, aniž by bylo nutné replikovat zdrojový kód. Objekt pro vytváření ID konverzace je nakonfigurovaný v Startup.cs.

JavaScript

Sada SDK poskytuje třídu, kterou je možné použít napříč libovolnou SkillConversationIdFactory dovedností, aniž by bylo nutné replikovat zdrojový kód. Objekt pro vytváření ID konverzace je nakonfigurovaný v index.js.

Java

Java implementovala třídu SkillConversationIdFactory jako třídu SADY SDK, kterou lze použít napříč libovolnou dovedností, aniž by bylo nutné replikovat zdrojový kód. Kód pro SkillConversationIdFactory najdete ve zdrojovém kódu balíčku botbuilder [kód sady Java SDK botbuilder].

Python

simple-root-bot/skill_conversation_id_factory.py

class SkillConversationIdFactory(ConversationIdFactoryBase):
    def __init__(self, storage: Storage):
        if not storage:
            raise TypeError("storage can't be None")

        self._storage = storage

    async def create_skill_conversation_id(
        self,
        options_or_conversation_reference: Union[
            SkillConversationIdFactoryOptions, ConversationReference
        ],
    ) -> str:
        if not options_or_conversation_reference:
            raise TypeError("Need options or conversation reference")

        if not isinstance(
            options_or_conversation_reference, SkillConversationIdFactoryOptions
        ):
            raise TypeError(
                "This SkillConversationIdFactory can only handle SkillConversationIdFactoryOptions"
            )

        options = options_or_conversation_reference

        # Create the storage key based on the SkillConversationIdFactoryOptions.
        conversation_reference = TurnContext.get_conversation_reference(
            options.activity
        )
        skill_conversation_id = (
            f"{conversation_reference.conversation.id}"
            f"-{options.bot_framework_skill.id}"
            f"-{conversation_reference.channel_id}"
            f"-skillconvo"
        )

        # Create the SkillConversationReference instance.
        skill_conversation_reference = SkillConversationReference(
            conversation_reference=conversation_reference,
            oauth_scope=options.from_bot_oauth_scope,
        )

        # Store the SkillConversationReference using the skill_conversation_id as a key.
        skill_conversation_info = {skill_conversation_id: skill_conversation_reference}
        await self._storage.write(skill_conversation_info)

        # Return the generated skill_conversation_id (that will be also used as the conversation ID to call the skill).
        return skill_conversation_id

    async def get_conversation_reference(
        self, skill_conversation_id: str
    ) -> Union[SkillConversationReference, ConversationReference]:
        if not skill_conversation_id:
            raise TypeError("skill_conversation_id can't be None")

        # Get the SkillConversationReference from storage for the given skill_conversation_id.
        skill_conversation_info = await self._storage.read([skill_conversation_id])

        return skill_conversation_info.get(skill_conversation_id)

    async def delete_conversation_reference(self, skill_conversation_id: str):
        await self._storage.delete([skill_conversation_id])

Pokud chcete podporovat složitější scénáře, navrhněte továrnu PRO ID konverzace tak, aby:

• Metoda ID konverzace pro vytvoření dovednosti získá nebo vygeneruje příslušné ID konverzace dovednosti.
• Metoda získání odkazu na konverzaci získá správnou uživatelskou konverzaci.

Dovednost klient a obslužná rutina dovedností

Spotřebitel dovedností používá klienta dovedností k předávání aktivit dovednostem dovednosti. Klient k tomu používá informace o konfiguraci dovedností a objekt pro vytváření ID konverzace.

Příjemce dovedností používá obslužnou rutinu dovedností k získání aktivit z dovednosti. Obslužná rutina k tomu používá továrnu ID konverzace, konfiguraci ověřování a zprostředkovatele přihlašovacích údajů a také závislosti na adaptéru kořenového robota a obslužné rutině aktivit.

C#

SimpleRootBot\Startup.cs

services.AddSingleton<IBotFrameworkHttpAdapter>(sp => sp.GetService<CloudAdapter>());
services.AddSingleton<BotAdapter>(sp => sp.GetService<CloudAdapter>());

JavaScript

simple-root-bot/index.js

// Create the conversationIdFactory
const conversationIdFactory = new SkillConversationIdFactory(new MemoryStorage());

// Create the skill client.
const skillClient = botFrameworkAuthentication.createBotFrameworkClient();

const handler = new CloudSkillHandler(adapter, (context) => bot.run(context), conversationIdFactory, botFrameworkAuthentication);

Java

DialogRootBot\application.java

@Bean
public SkillHttpClient getSkillHttpClient(
    CredentialProvider credentialProvider,
    SkillConversationIdFactoryBase conversationIdFactory,
    ChannelProvider channelProvider
) {
    return new SkillHttpClient(credentialProvider, conversationIdFactory, channelProvider);
}

@Bean
public SkillConversationIdFactoryBase getSkillConversationIdFactoryBase() {
    return new SkillConversationIdFactory(getStorage());
}

@Bean public ChannelServiceHandler getChannelServiceHandler(
    BotAdapter botAdapter,
    Bot bot,
    SkillConversationIdFactoryBase conversationIdFactory,
    CredentialProvider credentialProvider,
    AuthenticationConfiguration authConfig,
    ChannelProvider channelProvider
) {
    return new SkillHandler(
        botAdapter,
        bot,
        conversationIdFactory,
        credentialProvider,
        authConfig,
        channelProvider);
}

Python

simple-root-bot/app.py

CREDENTIAL_PROVIDER = SimpleCredentialProvider(CONFIG.APP_ID, CONFIG.APP_PASSWORD)
CLIENT = SkillHttpClient(CREDENTIAL_PROVIDER, ID_FACTORY)

    ADAPTER, BOT, ID_FACTORY, CREDENTIAL_PROVIDER, AUTH_CONFIG
)

Přenosy HTTP z dovednosti se dostanou do koncového bodu adresy URL služby, který uživatel dovednosti inzeruje do dovednosti. Pomocí obslužné rutiny koncového bodu specifického pro jazyk předáte provoz obslužné rutině dovedností.

Výchozí obslužná rutina dovedností:

• Pokud je k dispozici ID a heslo aplikace, pomocí objektu konfigurace ověřování provede ověřování jak ověřování robota, tak ověřování deklarací identity.
• Používá továrnu PRO ID konverzace k překladu z konverzace s uživatelskými dovednostmi zpět do konverzace kořenového uživatele.
• Vygeneruje proaktivní zprávu, aby uživatel dovednosti mohl znovu vytvořit kontext uživatele root-uživatel a předat mu aktivity.

Logika obslužné rutiny aktivity

Mějte na paměti, že logika dovednosti spotřebitele by měla:

• Nezapomeňte, jestli existují nějaké aktivní dovednosti a podle potřeby jim předávat aktivity.
• Všimněte si, že uživatel odešle žádost, která by se měla předat dovednostem, a zahájit dovednost.
• endOfConversation Vyhledejte aktivitu z jakékoli aktivní dovednosti, abyste si všimli, kdy se dokončí.
• Pokud je to vhodné, přidejte logiku, která uživateli nebo uživateli dovednosti umožní zrušit dovednost, která ještě nebyla dokončena.
• Před voláním dovednosti uložte stav, protože jakákoli odpověď se může vrátit k jiné instanci příjemce dovedností.

C#

SimpleRootBot\Bots\RootBot.cs

Kořenový robot má závislosti na stavu konverzace, informacích o dovednostech, klientovi dovedností a obecné konfiguraci. ASP.NET tyto objekty poskytuje prostřednictvím injektáže závislostí. Kořenový robot také definuje přístupová vlastnost stavu konverzace ke sledování toho, která dovednost je aktivní.

public static readonly string ActiveSkillPropertyName = $"{typeof(RootBot).FullName}.ActiveSkillProperty";
private readonly IStatePropertyAccessor<BotFrameworkSkill> _activeSkillProperty;
private readonly string _botId;
private readonly ConversationState _conversationState;
private readonly BotFrameworkAuthentication _auth;
private readonly SkillConversationIdFactoryBase _conversationIdFactory;
private readonly SkillsConfiguration _skillsConfig;
private readonly BotFrameworkSkill _targetSkill;

public RootBot(BotFrameworkAuthentication auth, ConversationState conversationState, SkillsConfiguration skillsConfig, SkillConversationIdFactoryBase conversationIdFactory, IConfiguration configuration)
{
    _auth = auth ?? throw new ArgumentNullException(nameof(auth));
    _conversationState = conversationState ?? throw new ArgumentNullException(nameof(conversationState));
    _skillsConfig = skillsConfig ?? throw new ArgumentNullException(nameof(skillsConfig));
    _conversationIdFactory = conversationIdFactory ?? throw new ArgumentNullException(nameof(conversationIdFactory));

    if (configuration == null)
    {
        throw new ArgumentNullException(nameof(configuration));
    }

    _botId = configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;

    // We use a single skill in this example.
    var targetSkillId = "EchoSkillBot";
    _skillsConfig.Skills.TryGetValue(targetSkillId, out _targetSkill);

    // Create state property to track the active skill
    _activeSkillProperty = conversationState.CreateProperty<BotFrameworkSkill>(ActiveSkillPropertyName);
}

Tato ukázka obsahuje pomocnou metodu pro předávání aktivit dovednostem. Uloží stav konverzace před vyvoláním dovednosti a zkontroluje, jestli požadavek HTTP proběhl úspěšně.

private async Task SendToSkill(ITurnContext turnContext, BotFrameworkSkill targetSkill, CancellationToken cancellationToken)
{
    // NOTE: Always SaveChanges() before calling a skill so that any activity generated by the skill
    // will have access to current accurate state.
    await _conversationState.SaveChangesAsync(turnContext, force: true, cancellationToken: cancellationToken);

    // Create a conversationId to interact with the skill and send the activity
    var options = new SkillConversationIdFactoryOptions
    {
        FromBotOAuthScope = turnContext.TurnState.Get<string>(BotAdapter.OAuthScopeKey),
        FromBotId = _botId,
        Activity = turnContext.Activity,
        BotFrameworkSkill = targetSkill
    };
    var skillConversationId = await _conversationIdFactory.CreateSkillConversationIdAsync(options, cancellationToken);

    using var client = _auth.CreateBotFrameworkClient();

    // route the activity to the skill
    var response = await client.PostActivityAsync(_botId, targetSkill.AppId, targetSkill.SkillEndpoint, _skillsConfig.SkillHostEndpoint, skillConversationId, turnContext.Activity, cancellationToken);

    // Check response status
    if (!(response.Status >= 200 && response.Status <= 299))
    {
        throw new HttpRequestException($"Error invoking the skill id: \"{targetSkill.Id}\" at \"{targetSkill.SkillEndpoint}\" (status is {response.Status}). \r\n {response.Body}");
    }
}

Nezapomeňte, že kořenový robot obsahuje logiku pro předávání aktivit dovednosti, spuštění dovednosti na žádost uživatele a zastavení dovednosti po dokončení dovednosti.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    if (turnContext.Activity.Text.Contains("skill"))
    {
        await turnContext.SendActivityAsync(MessageFactory.Text("Got it, connecting you to the skill..."), cancellationToken);

        // Save active skill in state
        await _activeSkillProperty.SetAsync(turnContext, _targetSkill, cancellationToken);

        // Send the activity to the skill
        await SendToSkill(turnContext, _targetSkill, cancellationToken);
        return;
    }

    // just respond
    await turnContext.SendActivityAsync(MessageFactory.Text("Me no nothin'. Say \"skill\" and I'll patch you through"), cancellationToken);

    // Save conversation state
    await _conversationState.SaveChangesAsync(turnContext, force: true, cancellationToken: cancellationToken);
}

protected override async Task OnEndOfConversationActivityAsync(ITurnContext<IEndOfConversationActivity> turnContext, CancellationToken cancellationToken)
{
    // forget skill invocation
    await _activeSkillProperty.DeleteAsync(turnContext, cancellationToken);

    // Show status message, text and value returned by the skill
    var eocActivityMessage = $"Received {ActivityTypes.EndOfConversation}.\n\nCode: {turnContext.Activity.Code}";
    if (!string.IsNullOrWhiteSpace(turnContext.Activity.Text))
    {
        eocActivityMessage += $"\n\nText: {turnContext.Activity.Text}";
    }

    if ((turnContext.Activity as Activity)?.Value != null)
    {
        eocActivityMessage += $"\n\nValue: {JsonConvert.SerializeObject((turnContext.Activity as Activity)?.Value)}";
    }

    await turnContext.SendActivityAsync(MessageFactory.Text(eocActivityMessage), cancellationToken);

    // We are back at the root
    await turnContext.SendActivityAsync(MessageFactory.Text("Back in the root bot. Say \"skill\" and I'll patch you through"), cancellationToken);

    // Save conversation state
    await _conversationState.SaveChangesAsync(turnContext, cancellationToken: cancellationToken);
}

JavaScript

simple-root-bot/rootBot.js

Kořenový robot má závislosti na stavu konverzace, informacích o dovednostech a klientovi dovedností. Kořenový robot také definuje přístupová vlastnost stavu konverzace ke sledování toho, která dovednost je aktivní.

constructor(conversationState, skillsConfig, skillClient, conversationIdFactory) {
    super();
    if (!conversationState) throw new Error('[RootBot]: Missing parameter. conversationState is required');
    if (!skillsConfig) throw new Error('[RootBot]: Missing parameter. skillsConfig is required');
    if (!skillClient) throw new Error('[RootBot]: Missing parameter. skillClient is required');
    if (!conversationIdFactory) throw new Error('[RootBot]: Missing parameter. conversationIdFactory is required');

    this.conversationState = conversationState;
    this.skillsConfig = skillsConfig;
    this.skillClient = skillClient;
    this.conversationIdFactory = conversationIdFactory;

// Create state property to track the active skill
this.activeSkillProperty = this.conversationState.createProperty(RootBot.ActiveSkillPropertyName);

Tato ukázka obsahuje pomocnou metodu pro předávání aktivit dovednostem. Uloží stav konverzace před vyvoláním dovednosti a zkontroluje, jestli požadavek HTTP proběhl úspěšně.

async sendToSkill(context, targetSkill) {
    // NOTE: Always SaveChanges() before calling a skill so that any activity generated by the skill
    // will have access to current accurate state.
    await this.conversationState.saveChanges(context, true);

    // Create a conversationId to interact with the skill and send the activity
    const skillConversationId = await this.conversationIdFactory.createSkillConversationIdWithOptions({
        fromBotOAuthScope: context.turnState.get(context.adapter.OAuthScopeKey),
        fromBotId: this.botId,
        activity: context.activity,
        botFrameworkSkill: this.targetSkill
    });

    // route the activity to the skill
    const response = await this.skillClient.postActivity(this.botId, targetSkill.appId, targetSkill.skillEndpoint, this.skillsConfig.skillHostEndpoint, skillConversationId, context.activity);

    // Check response status
    if (!(response.status >= 200 && response.status <= 299)) {
        throw new Error(`[RootBot]: Error invoking the skill id: "${ targetSkill.id }" at "${ targetSkill.skillEndpoint }" (status is ${ response.status }). \r\n ${ response.body }`);
    }
}

Nezapomeňte, že kořenový robot obsahuje logiku pro předávání aktivit dovednosti, spuštění dovednosti na žádost uživatele a zastavení dovednosti po dokončení dovednosti.

// See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
this.onMessage(async (context, next) => {
    if (context.activity.text.toLowerCase() === 'skill') {
        await context.sendActivity('Got it, connecting you to the skill...');

        // Set active skill
        await this.activeSkillProperty.set(context, this.targetSkill);

        // Send the activity to the skill
        await this.sendToSkill(context, this.targetSkill);
    } else {
        await context.sendActivity("Me no nothin'. Say 'skill' and I'll patch you through");
    }

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

// Handle EndOfConversation returned by the skill.
this.onEndOfConversation(async (context, next) => {
    // Stop forwarding activities to Skill.
    await this.activeSkillProperty.set(context, undefined);

    // Show status message, text and value returned by the skill
    let eocActivityMessage = `Received ${ ActivityTypes.EndOfConversation }.\n\nCode: ${ context.activity.code }`;
    if (context.activity.text) {
        eocActivityMessage += `\n\nText: ${ context.activity.text }`;
    }

    if (context.activity.value) {
        eocActivityMessage += `\n\nValue: ${ context.activity.value }`;
    }

    await context.sendActivity(eocActivityMessage);

    // We are back at the root
    await context.sendActivity('Back in the root bot. Say \'skill\' and I\'ll patch you through');

    // Save conversation state
    await this.conversationState.saveChanges(context, true);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

DialogRootBot\RootBot.java

Kořenový robot má závislosti na stavu konverzace, informacích o dovednostech, klientovi dovedností a obecné konfiguraci. ASP.NET tyto objekty poskytuje prostřednictvím injektáže závislostí. Kořenový robot také definuje přístupová vlastnost stavu konverzace ke sledování toho, která dovednost je aktivní.

public static final String ActiveSkillPropertyName = "com.microsoft.bot.sample.simplerootbot.ActiveSkillProperty";
private StatePropertyAccessor<BotFrameworkSkill> activeSkillProperty;
private String botId;
private ConversationState conversationState;
private SkillHttpClient skillClient;
private SkillsConfiguration skillsConfig;
private BotFrameworkSkill targetSkill;

public RootBot(
    ConversationState conversationState,
    SkillsConfiguration skillsConfig,
    SkillHttpClient skillClient,
    Configuration configuration
) {
    if (conversationState == null) {
        throw new  IllegalArgumentException("conversationState cannot be null.");
    }

    if (skillsConfig == null) {
        throw new  IllegalArgumentException("skillsConfig cannot be null.");
    }

    if (skillClient == null) {
        throw new  IllegalArgumentException("skillsClient cannot be null.");
    }

    if (configuration == null) {
        throw new  IllegalArgumentException("configuration cannot be null.");
    }


    this.conversationState = conversationState;
    this.skillsConfig = skillsConfig;
    this.skillClient = skillClient;

    botId = configuration.getProperty(MicrosoftAppCredentials.MICROSOFTAPPID);

    if (StringUtils.isEmpty(botId)) {
        throw new IllegalArgumentException(String.format("%s instanceof not set in configuration",
                                                         MicrosoftAppCredentials.MICROSOFTAPPID));
    }

    // We use a single skill in this example.
    String targetSkillId = "EchoSkillBot";
    if (!skillsConfig.getSkills().containsKey(targetSkillId)) {
        throw new IllegalArgumentException(
            String.format("Skill with ID \"%s\" not found in configuration", targetSkillId)
        );
    } else {
        targetSkill = (BotFrameworkSkill) skillsConfig.getSkills().get(targetSkillId);
    }

    // Create state property to track the active skill
    activeSkillProperty = conversationState.createProperty(ActiveSkillPropertyName);
}

Tato ukázka obsahuje pomocnou metodu pro předávání aktivit dovednostem. Uloží stav konverzace před vyvoláním dovednosti a zkontroluje, jestli požadavek HTTP proběhl úspěšně.

private CompletableFuture<Void> sendToSkill(TurnContext turnContext, BotFrameworkSkill targetSkill) {
    // NOTE: Always SaveChanges() before calling a skill so that any activity generated by the skill
    // will have access to current accurate state.
     return conversationState.saveChanges(turnContext, true)
     .thenAccept(result -> {
        // route the activity to the skill
        skillClient.postActivity(botId,
                                targetSkill,
                                skillsConfig.getSkillHostEndpoint(),
                                turnContext.getActivity(),
                                Object.class)
        .thenApply(response -> {
        // Check response status
        if (!(response.getStatus() >= 200 && response.getStatus() <= 299)) {
                throw new RuntimeException(
                    String.format(
                        "Error invoking the skill id: \"%s\" at \"%s\" (status instanceof %s). \r\n %s",
                        targetSkill.getId(),
                        targetSkill.getSkillEndpoint(),
                        response.getStatus(),
                        response.getBody()));
            }
            return CompletableFuture.completedFuture(null);
        });
     });
}

Nezapomeňte, že kořenový robot obsahuje logiku pro předávání aktivit dovednosti, spuštění dovednosti na žádost uživatele a zastavení dovednosti po dokončení dovednosti.

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    if (turnContext.getActivity().getText().contains("skill")) {
        return turnContext.sendActivity(MessageFactory.text("Got it, connecting you to the skill..."))
        .thenCompose(result -> {
            activeSkillProperty.set(turnContext, targetSkill);
            // Send the activity to the skill
            return sendToSkill(turnContext, targetSkill);
        });
    }

    // just respond
     return turnContext.sendActivity(
         MessageFactory.text("Me no nothin'. Say \"skill\" and I'll patch you through"))
     .thenCompose(result -> conversationState.saveChanges(turnContext, true));
}

@Override
protected CompletableFuture<Void> onEndOfConversationActivity(TurnContext turnContext) {
    // forget skill invocation
     return activeSkillProperty.delete(turnContext).thenAccept(result -> {
        // Show status message, text and value returned by the skill
        String eocActivityMessage = String.format("Received %s.\n\nCode: %s",
                                                   ActivityTypes.END_OF_CONVERSATION,
                                                   turnContext.getActivity().getCode());

        if (!StringUtils.isEmpty(turnContext.getActivity().getText())) {
            eocActivityMessage += String.format("\n\nText: %s", turnContext.getActivity().getText());
        }

        if (turnContext.getActivity() != null && turnContext.getActivity().getValue() != null) {
            eocActivityMessage += String.format("\n\nValue: %s", turnContext.getActivity().getValue());
        }

        turnContext.sendActivity(MessageFactory.text(eocActivityMessage)).thenCompose(sendResult ->{
            // We are back at the root
            return turnContext.sendActivity(
            MessageFactory.text("Back in the root bot. Say \"skill\" and I'll patch you through"))
            .thenCompose(secondSendResult-> conversationState.saveChanges(turnContext));
        });
     });
}

Python

simple-root-bot/bots/root_bot.py

Kořenový robot má závislosti na stavu konverzace, informacích o dovednostech, klientovi dovedností a obecné konfiguraci. Kořenový robot také definuje přístupová vlastnost stavu konverzace ke sledování toho, která dovednost je aktivní.

def __init__(
    self,
    conversation_state: ConversationState,
    skills_config: SkillConfiguration,
    skill_client: SkillHttpClient,
    config: DefaultConfig,
):
    self._bot_id = config.APP_ID
    self._skill_client = skill_client
    self._skills_config = skills_config
    self._conversation_state = conversation_state
    self._active_skill_property = conversation_state.create_property(
        ACTIVE_SKILL_PROPERTY_NAME
    )

Tato ukázka obsahuje pomocnou metodu pro předávání aktivit dovednostem. Uloží stav konverzace před vyvoláním dovednosti a zkontroluje, jestli požadavek HTTP proběhl úspěšně.

async def __send_to_skill(
    self, turn_context: TurnContext, target_skill: BotFrameworkSkill
):
    # NOTE: Always SaveChanges() before calling a skill so that any activity generated by the skill
    # will have access to current accurate state.
    await self._conversation_state.save_changes(turn_context, force=True)

    # route the activity to the skill
    await self._skill_client.post_activity_to_skill(
        self._bot_id,
        target_skill,
        self._skills_config.SKILL_HOST_ENDPOINT,
        turn_context.activity,
    )

Nezapomeňte, že kořenový robot obsahuje logiku pro předávání aktivit dovednosti, spuštění dovednosti na žádost uživatele a zastavení dovednosti po dokončení dovednosti.

async def on_message_activity(self, turn_context: TurnContext):
    if "skill" in turn_context.activity.text:
        # Begin forwarding Activities to the skill
        await turn_context.send_activity(
            MessageFactory.text("Got it, connecting you to the skill...")
        )

        skill = self._skills_config.SKILLS[TARGET_SKILL_ID]
        # Save active skill in state
        await self._active_skill_property.set(turn_context, skill)

        # Send the activity to the skill
        await self.__send_to_skill(turn_context, skill)
    else:
        # just respond
        await turn_context.send_activity(
            MessageFactory.text(
                "Me no nothin'. Say \"skill\" and I'll patch you through"
            )
        )

async def on_end_of_conversation_activity(self, turn_context: TurnContext):
    # forget skill invocation
    await self._active_skill_property.delete(turn_context)

    eoc_activity_message = f"Received {ActivityTypes.end_of_conversation}.\n\nCode: {turn_context.activity.code}"
    if turn_context.activity.text:
        eoc_activity_message = (
            eoc_activity_message + f"\n\nText: {turn_context.activity.text}"
        )

    if turn_context.activity.value:
        eoc_activity_message = (
            eoc_activity_message + f"\n\nValue: {turn_context.activity.value}"
        )

    await turn_context.send_activity(eoc_activity_message)

    # We are back
    await turn_context.send_activity(
        MessageFactory.text(
            'Back in the root bot. Say "skill" and I\'ll patch you through'
        )
    )

    await self._conversation_state.save_changes(turn_context, force=True)

Při zapnutí obslužné rutiny chyby

Když dojde k chybě, adaptér vymaže stav konverzace, aby se obnovila konverzace s uživatelem a zabránila zachování chybového stavu.

Před vymazáním stavu konverzace v konzumentovi dovedností je vhodné odeslat konec konverzační aktivity jakékoli aktivní dovednosti. Díky tomu může dovednost uvolnit všechny prostředky přidružené ke konverzaci s uživatelskými dovednostmi předtím, než uživatel dovednosti uvolní konverzaci.

C#

SimpleRootBot\AdapterWithErrorHandler.cs

V této ukázce je logika chyby otáčení rozdělena mezi několik pomocných metod.

private async Task HandleTurnError(ITurnContext turnContext, Exception exception)
{
    // Log any leaked exception from the application.
    // NOTE: In production environment, you should consider logging this to
    // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
    // to add telemetry capture to your bot.
    _logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

    await SendErrorMessageAsync(turnContext, exception);
    await EndSkillConversationAsync(turnContext);
    await ClearConversationStateAsync(turnContext);
}

private async Task SendErrorMessageAsync(ITurnContext turnContext, Exception exception)
{
    try
    {
        // Send a message to the user
        var errorMessageText = "The bot encountered an error or bug.";
        var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
        await turnContext.SendActivityAsync(errorMessage);

        errorMessageText = "To continue to run this bot, please fix the bot source code.";
        errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
        await turnContext.SendActivityAsync(errorMessage);

        // Send a trace activity, which will be displayed in the Bot Framework Emulator
        await turnContext.TraceActivityAsync("OnTurnError Trace", exception.ToString(), "https://www.botframework.com/schemas/error", "TurnError");
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught in SendErrorMessageAsync : {ex}");
    }
}

private async Task EndSkillConversationAsync(ITurnContext turnContext)
{
    if (_skillsConfig == null)
    {
        return;
    }

    try
    {
        // Inform the active skill that the conversation is ended so that it has
        // a chance to clean up.
        // Note: ActiveSkillPropertyName is set by the RooBot while messages are being
        // forwarded to a Skill.
        var activeSkill = await _conversationState.CreateProperty<BotFrameworkSkill>(RootBot.ActiveSkillPropertyName).GetAsync(turnContext, () => null);
        if (activeSkill != null)
        {
            var botId = _configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;

            var endOfConversation = Activity.CreateEndOfConversationActivity();
            endOfConversation.Code = "RootSkillError";
            endOfConversation.ApplyConversationReference(turnContext.Activity.GetConversationReference(), true);

            await _conversationState.SaveChangesAsync(turnContext, true);

            using var client = _auth.CreateBotFrameworkClient();

            await client.PostActivityAsync(botId, activeSkill.AppId, activeSkill.SkillEndpoint, _skillsConfig.SkillHostEndpoint, endOfConversation.Conversation.Id, (Activity)endOfConversation, CancellationToken.None);
        }
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught on attempting to send EndOfConversation : {ex}");
    }
}

private async Task ClearConversationStateAsync(ITurnContext turnContext)
{
    try
    {
        // Delete the conversationState for the current conversation to prevent the
        // bot from getting stuck in a error-loop caused by being in a bad state.
        // ConversationState should be thought of as similar to "cookie-state" in a Web pages.
        await _conversationState.DeleteAsync(turnContext);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught on attempting to Delete ConversationState : {ex}");
    }
}

JavaScript

simple-root-bot/index.js

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to the console log, instead of to app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

    await sendErrorMessage(context, error);
    await endSkillConversation(context);
    await clearConversationState(context);
};

async function sendErrorMessage(context, error) {
    try {
        // Send a message to the user.
        let onTurnErrorMessage = 'The bot encountered an error or bug.';
        await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.IgnoringInput);

        onTurnErrorMessage = 'To continue to run this bot, please fix the bot source code.';
        await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);

        // Send a trace activity, which will be displayed in Bot Framework Emulator.
        await context.sendTraceActivity(
            'OnTurnError Trace',
            `${ error }`,
            'https://www.botframework.com/schemas/error',
            'TurnError'
        );
    } catch (err) {
        console.error(`\n [onTurnError] Exception caught in sendErrorMessage: ${ err }`);
    }
}

async function endSkillConversation(context) {
    try {
        // Inform the active skill that the conversation is ended so that it has
        // a chance to clean up.
        // Note: ActiveSkillPropertyName is set by the RooBot while messages are being
        // forwarded to a Skill.
        const activeSkill = await conversationState.createProperty(RootBot.ActiveSkillPropertyName).get(context);
        if (activeSkill) {
            const botId = process.env.MicrosoftAppId;

            let endOfConversation = {
                type: ActivityTypes.EndOfConversation,
                code: 'RootSkillError'
            };
            endOfConversation = TurnContext.applyConversationReference(
                endOfConversation, TurnContext.getConversationReference(context.activity), true);

            await conversationState.saveChanges(context, true);
            await skillClient.postActivity(botId, activeSkill.appId, activeSkill.skillEndpoint, skillsConfig.skillHostEndpoint, endOfConversation.conversation.id, endOfConversation);
        }
    } catch (err) {
        console.error(`\n [onTurnError] Exception caught on attempting to send EndOfConversation : ${ err }`);
    }
}

async function clearConversationState(context) {
    try {
        // Delete the conversationState for the current conversation to prevent the
        // bot from getting stuck in a error-loop caused by being in a bad state.
        // ConversationState should be thought of as similar to "cookie-state" in a Web page.
        await conversationState.delete(context);
    } catch (err) {
        console.error(`\n [onTurnError] Exception caught on attempting to Delete ConversationState : ${ err }`);
    }
}

Java

DialogRootBot\SkillAdapterWithErrorHandler.java

V této ukázce je logika chyby otáčení rozdělena mezi několik pomocných metod.

private class SkillAdapterErrorHandler implements OnTurnErrorHandler {

    @Override
    public CompletableFuture<Void> invoke(TurnContext turnContext, Throwable exception) {
        return sendErrorMessage(turnContext, exception).thenAccept(result -> {
            endSkillConversation(turnContext);
        }).thenAccept(endResult -> {
            clearConversationState(turnContext);
        });
    }

    private CompletableFuture<Void> sendErrorMessage(TurnContext turnContext, Throwable exception) {
        try {
            // Send a message to the user.
            String errorMessageText = "The bot encountered an error or bug.";
            Activity errorMessage =
                MessageFactory.text(errorMessageText, errorMessageText, InputHints.IGNORING_INPUT);
            return turnContext.sendActivity(errorMessage).thenAccept(result -> {
                String secondLineMessageText = "To continue to run this bot, please fix the bot source code.";
                Activity secondErrorMessage =
                    MessageFactory.text(secondLineMessageText, secondLineMessageText, InputHints.EXPECTING_INPUT);
                turnContext.sendActivity(secondErrorMessage)
                    .thenApply(
                        sendResult -> {
                            // Send a trace activity, which will be displayed in the Bot Framework Emulator.
                            // Note: we return the entire exception in the value property to help the
                            // developer;
                            // this should not be done in production.
                            return TurnContext.traceActivity(
                                turnContext,
                                String.format("OnTurnError Trace %s", exception.toString())
                            );
                        }
                    );
            }).thenApply(finalResult -> null);

        } catch (Exception ex) {
            return Async.completeExceptionally(ex);
        }
    }

    private CompletableFuture<Void> endSkillConversation(TurnContext turnContext) {
        if (skillHttpClient == null || skillsConfiguration == null) {
            return CompletableFuture.completedFuture(null);
        }

        // Inform the active skill that the conversation instanceof ended so that it has
        // a chance to clean up.
        // Note: ActiveSkillPropertyName instanceof set by the RooBot while messages are
        // being
        StatePropertyAccessor<BotFrameworkSkill> skillAccessor =
            conversationState.createProperty(RootBot.ActiveSkillPropertyName);
        // forwarded to a Skill.
        return skillAccessor.get(turnContext, () -> null).thenApply(activeSkill -> {
            if (activeSkill != null) {
                String botId = configuration.getProperty(MicrosoftAppCredentials.MICROSOFTAPPID);

                Activity endOfConversation = Activity.createEndOfConversationActivity();
                endOfConversation.setCode(EndOfConversationCodes.ROOT_SKILL_ERROR);
                endOfConversation
                    .applyConversationReference(turnContext.getActivity().getConversationReference(), true);

                return conversationState.saveChanges(turnContext, true).thenCompose(saveResult -> {
                    return skillHttpClient.postActivity(
                        botId,
                        activeSkill,
                        skillsConfiguration.getSkillHostEndpoint(),
                        endOfConversation,
                        Object.class
                    );

                });
            }
            return CompletableFuture.completedFuture(null);
        }).thenApply(result -> null);
    }

    private CompletableFuture<Void> clearConversationState(TurnContext turnContext) {
        try {
            return conversationState.delete(turnContext);
        } catch (Exception ex) {
            return Async.completeExceptionally(ex);
        }
    }

}

Python

simple-root-bot/adapter_with_error_handler.py

    # This check writes out errors to console log
    # NOTE: In production environment, you should consider logging this to Azure
    #       application insights.
    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
    traceback.print_exc()
    await self._send_error_message(turn_context, error)
    await self._end_skill_conversation(turn_context, error)
    await self._clear_conversation_state(turn_context)

async def _send_error_message(self, turn_context: TurnContext, error: Exception):
    if not self._skill_client or not self._skill_config:
        return
    try:
        # Send a message to the user.
        error_message_text = "The skill encountered an error or bug."
        error_message = MessageFactory.text(
            error_message_text, error_message_text, InputHints.ignoring_input
        )
        await turn_context.send_activity(error_message)

        error_message_text = (
            "To continue to run this bot, please fix the bot source code."
        )
        error_message = MessageFactory.text(
            error_message_text, error_message_text, InputHints.ignoring_input
        )
        await turn_context.send_activity(error_message)

        # Send a trace activity, which will be displayed in Bot Framework Emulator.
        await turn_context.send_trace_activity(
            label="TurnError",
            name="on_turn_error Trace",
            value=f"{error}",
            value_type="https://www.botframework.com/schemas/error",
        )
    except Exception as exception:
        print(
            f"\n Exception caught on _send_error_message : {exception}",
            file=sys.stderr,
        )
        traceback.print_exc()

async def _end_skill_conversation(
    self, turn_context: TurnContext, error: Exception
):
    if not self._skill_client or not self._skill_config:
        return

    try:
        # Inform the active skill that the conversation is ended so that it has a chance to clean up.
        # Note: the root bot manages the ActiveSkillPropertyName, which has a value while the root bot
        # has an active conversation with a skill.
        active_skill = await self._conversation_state.create_property(
            ACTIVE_SKILL_PROPERTY_NAME
        ).get(turn_context)

        if active_skill:
            bot_id = self._config.APP_ID
            end_of_conversation = Activity(type=ActivityTypes.end_of_conversation)
            end_of_conversation.code = "RootSkillError"
            TurnContext.apply_conversation_reference(
                end_of_conversation,
                TurnContext.get_conversation_reference(turn_context.activity),
                True,
            )

            await self._conversation_state.save_changes(turn_context, True)
            await self._skill_client.post_activity_to_skill(
                bot_id,
                active_skill,
                self._skill_config.SKILL_HOST_ENDPOINT,
                end_of_conversation,
            )
    except Exception as exception:
        print(
            f"\n Exception caught on _end_skill_conversation : {exception}",
            file=sys.stderr,
        )
        traceback.print_exc()

async def _clear_conversation_state(self, turn_context: TurnContext):
    try:
        # Delete the conversationState for the current conversation to prevent the
        # bot from getting stuck in a error-loop caused by being in a bad state.
        # ConversationState should be thought of as similar to "cookie-state" for a Web page.
        await self._conversation_state.delete(turn_context)
    except Exception as exception:
        print(
            f"\n Exception caught on _clear_conversation_state : {exception}",
            file=sys.stderr,
        )
        traceback.print_exc()

Koncový bod dovedností

Robot definuje koncový bod, který předává příchozí aktivity dovedností obslužné rutině dovedností kořenového robota.

C#

SimpleRootBot\Controllers\SkillController.cs

[ApiController]
[Route("api/skills")]
public class SkillController : ChannelServiceController
{
    public SkillController(ChannelServiceHandlerBase handler)
        : base(handler)
    {
    }
}

JavaScript

simple-root-bot/index.js

const handler = new CloudSkillHandler(adapter, (context) => bot.run(context), conversationIdFactory, botFrameworkAuthentication);
const skillEndpoint = new ChannelServiceRoutes(handler);
skillEndpoint.register(server, '/api/skills');

Java

DialogRootBot\Controllers\SkillController.java

@RestController
@RequestMapping(value = {"/api/skills"})
public class SkillController extends ChannelServiceController {

    public SkillController(ChannelServiceHandler handler) {
        super(handler);
    }
}

Python

simple-root-bot/app.py

APP.router.add_post("/api/messages", messages)

Registrace služby

Zahrňte objekt konfigurace ověřování s ověřením deklarací identity a všechny další objekty. Tato ukázka používá stejnou logiku konfigurace ověřování k ověřování aktivit uživatelů i dovedností.

C#

SimpleRootBot\Startup.cs

// Register the skills configuration class
services.AddSingleton<SkillsConfiguration>();

// Register AuthConfiguration to enable custom claim validation.
services.AddSingleton(sp =>
{
    var allowedSkills = sp.GetService<SkillsConfiguration>().Skills.Values.Select(s => s.AppId).ToList();

    var claimsValidator = new AllowedSkillsClaimsValidator(allowedSkills);

    // If TenantId is specified in config, add the tenant as a valid JWT token issuer for Bot to Skill conversation.
    // The token issuer for MSI and single tenant scenarios will be the tenant where the bot is registered.
    var validTokenIssuers = new List<string>();
    var tenantId = sp.GetService<IConfiguration>().GetSection(MicrosoftAppCredentials.MicrosoftAppTenantIdKey)?.Value;

    if (!string.IsNullOrWhiteSpace(tenantId))
    {
        // For SingleTenant/MSI auth, the JWT tokens will be issued from the bot's home tenant.
        // Therefore, these issuers need to be added to the list of valid token issuers for authenticating activity requests.
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidTokenIssuerUrlTemplateV1, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidTokenIssuerUrlTemplateV2, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV1, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV2, tenantId));
    }

    return new AuthenticationConfiguration
    {
        ClaimsValidator = claimsValidator,
        ValidTokenIssuers = validTokenIssuers
    };
});

JavaScript

simple-root-bot/index.js

// Load skills configuration
const skillsConfig = new SkillsConfiguration();

const allowedSkills = Object.values(skillsConfig.skills).map(skill => skill.appId);

const claimsValidators = allowedCallersClaimsValidator(allowedSkills);

// If the MicrosoftAppTenantId is specified in the environment config, add the tenant as a valid JWT token issuer for Bot to Skill conversation.
// The token issuer for MSI and single tenant scenarios will be the tenant where the bot is registered.
let validTokenIssuers = [];
const { MicrosoftAppTenantId } = process.env;

if (MicrosoftAppTenantId) {
    // For SingleTenant/MSI auth, the JWT tokens will be issued from the bot's home tenant.
    // Therefore, these issuers need to be added to the list of valid token issuers for authenticating activity requests.
    validTokenIssuers = [
        `${ AuthenticationConstants.ValidTokenIssuerUrlTemplateV1 }${ MicrosoftAppTenantId }/`,
        `${ AuthenticationConstants.ValidTokenIssuerUrlTemplateV2 }${ MicrosoftAppTenantId }/v2.0/`,
        `${ AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV1 }${ MicrosoftAppTenantId }/`,
        `${ AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV2 }${ MicrosoftAppTenantId }/v2.0/`
    ];
}

// Define our authentication configuration.
const authConfig = new AuthenticationConfiguration([], claimsValidators, validTokenIssuers);

const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
    MicrosoftAppId: process.env.MicrosoftAppId,
    MicrosoftAppPassword: process.env.MicrosoftAppPassword,
    MicrosoftAppType: process.env.MicrosoftAppType,
    MicrosoftAppTenantId: process.env.MicrosoftAppTenantId
});

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env, credentialsFactory, authConfig);

Java

DialogRootBot\Application.java

/**
 * This class extends the BotDependencyConfiguration which provides the default
 * implementations for a Bot application.  The Application class should
 * override methods in order to provide custom implementations.
 */
public class Application extends BotDependencyConfiguration {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    /**
     * Returns the Bot for this application.
     *
     * <p>
     *     The @Component annotation could be used on the Bot class instead of this method
     *     with the @Bean annotation.
     * </p>
     *
     * @return The Bot implementation for this application.
     */
    @Bean
    public Bot getBot(
        ConversationState conversationState,
        SkillsConfiguration skillsConfig,
        SkillHttpClient skillClient,
        Configuration configuration
    ) {
        return new RootBot(conversationState, skillsConfig, skillClient, configuration);
    }

    @Override
    public AuthenticationConfiguration getAuthenticationConfiguration(Configuration configuration) {
        AuthenticationConfiguration authenticationConfiguration = new AuthenticationConfiguration();
        authenticationConfiguration.setClaimsValidator(
            new AllowedSkillsClaimsValidator(getSkillsConfiguration(configuration)));
        return authenticationConfiguration;
    }

    /**
     * Returns a custom Adapter that provides error handling.
     *
     * @param configuration The Configuration object to use.
     * @return An error handling BotFrameworkHttpAdapter.
     */
    @Override
    public BotFrameworkHttpAdapter getBotFrameworkHttpAdaptor(Configuration configuration) {
        return new SkillAdapterWithErrorHandler(
                                configuration,
                                getConversationState(new MemoryStorage()),
                                getSkillHttpClient(
                                    getCredentialProvider(configuration),
                                    getSkillConversationIdFactoryBase(),
                                    getChannelProvider(configuration)),
                                getSkillsConfiguration(configuration));
    }

    @Bean
    public SkillsConfiguration getSkillsConfiguration(Configuration configuration) {
        return new SkillsConfiguration(configuration);
    }

    @Bean
    public SkillHttpClient getSkillHttpClient(
        CredentialProvider credentialProvider,
        SkillConversationIdFactoryBase conversationIdFactory,
        ChannelProvider channelProvider
    ) {
        return new SkillHttpClient(credentialProvider, conversationIdFactory, channelProvider);
    }

    @Bean
    public SkillConversationIdFactoryBase getSkillConversationIdFactoryBase() {
        return new SkillConversationIdFactory(getStorage());
    }

    @Bean public ChannelServiceHandler getChannelServiceHandler(
        BotAdapter botAdapter,
        Bot bot,
        SkillConversationIdFactoryBase conversationIdFactory,
        CredentialProvider credentialProvider,
        AuthenticationConfiguration authConfig,
        ChannelProvider channelProvider
    ) {
        return new SkillHandler(
            botAdapter,
            bot,
            conversationIdFactory,
            credentialProvider,
            authConfig,
            channelProvider);
    }
}

Python

simple-root-bot/app.py

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
SETTINGS = ConfigurationBotFrameworkAuthentication(
    CONFIG,
    auth_configuration=AUTH_CONFIG,
)

STORAGE = MemoryStorage()
CONVERSATION_STATE = ConversationState(STORAGE)

ID_FACTORY = SkillConversationIdFactory(STORAGE)
CREDENTIAL_PROVIDER = SimpleCredentialProvider(CONFIG.APP_ID, CONFIG.APP_PASSWORD)
CLIENT = SkillHttpClient(CREDENTIAL_PROVIDER, ID_FACTORY)

ADAPTER = AdapterWithErrorHandler(
    SETTINGS, CONFIG, CONVERSATION_STATE, CLIENT, SKILL_CONFIG
)

# Create the Bot
BOT = RootBot(CONVERSATION_STATE, SKILL_CONFIG, CLIENT, CONFIG)

SKILL_HANDLER = SkillHandler(
    ADAPTER, BOT, ID_FACTORY, CREDENTIAL_PROVIDER, AUTH_CONFIG
)


# Listen for incoming requests on /api/messages
async def messages(req: Request) -> Response:
    # Main bot message handler.
    if "application/json" in req.headers["Content-Type"]:
        body = await req.json()
    else:
        return Response(status=HTTPStatus.UNSUPPORTED_MEDIA_TYPE)

    activity = Activity().deserialize(body)
    auth_header = req.headers["Authorization"] if "Authorization" in req.headers else ""

    invoke_response = await ADAPTER.process_activity(auth_header, activity, BOT.on_turn)
    if invoke_response:
        return json_response(data=invoke_response.body, status=invoke_response.status)
    return Response(status=HTTPStatus.OK)

Testování kořenového robota

Uživatele dovednosti můžete otestovat v emulátoru, jako by šlo o normálního robota. Musíte však současně spouštět dovednosti i roboty uživatelů. Podívejte se, jak implementovat dovednost s informacemi o konfiguraci dovednosti.

Stažení a instalace nejnovější aplikace Bot Framework Emulator

1. Spusťte robota dovednosti echo a jednoduchého kořenového robota místně na svém počítači. Pokud potřebujete pokyny, projděte si README soubor ukázky C#, JavaScriptu, Javy nebo Pythonu .
2. Pomocí emulátoru otestujte robota, jak je znázorněno níže. Když dovednost pošlete end nebo stop pošlete zprávu, dovednost odešle kořenovému robotovi endOfConversation aktivitu kromě zprávy odpovědi. endOfConversation Vlastnost kódu aktivity označuje, že dovednost byla úspěšně dokončena.

Další informace o ladění

Vzhledem k tomu, že se ověřuje provoz mezi dovednostmi a uživateli dovedností, při ladění takových robotů existují další kroky.

• Dovednost konzument a všechny dovednosti, které využívá, přímo nebo nepřímo, musí být spuštěné.
• Pokud jsou roboti spuštěni místně a pokud některý z robotů má ID a heslo aplikace, musí mít všichni roboti platné ID a hesla.
• Pokud jsou roboti všichni nasazeni, podívejte se , jak ladit robota z libovolného kanálu pomocí nástroje ngrok.
• Pokud některé roboty běží místně a některé se nasadí, podívejte se , jak ladit dovednosti nebo příjemce dovedností.

Jinak můžete ladit dovednost uživatele nebo dovednosti podobně jako ostatní roboty. Další informace naleznete v tématu Ladění robota a ladění pomocí bot Framework Emulator.

Další informace

Tady je několik věcí, které je potřeba zvážit při implementaci složitějšího kořenového robota.

Povolení zrušení vícestupňové dovednosti uživateli

Kořenový robot by měl před předáním zprávy uživatele do aktivní dovednosti zkontrolovat zprávu uživatele. Pokud chce uživatel zrušit aktuální proces, může kořenový robot odeslat aktivitu dovednosti místo přeposílání endOfConversation zprávy.

Výměna dat mezi kořenovými roboty a roboty dovedností

Pokud chcete posílat parametry dovednosti, může uživatel dovednosti nastavit vlastnost hodnoty u zpráv, které odesílá do dovednosti. Pokud chcete získat návratové hodnoty z dovednosti, měl by příjemce dovednosti zkontrolovat vlastnost hodnoty , když dovednost odešle endOfConversation aktivitu.

Použití více dovedností

• Pokud je dovednost aktivní, musí kořenový robot určit, která dovednost je aktivní, a předat zprávu uživatele správné dovednosti.
• Pokud žádná dovednost není aktivní, musí kořenový robot určit, která dovednost se má spustit( pokud existuje) na základě stavu robota a vstupu uživatele.
• Pokud chcete uživateli umožnit přepínání mezi více souběžnými dovednostmi, musí kořenový robot určit, se kterými aktivními dovednostmi chce uživatel pracovat, než zprávu uživatele přeposílá.

Použití režimu doručení očekávaných odpovědí

Použití režimu doručení očekávaných odpovědí :

• Naklonujte aktivitu z kontextu otáčení.
• Před odesláním aktivity od kořenového robota do dovednosti nastavte vlastnost režimu doručení nové aktivity na "ExpectReplies".
• Přečtěte si očekávané odpovědi z textu odpovědi vyvolání vráceného z odpovědi požadavku.
• Zpracujte každou aktivitu buď v rámci kořenového robota, nebo ji odešlete na kanál, který inicioval původní požadavek.

Očekávané odpovědi můžou být užitečné v situacích, kdy robot, který odpoví na aktivitu, musí být stejnou instancí robota, který aktivitu přijal.