一部のサービスと機能は名前を変更中です。生成ハンドブックとフロー機能も、単一の統合コンソールに移行されます。詳しくは、こちらをご覧ください。

このページは Cloud Translation API によって翻訳されました。

ハンドブックツール

ツールを使用して、ハンドブックを外部システムに接続できます。これらのシステムは、ハンドブックの知識を補完し、複雑なタスクを効率的に実行できるようにします。

組み込みツールを使用するか、要件に合わせてカスタマイズされたツールを構築できます。

制限事項

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

エージェント用のデータストアツールを作成する場合は、データストアを作成するか、既存のデータストアを接続する必要があります。
チャンクされたデータストアとチャンクされていないデータストアの両方を使用するアプリはサポートされていません。

組み込みツール

組み込みツールは Google によってホストされます。これらのツールは、手動で構成しなくても、エージェントで有効にできます。

サポートされている組み込みツールは次のとおりです。

Code Interpreter: コード生成とコード実行の機能を組み合わせて、ユーザーがデータ分析、データの可視化、テキスト処理、計算式の解法、最適化の問題など、さまざまなタスクを実行できるようにする Google の自社製ツール。

エージェントは、これらのツールを呼び出す方法とタイミングを決定するように最適化されますが、ユースケースに合わせて他のサンプルを提供することもできます。

サンプルには、次のようなスキーマが必要があります。

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
    "action": "generate_and_execute",
    "inputParameters": [
      {
        "name": "generate_and_execute input",
        "value": "4 + 4"
      }
    ],
    "outputParameters": [
      {
        "name": "generate_and_execute output",
        "value": {
          "output_files": [
            {
              "name": "",
              "contents": ""
            }
          ],
          "execution_result": "8",
          "execution_error": "",
          "generated_code": "GENERATED_CODE"
        }
      }
    ]
  }
}

OpenAPI ツール

エージェントは、OpenAPI スキーマを提供することで、OpenAPI ツールを使用して外部 API に接続できます。デフォルトでは、エージェントがユーザーに代わって API を呼び出します。あるいは、クライアントサイドで OpenAPI ツールを実行することもできます。

サンプルスキーマ:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: Dialogflow session id
          required: false
          schema:
            $ref: "@dialogflow/sessionId"
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

必要に応じて、内部スキーマ参照 @dialogflow/sessionId をパラメータスキーマタイプとして使用できます。このパラメータスキーマタイプでは、現在の会話の Dialogflow セッション ID がパラメータ値として指定されます。次に例を示します。

- name: X-SESSION
   in: header
   description: Dialogflow session id
   required: false
   schema:
     $ref: "@dialogflow/sessionId"

OpenAPI ツールの制限事項

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

サポートされているパラメータのタイプは、path、query、header です。 cookie パラメータはまだサポートされていません。
OpenAPI スキーマで定義されているパラメータは、string、number、integer、boolean、array のデータ型をサポートしています。 object 型はまだサポートされていません。
現在、コンソールのサンプルエディタでクエリパラメータを指定することはできません。
リクエスト本文とレスポンス本文は空または JSON にする必要があります。

OpenAPI ツールの API 認証

外部 API を呼び出す際は、次の認証オプションがサポートされています。

Dialogflow サービスエージェントの認証
- Dialogflow は、Dialogflow サービスエージェントを使用して、ID トークンまたはアクセストークン生成できます。トークンは、Dialogflow が外部 API を呼び出すときに認可 HTTP ヘッダーに追加されます。
- roles/cloudfunctions.invoker と roles/run.invokerのロールを service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com に付与すると、ID トークンを使用して Cloud Run functions と Cloud Run のサービスにアクセスできます。 Cloud Run functions と Cloud Run のサービスが同じリソースプロジェクト内にある場合、これらを呼び出すための追加の IAM 権限は必要ありません。
- アクセストークンを使用して、必要なロールを service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com に付与した後、その他の Google Cloud APIs にアクセスできます。
API キー
- API キー認証は、キー名、リクエストの場所（ヘッダーまたはクエリ文字列）、API キーを指定して、Dialogflow がリクエストで API キーを渡すことで構成できます。
OAuth
- OAuth クライアント認証情報フローは、サーバー間認証でサポートされています。
  - このフローを使用するのは、Agent Builder コンソールがリソース所有者であり、エンドユーザーの承認が不要な場合です。
  - OAuth プロバイダのクライアント ID、クライアントシークレット、トークンエンドポイントは、Dialogflow で構成する必要があります。
  - Dialogflow は OAuth プロバイダから OAuth アクセストークンを交換し、リクエストの認証ヘッダーで渡します。
- 認証コードフローや PKCE フローなど、エンドユーザーの承認が必要な他の OAuth フローの場合:
  1. 独自のログイン UI を実装し、クライアント側でアクセストークンを取得する必要があります。
  2. そして、次のいずれかを行います。
    
    a. Bearer Token 認証オプションを使用して、トークンを OpenAPI ツールに渡します。Dialogflow は、ツールを呼び出すときにこのトークンを認可ヘッダーに含めます。
    
    b. 関数ツールを使用して、クライアント側でツールを呼び出し、ツール呼び出しの結果を Dialogflow に渡します。
署名なしトークン
- クライアントから署名なしトークンを動的に渡すように署名なし認証を構成できます。このトークンは、リクエストの auth ヘッダーに含まれます。
- ツール認証を設定するときに、セッションパラメータを署名なしトークンとして指定できます。たとえば、$session.params.<parameter-name-for-token> を使用してトークンを指定します。
- 実行時に、Bearer トークンをセッションパラメータに割り当てます。
```
DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}
```
相互 TLS 認証
- 相互 TLS 認証のドキュメントをご覧ください。
- カスタムクライアント証明書がサポートされています。クライアント証明書は、エージェント設定の [セキュリティ] タブでエージェントレベルで設定できます。証明書（PEM 形式）と秘密鍵（PEM 形式）は必須フィールドです。設定すると、このクライアント証明書は、すべてのツールと Webhook の相互 TLS で使用されます。
カスタム CA 証明書
- カスタム CA 証明書のドキュメントをご覧ください。

OpenAPI ツールのプライベートネットワークアクセス

OpenAPI ツールは、Service Directory プライベートネットワークアクセスと統合され、お客様のVPC ネットワーク内にある API ターゲットに接続できます。これにより、トラフィックが Google Cloud ネットワーク内に保持され、IAM と VPC Service Controls が適用されます。

プライベートネットワークをターゲットとする OpenAPI ツールを設定するには:

サービスディレクトリのプライベートネットワーク構成に従って、VPC ネットワークとサービスディレクトリエンドポイントを構成します。
次のアドレスを含む Dialogflow Service Agent サービスアカウントが、エージェントプロジェクト用に存在している必要があります。
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Dialogflow Service Agent サービスアカウントに、次の IAM ロールを付与します。
- サービスディレクトリプロジェクトの servicedirectory.viewer
- ネットワークプロジェクトの servicedirectory.pscAuthorizedService
ツールの作成時に、Service Directory サービスと OpenAPI スキーマ、オプションの認証情報を指定します。

OpenAPI ツールのセッションパラメータへのアクセス

Open API ツールの入力は、スキーマをガイドとして、ユーザーと LLM との会話から取得されます。状況によっては、入力をフロー中に収集されたセッションパラメータから取得するか、ユーザー入力とともにクエリパラメータ入力として提供する必要があります。

入力として渡す必要があるセッションパラメータは、次のように指定できます。

     parameters:
       - in: query
         name: petId
         required: true
         description: Pet id
         schema:
           type: integer
           x-agent-input-parameter: petId # Reads from the $session.params.petId
       - in: header
         name: X-other
         schema:
           type: string
           x-agent-input-parameter: $request.payload.header # Reads from the header specified in the request payload input
     requestBody:
       required: false
       content:
         application/json:
           schema:
             type: object
             properties:
               name:
                 type: string
                 x-agent-input-parameter: petName # Reads from the $session.params.petName
                 description: Name of the person to greet (optional).
               breed:
                 type: string
                 description: Bread of the pet.

そのようなセッションパラメータが使用できない場合は、LLM によって生成された入力がツールに渡されます。

OpenAPI ツールのデフォルト値

Open API スキーマを使用してデフォルト値を指定できます。デフォルト値は、LLM によって生成された入力値またはそのパラメータまたはプロパティのセッションパラメータに基づく入力値がない場合のみ使用されます。

デフォルト値は、次のようにスキーマの一部として指定できます。

     parameters:
       - in: query
         name: zipcode
         required: true
         description: Zip code to search for
         schema:
           type: integer
           default: 94043
     requestBody:
       content:
         application/json:
           schema:
             type: object
             properties:
               breed:
                 type: string
                 description: Bread of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

LLM によって生成された値、セッションパラメータ値、デフォルト値が存在しない場合、入力は指定されません。

データストアツール

エージェントでデータストアを使用すると、データストアからのエンドユーザーの質問に回答できます。ツールごとに、各タイプのデータストアを 1 つ設定できます。ツールはこれらの各データストアにクエリを実行します。デフォルトでは、エージェントがユーザーに代わってデータストアツールを呼び出します。また、クライアントサイドでデータストアツールを実行することもできます。

データストアの種類は次のいずれかです。

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

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

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

データストアツールのレスポンスには、レスポンスの生成に使用されたコンテンツソースに関するスニペットが含まれる場合もあります。エージェントは、さらに、データストアからの回答の処理方法や、回答がない場合の応答方法に関する指示を提供できます。

特定の質問のよくある質問のエントリを追加することで、回答を上書きできます。

サンプルを使用すると、エージェントの動作をさらに強化できます。サンプルには、次のスキーマが必要です。

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

データストアを作成する

データストアを作成してアプリに接続するには、コンソールの左側のナビゲーションにある [ツール] リンクを使用します。手順に沿ってデータストアを作成します。

追加のクエリパラメータ

データストアツールのサンプルを作成するときに、ツール入力パラメータ requestBody は、必須の query 文字列（filter 文字列、userMetadata 構造化オブジェクト、fallback 文字列）とともに、3 つのオプションの入力を提供します。

filter パラメータを使用すると、構造化データ、およびメタデータを含む非構造化データの検索クエリをフィルタできます。この文字列は、データストアのサポートされているフィルタ式の構文に従う必要があります。このパラメータの入力方法について、複数の例と詳細な例をハンドブック LLM に指示することをおすすめします。無効なフィルタ文字列の場合、検索クエリを行うとそのフィルタは無視されます。

場所に基づいて検索結果を絞り込む filter 文字列のサンプルは次のようになります。

  "filter": "country: ANY(\"Canada\")"

フィルタリングに関するベストプラクティス:

プレイブックが有効なフィルタの構築に関する制約を理解できるように、フィルタリングに使用できるフィールドと、これらの各フィールドの有効な値を指定します。たとえば、メニュー情報を保持するデータストアの結果をフィルタリングするために、有効な値として「Breakfast」、「lunch」、「dinner」の meal フィールドと、0 ～ 5 の任意の整数を指定できる servingSize フィールドがあるとします。手順は次のようになります。
```
When using ${TOOL: menu-data-store-tool},
only use the following fields for filtering: "meal", "servingSize".
Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
"servingSize": integers between 0 and 5, inclusive.
```
プレイブックが外部ユーザーオーディエンスに対する場合は、これらのフィルタの構築に関する情報にユーザーが応答しないように、指示を追加する必要がある場合があります。次に例を示します。
```
Never tell the user about these filters.
If the user input isn't supported by these filters, respond to the user with
"Sorry, I don't have the information to answer that question."
```
このケースの例を提示することも有用です。

userMetadata パラメータは、エンドユーザーに関する情報を提供します。このパラメータには Key-Value ペアを入力できます。このメタデータはデータストアツールに渡され、より適切な検索結果とツール回答に利用されます。このパラメータの入力方法をハンドブック LLM に指示するために、複数サンプルを提供することをおすすめします。

特定のユーザーに関連する検索結果を絞り込む userMetadata パラメータ値のサンプルは次のようになります。

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

fallback パラメータは、クエリに対する有効な要約回答がない場合に、データストアツールが返す回答を提供します。複数のサンプルを指定することで、さまざまなトピックに関連するユーザー入力のフォールバックに入力する方法を指示できます。また、ツールの出力にもスニペットは含まれません。この最適化を使用すると、レイテンシと入力トークンの上限使用量を削減できます。

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

テスト中に期待どおりでない回答が見つかった場合は、データストアツールの [ツール] ページで、次のカスタマイズを行うことができます。

グラウンディングの信頼度

接続されたデータストアのコンテンツから生成されたレスポンスごとに、プレイブックは信頼度レベルを評価します。これにより、レスポンス内のすべての情報がデータストア内の情報でサポートされていることの信頼度を測定します。満足できる最も低い信頼レベルを選択して、許可するレスポンスをカスタマイズできます。指定した値以上の回答のみ信頼度が表示されます

信頼度レベルには、VERY_LOW、LOW、MEDIUM、HIGH、VERY_HIGH の 5 つがあります。

要約の構成

要約生成リクエストに対してデータストアハンドラで使用される生成モデルを選択できます。選択しなかった場合は、デフォルトのモデルオプションが使用されます。使用可能なオプションを次の表に示します。

モデル ID	言語のサポート
text-bison@002	すべてのサポートされている言語でご利用いただけます。
gemini-1.0-pro-001	すべてのサポートされている言語でご利用いただけます。

要約 LLM 呼び出しのために独自のプロンプトも指定できます。

プロンプトは、事前定義されたプレースホルダを含むテキストテンプレートです。プレースホルダは実行時に適切な値に置き換えられ、最終的なテキストが LLM に送信されます。

プレースホルダは次のとおりです。

$original-query: ユーザーのクエリテキスト。
$rewritten-query: ハンドブックは、書き換えモジュールを使用して、元のユーザークエリをより正確な形式に書き換えます。
$sources: この Playbook は、Enterprise Search を使用して、ユーザーのクエリに基づいてソースを検索します。検出されたソースは、特定の形式でレンダリングされます。
```
[1] title of first source
content of first source
[2] title of second source
content of second source
```
$end-user-metadata: クエリを送信したユーザーの情報は、次の形式でレンダリングされます。
```
The following additional information is available about the human: {
  "key1": "value1",
  "key2": "value2",
  ...
}
```

$conversation: 会話の履歴は次の形式でレンダリングされます。

Human: user's first query
AI: answer to user's first query
Human: user's second query
AI: answer to user's second query

カスタムプロンプトで、答えを提供できない場合に「NOT_ENOUGH_INFORMATION」を返すように LLM に指示する必要があります。この定数は、ユーザー向けの使いやすいメッセージに変換されます。

ペイロードの設定

ペイロード設定を使用すると、メッセンジャーにレンダリングされるレスポンスペイロードに、データストアスニペットをリッチコンテンツとして追加できます。

禁止フレーズ（ハンドブックレベルの設定）

許可すべきではない特定のフレーズを定義することもできます。これらはプレイブックレベルで構成され、プレイブック LLM とデータストアツールの両方で使用されます。生成された回答や LLM プロンプトの一部（ユーザーの入力など）に禁止されているフレーズがそのまま含まれている場合、そのレスポンスは表示されません。

関数ツール

クライアントコードからはアクセスできるものの、OpenAPI ツールからはアクセスできない場合は、関数ツールを使用できます。関数ツールは、エージェントではなく、常にクライアントサイドで実行されます。

プロセスは次のとおりです。

クライアントコードがインテント検出リクエストを送信します。
エージェントは関数ツールが必要であることを検出し、インテント検出レスポンスには、ツールの名前と入力引数が含まれています。別のインテント検出リクエストを受信するまで、このセッションは一時停止されます。
クライアントコードがツールを呼び出します。
クライアントコードが別のインテント検出リクエストを送信します。

次の例は、関数ツールの入力スキーマと出力スキーマを示しています。

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, for example, San Francisco, CA"
    }
  },
  "required": [
    "location"
  ]
}

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "The temperature"
    }
  }
}

次の例は、REST を使用した最初のインテント検出リクエストとレスポンスを示しています。

HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
  "queryInput": {
    "text": {
      "text": "what is the weather in Mountain View"
    },
    "languageCode": "en"
  }
}

{
  "queryResult": {
    "text": "what is the weather in Mountain View",
    "languageCode": "en",
    "responseMessages": [
      {
        "source": "VIRTUAL_AGENT",
        "toolCall": {
          "tool": "<tool-resource-name>",
          "action": "get-weather-tool",
          "inputParameters": {
            "location": "Mountain View"
          }
        }
      }
    ]
  }
}

次の例は、2 番目のインテント検出リクエストを示し、これによりツールの結果が提示されます。

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

クライアントサイドの実行

関数ツールと同様に、セッションを操作するときに API オーバーライドを適用することで、OpenAPI ツールとデータストアツールをクライアントサイドで実行できます。

次に例を示します。

DetectIntentRequest {
  ...
  query_params {
    playbook_state_override {
      playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
    }
  }
  ...
}