状態ハンドラ

状態ハンドラは単にハンドラとも呼ばれ、エンドユーザーへのレスポンスを作成する、または現在のページを移行することで、会話を制御するために使用されます。会話ターンごとにハンドラが評価され、セッションに影響を与える可能性があります。 ハンドラには、次の 3 種類の一般的なデータがあります。

用語 定義
ハンドラの要件 ハンドラがセッションに影響を与えるためには、満たす必要がある要件が存在します。ハンドラは、要件を満たし、なんらかの方法でセッションに影響を与えると呼び出されたとみなされます
ハンドラのフルフィルメント ハンドラが呼び出されると、オプションのフルフィルメントを使用してエンドユーザーのレスポンスが作成されます。これらのレスポンスは、静的エージェント データで定義するか、Webhook サービスから動的に取得します。
ハンドラの遷移ターゲット ハンドラが呼び出された場合は、オプションの遷移ターゲットを使用して現在のページが変更されます。 次のページは、フローのスタートページ、または現在アクティブなフロー内のページのみです。

ハンドラの要件が異なる次の 2 種類の状態ハンドラがあります。

用語 定義
ルート ルートは、エンドユーザーの入力がセッション ステータスのインテントまたは一部の条件に一致した場合に呼び出されます。インテント要件のあるルートは、インテント ルートとも呼ばれます。条件のみを要件とするルートは条件ルートとも呼ばれます。
イベント ハンドラ イベント ハンドラは、イベントが呼び出された場合に呼び出されます。 予期しないエンドユーザー入力を受け取ったとき、または Webhook エラーが発生したときに、一部の組み込みイベントがトリガーされます。会話の外で何かが発生したときに呼び出すカスタム イベントを定義することもできます。

状態ハンドラの処理は、次の 3 つのステップで行われます。

用語 定義
1. 範囲 セッションに影響を与えるには、ハンドラがスコープ内に存在する必要があります。スコープは、ハンドラがフロー、ページ、またはフォーム パラメータに適用されるかどうか、さらに関連付けられたフローがアクティブであるかどうか、関連付けられたページがアクティブであるかどうか、またはエージェントが現在関連付けられたフォーム パラメータを入力しようとしているかどうかによって決まります。
2. Evaluation スコープ内の各ハンドラは、順に評価されます。ハンドラの要件を満たしている場合は、評価に合格します。
3. 発信 ハンドラはスコープ内にあり評価に合格すると、呼び出されます。関連付けられたフルフィルメントが呼び出され、関連付けられた遷移ターゲットがセッションに適用されます。

範囲

ハンドラが評価されるには、ハンドラがスコープ内に存在する必要があります。ハンドラのスコープは、会話を制御するうえで有用な重要かつ強力なツールです。ハンドラのスコープを制御することで、次の場合について制御できます。

X 項目
インテントが一致した場合
条件をチェックする必要がある場合
特定のイベントを処理できる場合
ページ遷移が発生する場合
静的フルフィルメント レスポンスが提供された場合
動的レスポンスに対して Webhook によるフルフィルメントが呼び出された場合

スコープは、ハンドラがフロー、ページ、またはフォーム パラメータに適用されるかどうか、さらに関連付けられたフローがアクティブであるかどうか、関連付けられたページがアクティブであるかどうか、またはエージェントが現在関連付けられたフォーム パラメータを入力しようとしているかどうかによって決まります。

スコープ ルールの詳細は以下の通りです。

  • アクティブなフローに適用されるルート:
    • 現在のページがフローの開始ページである場合は、スコープに含まれます。
    • 現在のページがフローの開始ページでない場合は、インテントの要件がある場合にのみスコープに含まれます。
  • 現在のページに適用されているルートはスコープに含まれます。
  • アクティブなフローが適用されたイベント ハンドラはスコープに含まれます。
  • 現在のページに適用されているイベント ハンドラはスコープに含まれます。
  • エージェントが現在挿入しようとしているフォーム パラメータに適用されたイベント ハンドラはスコープに含まれます。

ルート

ルートには 2 つの要件があり、いずれかまたは両方を指定する必要があります。両方の要件が指定されている場合、ルートを呼び出すには、両方を満たす必要があります。

用語 定義
インテントの要件 現在の会話ターンのエンドユーザー入力に一致させる必要があるインテント。 ルートにインテントの要件がある場合、そのルートはインテント ルートと呼ばれます。
条件の要件 満たす必要がある条件。ルートに条件の要件がある場合、そのルートは条件ルートと呼ばれます。

ルートは、フロー(フローレベルのルート)とページ(ページレベルのルート)に適用できます。たとえば、次のような状況でルートを使用できます。

X 項目
エンドユーザー入力がインテントと一致すると、その一致によって静的フルフィルメントのレスポンスがトリガーされます。
エンドユーザー入力がインテントと一致すると、その一致によって動的レスポンスの Webhook によるフルフィルメントがトリガーされます。
エンドユーザーの入力によって最終的に必要なフォーム パラメータが指定されると、条件チェックによって別のページにセッション遷移がトリガーされます。
エンドユーザーの入力によって特定のフォーム パラメータが指定されると、条件チェックによって静的フルフィルメント レスポンスがトリガーされます。
条件チェックを true に設定すると、ページが強制的に遷移します。

インテントの伝播

通常、一致するインテントがあるためにルートが呼び出されると、インテントが消費されます。新しいエンドユーザーの入力によって新しいインテントの一致がトリガーされない限り、消費されたインテントが再び一致することはありません。ただし、次のシナリオでは、インテントの一致をあるフローから別のフローに伝播できます。

  • flow F1 のルートには、要件として intent I1 が、遷移ターゲットとして flow F2 が指定されています。
  • Flow F2 には、要件として intent I1 も指定されているルートがあります。

この場合、flow F1 のルートが呼び出されると、intent I1 は単一のエンドユーザー入力に対して 2 回一致し、両方のルートが呼び出されます。

インテントの伝播は、次の場合に便利です。

X 項目
現在のページを別のフローの特定のページに変更する場合(遷移ターゲット フローのルートには特定の遷移ターゲット ページがあります)。
フローのスタートページのエントリ メッセージを作成する場合(遷移ターゲット フローのルートにはフルフィルメントがあります)。

ルートグループ

エージェントを作成する際、多くのページで共通のルートのセットが使用されている場合があります。ルートを再利用可能にするには、ルートグループを定義します。これらのグループはフロー全体のリソースです。

たとえば、フローで「I want to add a topping to my pizza」や「I want to change a drink size」などのエンドユーザー入力を処理するとします。これらの入力は、フローの複数のページのいずれか 1 つがアクティブになったときに処理される必要があります。関連するすべてのページに対してこれらの入力を処理するインテントを使用して 2 つのルートを定義できますが、多くの重複した作業が生じます。代わりに、ルートグループを 1 回定義し、関連するすべてのページでグループへの参照を追加できます。

フローレベルのルート

フローレベルのルートは、フローに適用されるルートです。これらのタイプのハンドラには、次のようなユースケースがあります。

X 項目
フローのスタートページを対象とするスコープにインテントまたは条件の要件を伴うハンドラ。
フロー内のすべてのページを対象とするスコープにインテント要件を伴うハンドラ。

ページレベルのルート

ページレベルのルートはページに適用されるルートです。これらのタイプのハンドラには、次のようなユースケースがあります。

X 項目
特定のページがアクティブな場合に、スコープ内のインテントまたは条件の要件を伴うハンドラ。

イベント ハンドラ

イベント ハンドラを呼び出す際には、次の 1 つの要件があります。

用語 定義
イベントの要件 呼び出す必要があるイベント。イベントは名前で識別されます。予期しないエンドユーザー入力を受信したとき、または Webhook エラーが発生したときに、一部の組み込みイベントが呼び出されます。会話の外で何かが発生したときに呼び出すカスタム イベントを定義することもできます。

イベントハンドラは、フロー(フローレベルのイベント ハンドラ)、ページ(ページレベルのイベント ハンドラ)、パラメータ(パラメータ レベルのイベント ハンドラ)に適用できます。たとえば、次のような場合にイベント ハンドラを使用できます。

X 項目
エンドユーザー入力がどのインテントとも一致しない場合、一致しないイベント ハンドラは特定の静的フルフィルメント レスポンスを提供します。
システムでタイマーが期限切れになった場合、特定の静的フルフィルメント レスポンスを使用してエンドユーザーにリマインダー情報を提供します。

フローレベルのイベント ハンドラ

フローレベルのイベント ハンドラは、フローに適用されるイベント ハンドラです。これらのタイプのハンドラには、次のようなユースケースがあります。

X 項目
フロー スタートページを対象とするスコープ内にイベント要件を伴うハンドラ。
フロー内のすべてのページを対象とするイベント要件を伴うハンドラ。
フロー内のすべてのページによって共有される、予期しないエンドユーザー入力の処理。
Webhook エラーの処理。フロー内のすべてのページで共有されます。
システムによって呼び出されるカスタム イベントの処理。フロー内のすべてのページで共有されます。

各フローには、no-matchno-input組み込みイベントのイベント ハンドラがあります。これらのイベント ハンドラは、フローの作成時に自動的に作成され、削除できません。

ページレベルのイベント ハンドラ

ページレベルのイベント ハンドラは、ページに適用されるイベント ハンドラです。これらのタイプのハンドラには、次のようなユースケースがあります。

X 項目
特定のページがアクティブな場合に、スコープ内のイベント要件を伴うハンドラ。
ページに固有の予期しないエンドユーザー入力の処理。
ページ固有の Webhook エラーの処理。
ページ固有のカスタム イベントの処理。

パラメータ レベルのイベント ハンドラ

パラメータ レベルのイベント ハンドラは、フォーム パラメータに適用されるイベント ハンドラです。リプロンプト ハンドラとも呼ばれます。これらのイベント ハンドラは、フォーム入力時の無効なエンドユーザー入力を処理することを目的としているため、カスタム イベントは使用できません。

これらのタイプのハンドラには、次のようなユースケースがあります。

X 項目
エンドユーザーがフォームのパラメータを入力する際に有効な入力を行わなかった場合。

組み込みイベント

以下のイベントが組み込まれています。一部のイベントは特定のレベルに制限されています。

イベント名
フローレベル ページレベル パラメータレベル 呼び出される時点
sys.no-match-default エンドユーザー入力は、スコープ内のハンドラのインテントと一致せず、フォーム パラメータも満たしません。
sys.no-match-[1-6] これらのいずれかの数値順に並べられたイベントのハンドラを指定すると、sys.no-match-default の代わりに、sys.no-match-1sys.no-match-2、...の順に呼び出されます。
sys.no-input-default エンドユーザー入力を受信しなかったとき。
sys.no-input-[1-6] これらのいずれかの数値順に並べられたイベントのハンドラを指定すると、sys.no-input-default の代わりに、sys.no-input-1sys.no-input-2、...の順に呼び出されます。
sys.invalid-parameter Webhook がパラメータを無効にしたとき。
webhook.error Webhook 呼び出しがエラーを返したとき。
webhook.error.timeout Webhook 呼び出しがタイムアウトしたとき。

カスタム イベント

カスタム イベントとイベント ハンドラを作成できます。イベントは単純に名前で識別されます。組み込みイベントと競合しないように、sys. または webhook. で始まるイベント名は使用しないでください。

API を使用してイベントを呼び出すには、にある detectIntent メソッドの queryInput.event フィールドを参照してください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3beta1
REST セッション リソース
RPC セッション インターフェース

評価順序

ハンドラは、特定の順序で評価されます。次の一般的なルールが適用されます。

  1. スコープ内のハンドラのみが評価されます。
  2. 要件を満たすハンドラのみを呼び出すことができます。
  3. 遷移ターゲットのないハンドラが呼び出された場合、ハンドラのリストの評価は続行されます。このルールにより、複数のフルフィルメントでレスポンス キューに複数のメッセージを追加できます。
  4. 遷移ターゲットを含むハンドラが呼び出されると、ハンドラのリストの評価は終了します。
  5. フルフィルメントを含むハンドラが呼び出され、フルフィルメントが Webhook エラーの場合は次のようになります。
    • イベント ハンドラがイベントのスコープ内にある場合は、イベントを処理し、ハンドラのリストの評価を終了します。
    • イベント ハンドラがイベントのスコープ内にない場合、Webhook は通知なく失敗します。
  6. インテントまたは条件の要件が満たされると、そのインテントまたは条件は消費されないため、同じインテントまたは条件を伴う複数のルートを呼び出すことができます。
  7. イベント要件が満たされると、イベントは消費されるため、最初に検出されたイベント ハンドラのみを呼び出すことができます。

評価には次の 3 つのフェーズがあります。

  1. インテント要件を伴うルートは、次の順序で評価されます。
    1. ページレベル: 指定された順序で、現在のページに適用される個別のルート。
    2. ページレベルのグループ: 指定された順序で、現在のページに適用されるルートグループ
    3. フローレベル: 指定された順序で、アクティブなフローに適用されるルート。
  2. 条件の要件のみを伴うルートは、次の順序で評価されます。
    1. ページレベル: 指定された順序で、現在のページに適用される個別のルート。
  3. イベント ハンドラは次の順序で評価されます。
    1. パラメータ レベル: 指定された順序で、エージェントが現在挿入しようとしている現在のページのフォーム パラメータに適用されるイベント ハンドラ(リプロンプト ハンドラ)。
    2. ページレベル: 指定された順序で、現在のページに適用されるイベント ハンドラ。
    3. フローレベル: 指定された順序で、アクティブなフローに適用されるイベント ハンドラ。

遷移のシンボリック ターゲット

ハンドラの遷移ターゲットを入力する際は、特定のフローやページを入力できますが、遷移のシンボリック ターゲットを入力することもできます。

遷移のシンボリック ターゲット
説明
START_PAGE 同名のアクティブなフローのスタートページに遷移します。
END_FLOW 現在アクティブなフローを終了し、現在のフローに遷移したページに戻ります。
END_SESSION 現在のセッションを消去して、END_SESSION という名前の特別なページに遷移します。次のユーザー入力は、デフォルトの開始フロースタートページでセッションを再起動します。
PREVIOUS_PAGE 前のページに遷移します。
CURRENT_PAGE 現在のページに再び遷移します。エージェントで何かを繰り返す必要がある場合に利用できます。