スキルの概要Skills overview

適用対象: 対象 SDK v4 対象外 SDK v3 APPLIES TO: yesSDK v4 no SDK v3

Bot Framework SDK のバージョン 4.7 以降では、別のボット (スキル) を使用してボットを拡張することができます。Starting with version 4.7 of the Bot Framework SDK, you can extend a bot using another bot (a skill). スキルは、他のさまざまなボットで使用されて再利用を促進します。これにより、ユーザー向けに作成したボットを、独自のスキルやサードパーティのスキルを使用して拡張できます。A skill can be consumed by various other bots, facilitating reuse, and in this way, you can create a user-facing bot and extend it by consuming your own or 3rd party skills.

  • "スキル" は、別のボットに対して一連のタスクを実行できるボットです。A skill is a bot that can perform a set of tasks for another bot. 1 つのボットは、スキルでもユーザー向けボットでもあります。A bot can be both a skill and a user-facing bot.
  • "スキル コンシューマー" は、1 つ以上のスキルを呼び出すことができるボットです。A skill consumer is a bot that can call one or more skills. ユーザー向けスキル コンシューマーは、"ルート ボット" とも呼ばれます。A user-facing skill consumer is also called a root bot.
  • "スキル マニフェスト" は、スキルが実行できるアクション、その入力と出力パラメーター、およびスキルのエンドポイントが記述された JSON ファイルです。A skill manifest is a JSON file that describes the actions the skill can perform, its input and output parameters, and the skill's endpoints.

つまり、ユーザーはルート ボットと直接対話し、ルート ボットはその会話ロジックの一部をスキルに委任します。In other words, the user interacts directly with the root bot, and the root bot delegates some of its conversational logic to a skill.

スキル機能は次のように設計されています。The skills feature is designed so that:

  • スキルとコンシューマーは、ボット フレームワークのプロトコルを使用して HTTP で通信します。Skills and consumers communicate over HTTP using the bot framework protocol.
  • スキル コンシューマーは複数のスキルを使用できます。A skill consumer can consume multiple skills.
  • スキル コンシューマーは、スキルの実装に使用された言語とは関係なくスキルを使用できます。A skill consumer can consume a skill regardless of the language used to implement the skill. たとえば C# ボットは、Python を使用して実装されたスキルを使用できます。For example, a C# bot can consume a skill implemented using Python.
  • スキルは、スキル コンシューマーになり、その他のスキルを呼び出すこともできます。A skill can also be a skill consumer and call other skills.
  • スキルはユーザー認証をサポートしますが、ユーザー認証はスキルでローカルに行われ、別のボットに転送することはできません。Skills support user authentication; however, user authentication is local to the skill and cannot be transferred to another bot.
  • スキルは、Bot Framework アダプターとカスタム アダプターの両方と連携できます。Skills can work with both the Bot Framework adapter and custom adapters.

この図は、考えられる順列の一部を示しています。This diagram shows some of the possible permutations.

ブロック図

概念のアーキテクチャConceptual architecture

スキルとスキル コンシューマーは別々のボットであり、ユーザーはそれらを個別に公開します。A skill and skill consumer are separate bots, and you publish them independently. スキルには、完了時に endOfConversation アクティビティを送信するロジックを追加で組み込む必要があります。これにより、スキル コンシューマーはスキルへのアクティビティの転送を停止するタイミングを認識できます。A skill needs to include additional logic to send an endOfConversation activity when it completes, so that the skill consumer knows when to stop forwarding activities to the skill.

ルート ボットは少なくとも 2 つの HTTP エンドポイントを実装します。1 つはユーザーからアクティビティを受信し、もう 1 つはスキルからアクティビティを受信します。A root bot implements at least two HTTP endpoints, one for receiving activities from the user and one for receiving activities from skills. スキル コンシューマーでは、スキルからの HTTP メソッド要求を受信するコードと、スキル ハンドラーを組み合わせる必要があります。The skill consumer needs to pair code that receives the HTTP method request from the skill with a skill handler. スキルを管理する (スキルの呼び出し時やキャンセル時など) ためのロジックを追加する必要があります。It requires added logic for managing a skill, such as when to call or cancel the skill, and so on. コンシューマーには、通常のボット オブジェクトとアダプター オブジェクトに加えて、アクティビティをスキルとやり取りするために使用されるスキル関連オブジェクトがいくつか含まれています。In addition to the usual bot and adapter objects, the consumer includes a few skill-related objects, used to exchange activities with the skill.

次の図は、ユーザーから送信されたアクティビティがルート ボットを経由してスキルに到達し、再びユーザーに戻るまでのフローを示しています。This diagram outlines the flow of activities from the user to the root bot to a skill and back again.

アーキテクチャの図

  1. ルート ボットのアダプターは、ユーザーからアクティビティを受信して、ルート ボットのアクティビティ ハンドラーに転送します。The root bot's adapter receives activities from the user and forwards them to the root bot's activity handler.
  2. ルート ボットは、スキル HTTP クライアントを使用してアクティビティをスキルに送信します。The root bot uses a skill HTTP client to send an activity to the skill. さらに、スキル定義とスキル会話 ID ファクトリからコンシューマー/スキル間の会話の情報を取得します。It gets the consumer-skill conversation information from a skill definition and a skill conversation ID factory. これには、スキルがアクティビティへの応答に使用するサービス URL が含まれます。This includes the service URL that the skill will use to reply to the activity.
  3. スキルのアダプターは、スキル コンシューマーからアクティビティを受信して、スキルのアクティビティ ハンドラーに転送します。The skill's adapter receives activities from the skill consumer and forwards them to the skill's activity handler.
  4. スキルが応答すると、ルート ボットのスキル ハンドラーはアクティビティを受信します。When the skill responds, the root bot's skill handler receives the activity. さらに、スキル会話 ID ファクトリからルート/ユーザー間の会話の情報を取得します。It gets the root-user conversation information from the skill conversation ID factory. その後に、アクティビティをルート ボットのアダプターに転送します。It then forwards the activity to the root bot's adapter.
  5. ルート ボットのアダプターは、内部でプロアクティブ メッセージを生成して、ユーザーとの会話を再開します。The root bot's adapter internally generates a proactive message to resume the conversation with the user.
  6. ルート ボットのアダプターは、スキルからのメッセージをすべてユーザーに送信します。The root bot's adapter sends any messages from the skill to the user.

スキルの管理とスキル トラフィックのルーティングには、次のオブジェクトを利用します。These objects help manage skills and route skill traffic:

  • "Bot Framework スキル" は、スキルのルーティング情報を記述したもので、スキル コンシューマーの構成ファイルから読み取られます。A Bot Framework skill describes routing information for a skill and can be read from the skill consumer's configuration file.
  • "スキル HTTP クライアント" は、スキルにアクティビティを送信します。A skill HTTP client sends activities to a skill.
  • "スキル ハンドラー" は、スキルからアクティビティを受信します。A skill handler receives activities from a skill.
  • "スキル会話 ID ファクトリ" は、ユーザー/ルート間の会話リファレンスとルート/スキル間の会話リファレンスの間で変換を行います。The skill conversation ID factory translates between the user-root conversation reference and the root-skill conversation reference.
  • Bot Connector サービスは、チャネルとボット間認証の両方を提供します。The Bot Connector service provides both channel and bot-to-bot authentication. "認証構成" オブジェクトを使用して要求検証をボット (スキルまたはスキル コンシューマー) に追加することにより、アクセスできるアプリケーションやユーザーを制限できます。Using an authentication configuration object, you can add claims validation to a bot (skill or skill consumer) to limit which applications or users have access.

スキル クライアントとスキル ハンドラーの両オブジェクトは、"会話 ID ファクトリ" を使用して、ルート ボットがユーザーとの対話に使用する会話と、ルート ボットがスキルとの対話に使用する会話の間で変換を行います。The skill client and skill handler objects both use the conversation ID factory to translate between the conversation the root bot uses to interact with the user and the conversation the root bot uses to interact with the skill.

ボット間通信Bot-to-bot communication

設計するボットの種類に関係なく、この設計の一定の側面を理解しておくことが重要です。It's important to understand certain aspects of this design, independent of which bot you're designing.

会話リファレンスConversation references

ユーザー/ルート間の会話とルート/スキル間の会話は異なります。The user-root conversation is different than the root-skill conversation.

"会話 ID ファクトリ" は、スキル コンシューマーとスキルの間のトラフィックの管理を支援します。The conversation ID factory helps to manage traffic between a skill consumer and a skill. このファクトリは、ルート/ユーザー間の会話 ID とルート/スキル間の会話 ID の間で変換を行います。The factory translates between the ID of the conversation the root has with the user and the one it has with the skill. つまり、ルートとスキルの間で使用される会話 ID を生成し、その ID から元のユーザー/ルート間の会話 ID を復旧します。In other words, it generates a conversation ID for use between the root and the skill, and recovers the original user-root conversation ID from the root-skill conversation ID.

サーバー間の調整Cross-server coordination

ルートとスキル ボットは HTTP を介して通信します。The root and skill bots communicate over HTTP. そのため、スキルからアクティビティを受信するルート ボットのインスタンスと、開始アクティビティを送信したインスタンスが同じでない場合があります。つまり、これら 2 つの要求は、異なるサーバーで処理される可能性があります。So, the instance of the root bot that receives an activity from a skill may not be the same instance that sent the initiating activity; in other words, different servers may handle these two requests.

  • アクティビティをスキルに転送する前に、必ずスキル コンシューマーで状態を保存してください。Always save state in the skill consumer before forwarding an activity to a skill. これにより、スキルからトラフィックを受信するインスタンスは、スキルを呼び出す前に、前のインスタンスが中断したところから処理を再開できます。This ensures that the instance that receives traffic from a skill can pick up where the previous instance left off before it called the skill.
  • スキル ハンドラーは、スキルからアクティビティを受信すると、それをスキル コンシューマーに適した形式に変換し、コンシューマーのアダプターに転送します。When the skill handler receives an activity from a skill, it translates it into a form appropriate for the skill consumer, and forwards it to the consumer's adapter.

スキル コンシューマーとスキルの状態Skill consumer and skill state

スキル コンシューマーとスキルは、それぞれの状態を別々に管理します。The skill consumer and skill manage their own state separately. ただしコンシューマーでは、スキルとの通信に使用する会話 ID が作成されます。However, the consumer creates the conversation ID that it uses to communicate with the skill. これがスキルの会話状態に影響することがあります。This can have an effect on conversation state in the skill.

重要

既に説明したように、スキル コンシューマーがユーザー アクティビティをスキルに委任した場合に、そのコンシューマーの別のインスタンスがスキルの応答を受信することがあります。As noted previously, when the skill consumer delegates a user activity to a skill, a different instance of the consumer may receive the skill response. コンシューマーは、アクティビティをスキルに転送する直前に、会話状態を保存する必要があります。The consumer should always save conversation state immediately before forwarding an activity to a skill.

ボット間認証Bot-to-bot authentication

サービス レベルの認証は、Bot Connector サービスで管理されます。Service-level authentication is managed by the Bot Connector service. このフレームワークでは、ベアラー トークンとボット アプリケーション ID を使用して各ボットの ID が検証されます。The framework uses bearer tokens and bot application IDs to verify the identity of each bot.

Bot Framework では、"認証構成" オブジェクトを使用して、受信した要求の認証ヘッダーが検証されます。The Bot Framework uses an authentication configuration object to validate the authentication header on incoming requests.

要求検証Claims validation

認証構成に "要求検証コントロール" を追加することができます。You can add a claims validator to the authentication configuration. 要求は認証ヘッダーの後に評価されます。The claims are evaluated after the authentication header. 要求を拒否するには、検証コードでエラーまたは例外をスローします。Throw an error or exception in your validation code to reject the request.

通常であれば認証される要求を、さまざまな理由で拒否することができます。There are various reasons you might reject an otherwise authenticated request:

  • スキル コンシューマーが、会話を開始した相手である可能性があるスキルからのトラフィックのみを受け入れる必要がある場合。When the skill consumer should accept traffic only from skills that it may have initiated a conversation with.
  • スキルが有料サービスの一部であり、データベースに登録されていないユーザーのアクセスを禁止する必要がある場合。When a skill is part of a paid-for service, and users not in the database should not have access.
  • スキルへのアクセスを特定のスキル コンシューマーに限定する場合。When you want to restrict access to the skill to specific skill consumers.

関連情報Additional information

ユーザーから見ると、自分たちはルート ボットと対話しています。From the user's perspective, they are interacting with the root bot. スキルにとってスキル コンシューマーは、ユーザーとの通信に使用するチャネルです。From the skill's perspective, the skill consumer is the channel over which it communicates with the user.