生成ハンドブック

生成ハンドブックは、大規模言語モデル（LLM）を使用して Dialogflow CX エージェントを作成するための新しい方法を提供します。フロー、ページ、インテント、遷移を定義するのではなく、ハンドブックの形式で自然言語の説明と構造化データを提供します。これにより、エージェントの作成とメンテナンスにかかる時間を大幅に短縮し、ビジネスにおけるまったく新しいタイプの会話エクスペリエンスを実現できます。

特定の会話シナリオで、フローによって提供される明示的なコントロールを引き続き必要とする場合は、ハンドブックとフローの効果を 1 つのハイブリッド エージェントに組み合わせることができます。

制限事項

次の制限が適用されます。

  • 英語のみがサポートされています。
  • us-central1 リージョンと global リージョンのみがサポートされています。
  • ハンドブック エージェントは、デフォルトの開始フローの Default Welcome Intent ルートから通話コンパニオン SMS を送信することはできませんが、標準フローで通話コンパニオン SMS オプションを有効にできます。

ハンドブックの概要

ハンドブックは、ハンドブック エージェントの基本的な構成要素です。通常、エージェントには多数のハンドブックがあり、各ハンドブックは特定のタスクを処理するように定義されています。ハンドブック データは LLM に提供されるため、質問に対する回答とタスクの実行に必要な情報を備えています。各ハンドブックでは、情報の提供、外部サービスへのクエリの送信、従来のフローへの会話処理の委任、またはサブタスクを処理するための別のハンドブックへの延期が可能です。

ハンドブック エージェントを作成する

Dialogflow エージェントを作成するときに、エージェントがハンドブック（ハンドブック エージェント）またはフロー（従来のエージェント）のいずれかとの会話を開始するように選択できます。

ハンドブック エージェントを作成するには:

  1. 手順に沿ってエージェントを作成し、[独自に構築] を選択します。
  2. エージェント タイプとして [生成] を選択します。
  3. [保存] をクリックします。

左側のナビゲーションには 3 つの新しいリソース セレクタがあります。これらのセレクタでは、次のオプションを選択できます。

  • フローリソース
  • 生成リソース
  • 共有リソース

ハンドブック エージェントを作成すると、デフォルトのハンドブックが自動的に作成されます。

ハンドブックのデータ

このセクションでは、ハンドブックを定義するデータについて説明します。

ハンドブック名

[ハンドブックの名前] は、ハンドブックの表示名です。ハンドブックによって、この名前で相互に参照される場合があります。

ハンドブックの目標

ハンドブックの目標は、ハンドブックで達成する必要がある内容の概要です。

例:

Help customers to book flights and hotels.

ハンドブックの手順

ハンドブックのステップによって、ハンドブックの目標を達成するために必要なプロセスが定義されます。

各ステップには、次のいずれかを含む自然言語命令が含まれます。

  • LLM で理解できる基本的な指示。
  • ユーザーを別のハンドブックにルーティングする手順。ハンドブックは ${PLAYBOOK: playbook_name} の形式を使用して参照されます。
  • 特定のツールの使用手順。ツールは、${TOOL: tool_name} の形式で参照されます。
  • ユーザーを Dialogflow フローにルーティングする指示。フローは ${FLOW: flow_name} の形式を使用して参照されます。

各ステップの説明は「-」で始まり、インデントを使用してサブステップを定義できます。

例:

- greet the customer and ask them how you can help.
    - If the customer wants to book flights, route them to ${PLAYBOOK: flight_booking}.
    - If the customer wants to book hotels, route them to  ${PLAYBOOK: hotel_booking}.
    - If the customer wants to know trending attractions, use the ${TOOL: attraction_tool} to show them the list.
- help the customer to pay for their booking by routing them to ${FLOW: make_payment}.

ハンドブックのパラメータ

ハンドブックでは、明示的に定義されたパラメータを使用して、コンテキスト情報を受け入れ、出力できます。パラメータは、ハンドブックを作成すると、[Parameters] タブを使用してハンドブックごとに定義されます。

ハンドブックのパラメータには、タイプ、名前、説明があります。パラメータを定義した後、ハンドブックの例でそれらを使用して、パラメータ値を確実に読み取り、書き込み、使用する方法をハンドブックに示します。詳細については、ハンドブックの入力と出力の例とパラメータを渡すをご覧ください。

ハンドブックの入力パラメータ

入力パラメータを使用すると、ハンドブックでフローや他のハンドブックから渡された値を使用できます。たとえば、ハンドブックがユーザーの希望する名前をパラメータとして受け取り、それを使用してユーザーに個人的に感謝を伝えることができます。また、ハンドブックが注文 ID をパラメータとして受け取り、ツールでそれを使用して注文の詳細を取得することもできます。

ハンドブックの入力パラメータは、ハンドブックごとに定義されます。デフォルトでは、ハンドブックに他の Dialogflow CX パラメータ タイプは表示されません。フローがハンドブックに遷移するとき、ターゲットのハンドブックに同じ名前の入力パラメータがあると、ページ パラメータとセッション パラメータはハンドブックに伝播されます。遷移中にフローからハンドブックに情報を伝えるには、遷移前に存在するセッション パラメータかページ パラメータと同じ名前のハンドブック入力パラメータを定義します。

入力パラメータ値が、ハンドブックのアクションに与える影響を制御するサンプルを作成します。たとえば、入力パラメータがエージェントの参照方法に影響する場合は、パラメータ値を定義する例を作成し、サンプル内の発話アクションで同じ値を使用します。詳細については、パラメータの受け渡しをご覧ください。

ハンドブックの出力パラメータ

出力パラメータを使用すると、ハンドブックは他のフローやハンドブックで使用される情報を出力できます。たとえば、ハンドブックがユーザーから注文番号を収集し、それを出力パラメータを通じて出力する場合や、ハンドブックでツールを使用してフライトを予約し、その確認番号を出力パラメータを通じて出力する場合があります。

ハンドブックが、どのように各出力パラメータの値を決定するかを制御するサンプルを作成します。たとえば、確認番号を表す出力パラメータが、ツールを使用した出力から値を取得する必要がある場合は、ツールを使用した出力がハンドブックの出力パラメータの値と一致するサンプルを作成します。

パラメータを送る

ハンドブックは、フローとは異なり、特定の構文によるパラメータ値の挿入はサポートしていません。その代わりに、ハンドブックでは、手順と数ショットのプロンプトの例を使用して、パラメータ値の使用方法と、パラメータ値を指定するときに値を決定する方法を定めます。

次のハンドブックを使用して、イベント チケットの販売用に設計されたエージェントを検討します。

  1. Ticket sales API というツールを使用して注文を行う Ticket ordering というハンドブック。
    1. このハンドブックは、型が number、名前が event_id の入力パラメータを受け入れます。
    2. Ticket sales API ツールは、event_id を含むリクエストを想定しています。
  2. 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 を持つイベントを選択するユーザーの発話を含めます。
  • ユーザーの選択によって決定されたものと同じ現実的な 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 playbook に渡します。次に、Ticket ordering は、リクエストの本文内の同じ event_id を Ticket sales API に渡します。ハンドブックは、パラメータがどのように使用されるかべきを推測するために、明確なパラメータ値を持つ例に依存しています。

ハンドブックの例

各ハンドブックには 1 つ以上の例を含める必要があります。これらの例は、エンドユーザーとエージェント間のサンプル会話で、エージェントによって実行されるダイアログやアクションを含みます。これらは、LLM の効果的なプロンプトの例です。

コンソールには、アクションを入力するためのインターフェースがあります。例:

エントリ例のスクリーンショット

入力サマリーと出力サマリーの例

ハンドブックでは、入力パラメータと出力パラメータに加えて、他のハンドブックと情報を交換するために、入力サマリーを受け取り、出力サマリーを出力できます。サマリーは、ハンドブック間で抽象的なコンテキスト情報を渡すことに役立ちますが、パラメータは、ハンドブック間で構造化され明確に定義されたフィールドを渡す場合に役立ちます。パラメータは、フローとハンドブックの間でデータを交換する唯一の方法です。

関連する入力サマリーを例に追加して、実行時に入力サマリーに基づいてアクションを調整するようにハンドブックの条件を設定します。会話の例についての関連する正確な詳細を含む出力サマリーを追加して、何の詳細が要約するために重要であるかをハンドブックに示します。

入出力パラメータの例

入力サマリーと出力サマリーに加えて、ハンドブックが入力または出力パラメータを定義する場合、言語モデルがパラメータ値を確実に使用する方法を推測できるように、ハンドブックの例では、これらの入力パラメータまたは出力パラメータもすべて定義する必要があります。

2 つの入力パラメータと 1 つの出力パラメータがあるこのハンドブックで示されているように、ハンドブックの各例では、ハンドブックで定義された各パラメータ値を指定し、使用する必要があります。

入力パラメータと出力パラメータが入力された例のスクリーンショット

ハンドブックの出力状態の例

作成する各例について、例の会話の最終状態を最もよく表すハンドブックの状態を選択します。

  • OK: ハンドブックの目標は達成されました。
  • CANCELLED: 会話の状況により、ハンドブックが目標を達成することなく停止しました。たとえば、この状態は、ユーザが何を手伝ってほしいかについて考えを変えた場合などに適切です。
  • FAILED: エラーまたは処理不能な状況のために、ハンドブックが目標を達成せずに停止しました。たとえば、ツールの呼び出し中にネットワークの問題が原因で目標に到達できなかったときに、この状態が適切な場合があります。
  • ESCALATED: ユーザーが人間のエージェントへのエスカレーションをリクエストしたため、ハンドブックは目標を達成せずに停止しました。

取得戦略

取得戦略では、各例がハンドブックのプロンプトに含まれるかどうかを制御します。

  • DEFAULT: プロンプトがトークンの上限に近い場合は、例を省略できます。
  • STATIC: 例は常に含まれています。
  • NEVER: 例がプロンプトに含まれることはありません。この例は、ハンドブックのパフォーマンスに何の影響も与えません。

ハンドブックを作成する

ハンドブックを作成するには:

  1. 左側のナビゲーションで示されているリソースを選択します。
  2. [ハンドブック] をクリックします。
  3. [新規作成] をクリックします。
  4. 前述のようにデータを提供します。

デフォルトのハンドブック

生成エージェントを作成すると、デフォルトのハンドブックが自動的に作成されます。

デフォルトのハンドブックは会話の出発点となるため、他のハンドブックとは重要な違いがいくつかあります。

  • デフォルトのハンドブックは、先行する会話ターンのサマリーを受け取りません。
  • デフォルトのハンドブックでは、入力パラメータを定義することも受信することもできません。

ハンドブックのバージョン

ハンドブックのバージョンは不変です。つまり、ハンドブックのバージョンを保存できます。

ハンドブックのバージョンを保存するには:

  1. コンソールでハンドブックを読み込みます。
  2. [変更履歴] をクリックします。
  3. [バージョンを作成] をクリックします。
  4. バージョン名を入力して [保存] をクリックします。

変更履歴を表示するには:

  1. コンソールでハンドブックを読み込みます。
  2. [変更履歴] をクリックします。
  3. [変更履歴を表示] をクリックします。
  4. 右側に変更履歴パネルが開きます。各バージョンをクリックすると、その内容が表示されます。

ツール

ハンドブックのステップでは、ステップの実行に使用するツールを参照できます。ハンドブックで使用されるツールごとに、OpenAPI スキーマを提供することでツールの詳細を提供します。

HTTP API 呼び出しまたはデータストア クエリは現在サポートされています。

セッション ID をパスまたはクエリ パラメータとして指定できます。例:

parameters:
  - name: petId
    in: path
    description: ID of pet that needs to be updated
    required: true
    schema:
      $ref: '@dialogflow/sessionId'
  - name: petName
    in: query
    description: ID of pet that needs to be updated
    required: true
    schema:
      $ref: '@dialogflow/sessionId'

HTTP API 呼び出しには、次の制限が適用されます。

  • セッション ID を除き、クエリ パラメータはサポートされていません。
  • リクエストとレスポンスの本文は空または JSON にする必要があります。
  • oneOf などの高度なスキーマ機能はサポートされていません。

次の例では、データストアを参照する方法を示します。

"dataStoreConnections": [
    {
       "dataStoreType": "DATA_STORE_TYPE",
       "dataStore": "projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID"
    }
]

DATA_STORE_TYPE は、次のいずれかの値になります。

  • PUBLIC_WEB: 公開ウェブ コンテンツを含むデータストア。
  • UNSTRUCTURED: 構造化されていない非公開データを含むデータストア。
  • STRUCTURED: 構造化データ（FAQ など）を含むデータストア。

次の例では、HTTP API ツールを参照する方法を示します。

openapi: 3.0.2
info:
  title: Search Attraction Tool
  description: >-
    This API search for attractions for travel purposes
  version: 1.0
servers:
  - url: https://search-attraction.app
paths:
  /search:
    post:
      summary: Search for attractions given a query
      operationId: search
      requestBody:
        description: Query
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: Successfully got results (may be empty)
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: string
components:
  schemas:
    Query:
      required:
        - text
      type: object
      properties:
        text:
          type: string

おすすめの方法

以下のベスト プラクティスは、堅牢なエージェントの構築に役立ちます。

ハンドブックごとに 1 つ以上のサンプル

サンプルは、ハンドブックそれぞれに少なくとも 1 つずつ必要です。十分なサンプルがない場合、ハンドブックによって予期しない動作が発生する可能性があります。エージェントが応答しない、または予期したとおりに動作しない場合は、欠落しているか、明確に定義されていないサンプルが原因である可能性があります。サンプルを改善するか、新しいサンプルを追加してみてください。

指示とサンプルの正確性

明確で説明的な手順を書くことは役立ちますが、エージェントの動作の精度を決めるのはサンプルの質と量です。言い換えると、完全に正確な指示を与えるよりも、徹底的なサンプルを書くことに多くの時間をかけてください。

ツールスキーマの operationId フィールド

ツールのスキーマを定義する場合、operationId 値は重要です。ハンドブックの指示では、この値が参照されます。このフィールドに推奨される命名規則は次のとおりです。

  • 文字、数字、アンダースコアのみ。
  • スキーマに記載されているすべての operationId の中で一意でなければなりません。
  • 提供される機能を反映したわかりやすい名前でなければなりません。

ツールスキーマの検証

ツールスキーマは、検証する必要があります。Swagger Editor を使用して、openAPI 3.0 のスキーマ構文を確認できます。

Bard でスキーマを生成する

Bard では、スキーマを生成できます。たとえば、「Google カレンダー用にサンプルの openAPI 3.0 スキーマを作成できますか」を試してください。

焦点を絞ったハンドブック

非常に大規模で複雑なハンドブックは作成しないでください。各ハンドブックでは、具体的で明確なタスクを達成する必要があります。複雑なハンドブックがある場合は、小さなサブハンドブックに分割することを検討してください。

テストケース

ハンドブックをサポートするために、既存のテストケース機能が強化されました。

必須のテストケースの結果フィールドが追加され、ハンドブックのサンプルの形式でアクションのリストが提供されます。テストケースで、アクションが想定どおりに実行されたことを確認します。

ハンドブックまたはハンドブックのバージョンを表示するときに、ハンドブックのデータの上にある [テストケース] タブをクリックすると、テストケースの結果を確認し、オンデマンドでテストケースを実行できます。

ハンドブックのさまざまなバージョンでテストケースの結果を比較することもできます。テストケースを選択し、[Compare] をクリックします。

エージェントのすべてのテストケースを表示するには、左側のナビゲーションで [テストケース] をクリックします。

会話の履歴

既存の会話履歴機能が強化され、ハンドブックに対応しました。

ツールの実行、ハンドブックの呼び出し、ハンドブック エージェントからのフローの呼び出しに関する情報が追加されました。