ハンドブックでは、明示的に定義されたパラメータを使用して、コンテキスト情報を受け入れ、出力します。パラメータには、ユーザーの選択やアクションの結果など、会話に関する情報が保存されます。これらのパラメータの値は、ハンドブックとフロー間で渡すことができます。
パラメータ宣言
入力（読み取り）パラメータと出力（書き込み）パラメータを定義できます。
パラメータには、名前、説明、および次のいずれかのタイプがあります。
- 文字列
- 数値
- ブール値
- ツール固有のパラメータ タイプ
パラメータがリストかどうかを指定することもできます。
入力（読み取り）パラメータ
ハンドブックごとに、入力パラメータ（読み取りパラメータとも呼ばれます）を定義できます。これにより、ハンドブックで、フローや他のハンドブックから渡された値を使用できます。たとえば、ハンドブックがユーザーの希望する名前をパラメータとして受け取り、それを使用してユーザーに個人的に感謝を伝えることができます。また、ハンドブックが注文 ID をパラメータとして受け取り、ツールを使用して注文の詳細を取得するために使用することもできます。
入力パラメータは、ハンドブックごとに定義されます。デフォルトでは、ハンドブックは他の Dialogflow CX コンソール パラメータ タイプにアクセスできません。フローがハンドブックに遷移するとき、ターゲットのハンドブックに同じ名前の入力パラメータがあると、ページ パラメータとセッション パラメータはハンドブックに伝播されます。遷移中にフローからハンドブックに情報を伝えるには、遷移前に存在するセッション パラメータかページ パラメータと同じ名前のハンドブック入力パラメータを定義します。
入力パラメータ値が、アクションに与える影響を制御するサンプルを作成します。たとえば、入力パラメータがエージェントによるユーザーの参照方法に影響を与える必要がある場合は、パラメータの値を定義するサンプルを作成し、サンプル内の発話アクションで同じ値を使用します。詳しくは、パラメータを渡すをご覧ください。
出力（書き込み、戻り値）パラメータ
ハンドブックごとに、出力パラメータ（書き込みパラメータ、戻りパラメータとも呼ばれます）を定義できます。これにより、ハンドブックは他のフローやハンドブックで使用される情報を出力できます。たとえば、ハンドブックがユーザーから注文番号を収集し、それを出力パラメータを通じて出力する場合や、ハンドブックでツールを使用してフライトを予約し、その確認番号を出力パラメータを通じて出力する場合があります。
ハンドブックが各出力パラメータの値を決定する方法を制御するサンプルを作成します。たとえば、確認番号を表す出力パラメータが、ツールを使用した出力から値を取得する場合は、ツールの出力がハンドブックの出力パラメータの値と一致するサンプルを作成します。
パラメータを送る
ハンドブックは、フローとは異なり、特定の構文によるパラメータ値の挿入はサポートしていません。その代わりに、ハンドブックでは、手順と少数ショット プロンプトの例を使用して、パラメータ値の使用方法と決定方法を定めます。
ルーティン ハンドブックからフロー
ルーティン ハンドブックからフローにパラメータを渡すには:
- ルーティン ハンドブックの書き込みパラメータを定義します。これは、ルーティン ハンドブックの完了時にセッション パラメータになります。
- フローでセッション パラメータを使用します。
- 指示と例にパラメータの使用を含めます。
ルーティン ハンドブックへのフロー
フローからルーティン ハンドブックにパラメータを渡すには:
- フローからセッション パラメータを書き込みます。
- ルーティン ハンドブックの読み取りパラメータを同じ名前で定義します。
- 指示と例にパラメータの使用を含めます。
タスク ハンドブックからフロー
タスク ハンドブックからフローにパラメータを渡すには:
- フロー設定で、同じ名前の入力パラメータを定義します。
- 指示と例にパラメータの使用を含めます。
タスク ハンドブックへのフロー
フローから親タスク ハンドブックにパラメータを渡すには:
- フロー設定で、戻りパラメータを定義します。
- 指示と例にパラメータの使用を含めます。
フローから子タスク ハンドブックにパラメータを渡すには:
- フロー内のセッション パラメータと同じ名前を共有するタスク ハンドブックで、タスク入力パラメータを定義します。
- 指示と例にパラメータの使用を含めます。
ルーティン ハンドブックからタスク ハンドブック
ルーティン ハンドブックからタスク ハンドブックにパラメータを渡すには:
- 同じ名前を使用して、タスク ハンドブックの入力パラメータを定義します。
- 指示と例にパラメータの使用を含めます。
ツールを含むサンプル
次のタスク ハンドブックを使用して、イベント チケットの販売用に設計されたエージェントを検討します。
Ticket sales APIという名前のツールを使用して注文を行うTicket orderingという名前のハンドブック。- このハンドブックは、
event_idという名前のnumber型の入力パラメータを受け入れます。 Ticket sales APIツールは、event_idを含むリクエストを想定しています。
- このハンドブックは、
Event selectionという名前のハンドブック。ユーザーは、イベントを選択し、event_idをパラメータとしてTicket orderingに転送しチケットを購入します。
この例では、Event selection から Ticket ordering、Ticket ordering から Ticket sales API に event_id が確実に渡されるようにするために、いくつかのサンプルが必要です。
Ticket ordering ハンドブックには、次のような複数のサンプルを含める必要があります。
- 入力パラメータ
event_idには、それぞれのサンプルで異なる現実的な値を指定します。 - リクエストの本文に、入力パラメータで指定されたものと同じ現実的な
event_id値を含むツール使用アクションを含めます。
Event selection ハンドブックには、次のような複数のサンプルを含める必要があります。
- 現実的な
event_idを持つイベントが選択されるユーザーの発話を含めます。各サンプルで異なる ID を使用します。 - 選択によって決定されたものと同じ現実的な
event_idをevent_idパラメータに設定するTicket orderingのハンドブック呼び出しを含めます。
サンプルを追加するだけでなく、手順、目標、ツールの詳細に、パラメータをどのように使用すべきかを説明する具体的な指示を追加します。
たとえば、Ticket ordering ハンドブックには次の指示を含めることができます。
- Use parameter event_id to send a buy_tickets request with ${TOOL: Ticket sales API}
説明されているサンプルと指示が存在すると、Event selection ハンドブックがユーザーの選択に基づいて event_id を正しく決定し、それを event_id という名前の入力パラメータとして Ticket ordering ハンドブックに渡します。次に、Ticket ordering は、リクエストの本文内の同じ event_id を Ticket sales API に渡します。ハンドブックは、パラメータがどのように使用されるかを推測するために、明確なパラメータ値を持つ例に依存しています。