ツール

ツールを使用して、エージェントを外部システムに接続できます。 これらのシステムは、エージェント アプリの知識を強化し、複雑なタスクを効率的に実行できるようにします。

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

制限事項

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

組み込みツール

組み込みツールは 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 Functions と Cloud Run のサービスにアクセスできます。 Cloud Functions と Cloud Run のサービスが同じリソース プロジェクト内にある場合、これらを呼び出すための追加の IAM 権限は必要ありません。
    • 必要なロールを service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com に付与すると、アクセス トークンを使用して他の Google Cloud APIs にアクセスできます。
  • API キー
    • API キー認証を構成するには、キー名、リクエストの場所（ヘッダーまたはクエリ文字列）、API キーを指定します。これにより、Dialogflow がリクエストで API キーを渡します。
  • OAuth
    • OAuth クライアント認証情報フローは、サーバー間認証でサポートされています。 OAuth プロバイダのクライアント ID、クライアント シークレット、トークン エンドポイントは、Dialogflow で構成する必要があります。 Dialogflow は OAuth アクセス トークンを交換し、それをリクエストの auth ヘッダーで渡します。
    • 他の OAuth フローでは、関数ツールを使用して独自のログイン UI と統合し、トークンを交換する必要があります。
  • 相互 TLS 認証
  • カスタム CA 証明書

データストア ツール

エージェント アプリでデータストアを使用すると、データストアからのエンドユーザーの質問に回答できます。ツールごとに、各タイプのデータストアを 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"
            }
          ]
        }
      }
    ]
  }
}

データストアを作成する

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

追加のクエリ パラメータ

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

filter パラメータを使用すると、構造化データまたは非構造化データの検索クエリをメタデータでフィルタできます。この文字列は、サポートされているフィルタ式の構文に従う必要があります。 このパラメータの入力方法をエージェント LLM に指示するために、複数のサンプルを使用することをおすすめします。無効なフィルタ文字列の場合、検索クエリを実行するとそのフィルタは無視されます。

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

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

userMetadata パラメータは、エンドユーザーに関する情報を提供します。このパラメータには、任意の Key-Value ペアを入力できます。このメタデータはデータストア ツールに渡され、検索結果とツールのレスポンスをより適切に通知します。このパラメータの入力方法をエージェント LLM に指示するために、複数サンプルを提供することをおすすめします。

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

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

テスト中に一部のレスポンスが期待どおりでない場合は、データストア ツールのツールページで次のカスタマイズを行うことができます。

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

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

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

要約の構成

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

モデル ID 言語のサポート
text-bison@001 サポートされているすべての言語でご利用いただけます。
text-bison@002 サポートされているすべての言語でご利用いただけます。
text-bison@001 調整済み（会話型） 現時点では、英語のみがサポートされています。
text-bison@001 調整済み（情報） 現時点では、英語のみがサポートされています。
gemini-pro サポートされているすべての言語でご利用いただけます。

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

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

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

  • $original-query: ユーザーのクエリテキスト。
  • $rewritten-query: エージェントは、リライター モジュールを使用して、元のユーザークエリをより正確な形式に書き換えます。

  • $sources: エージェントは、ユーザーのクエリに基づいて Enterprise Search を使用してソースを検索します。検出されたソースは特定の形式でレンダリングされます。

    [1] title of first source
content of first source
[2] title of second source
content of first source

  • $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 ツールからはアクセスできない場合は、関数ツールを使用できます。 関数ツールは、エージェント アプリではなく、常にクライアントサイドで実行されます。

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

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

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

{
  "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
    }
  }
  ...
}

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

  1. クライアント コードが、クライアント実行を指定するインテント検出リクエストを送信します。
  2. エージェント アプリはツールが必要であることを検出し、インテント検出レスポンスにはツールの名前と入力引数が含まれています。このセッションは、ツール結果とともに別のインテント検出リクエストを受信するまで一時停止されます。
  3. クライアント コードがツールを呼び出します。
  4. クライアント コードは、ツール結果を出力引数として提供する別のインテント検出リクエストを送信します。
前へ
おすすめの方法
次へ
概要