ハンドブック ツール

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

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

ツールのテスト

ツールを作成したら、ツールのテスト機能を使用して、ツールが機能することを確認できます。ツールを表示している場合は、ツールペイン上部の [テスト] ボタンをクリックします。これにより、シミュレータで入力するためのツールが開きます。ツール入力を指定し、[出力を表示] をクリックして、ツール出力が正しいことを確認します。

ツールを例に追加するときに、ツールのテスト機能を使用することもできます。

組み込みツール

組み込みツールは 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 に付与した後、他の API にアクセスできます。 Google Cloud

  • サービス アカウントの認証

    • サービス アカウントを使用すると、サポートされているすべての Google API に対するツール リクエストを認証できます。サービス アカウントはプリンシパルであるため、他のプリンシパルと同様に、ロールを付与することでプロジェクト内のリソースにアクセスできます。サービス アカウントのメールアドレスは、ツール リクエストの Authorization ヘッダーで送信されるアクセス トークンの生成に使用されます。

    • この機能を使用するには、次の権限が必要です。

      • サービス アカウント認証を使用するツールを作成または更新するユーザーに roles/iam.serviceAccountUser ロールを付与します。
      • roles/iam.serviceAccountTokenCreator ロールを Dialogflow Service Agent に付与します。

    • 複数のプロジェクトでサービス アカウントを使用する場合は、組織のポリシーでサポートされていることを確認してください。両方の権限は、サービス アカウントを含むプロジェクトで付与する必要があります。

  • API キー

    • API キー認証は、キー名、リクエストの場所（ヘッダーまたはクエリ文字列）、API キーを指定して、Dialogflow がリクエストで API キーを渡すことで構成できます。
    • Secret Manager を使用して API キーを指定することをおすすめします。

  • OAuth

    • OAuth クライアント認証情報フローは、サーバー間認証でサポートされています。

      • このフローは、AI Applications コンソールがリソース所有者であり、エンドユーザーの承認が不要な場合に使用できます。
      • OAuth プロバイダのクライアント ID、クライアント シークレット、トークン エンドポイントは、Dialogflow で構成する必要があります。
        • Secret Manager を使用してクライアント シークレットを指定することをおすすめします。
      • 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>
    }
  }
  ...
}
    • セッション パラメータからトークンを取得するのではなく、静的トークンを構成する必要がある場合は、Secret Manager を使用してトークンを指定することをおすすめします。

  • 相互 TLS 認証

    • 相互 TLS 認証のドキュメントをご覧ください。
    • カスタム クライアント証明書がサポートされています。クライアント証明書は、エージェント設定の [セキュリティ] タブでエージェント レベルで設定できます。証明書（PEM 形式）と秘密鍵（PEM 形式）は必須フィールドです。設定すると、このクライアント証明書は、すべてのツールと Webhook の相互 TLS で使用されます。

  • カスタム CA 証明書

Secret Manager 認証

OAuth、API キー、または Bearer トークンを使用する場合は、Secret Manager を使用して認証情報をシークレットとして保存できます。シークレットを使用してツールを認証する手順は次のとおりです。

  1. シークレットがまだない場合は、シークレットを作成します。
  2. 新しいシークレットに Secret Manager のシークレット アクセサー（roles/secretmanager.secretAccessor）ロールを Dialogflow Service Agent に付与します。
  3. 認証情報をクリップボードにコピーします。
  4. シークレットに新しいシークレット バージョンを追加します。認証情報をシークレット値として貼り付けます。
    • 末尾の改行文字は省略します。
  5. 追加したシークレット バージョンの名前をコピーします。名前の形式は projects/{project_id}/secrets/{secret_id}/versions/{version_id}" です。
  6. ツールの編集画面を開き、次の操作を行います。
    • OAuth を使用する場合は、[Authentication type] として [OAuth] を選択し、[Client secret] の下にある [Secret version] をクリックして、シークレット バージョン名を [Secret version] 入力ボックスに貼り付けます。
    • API キーを使用する場合は、[認証タイプ] として [API キー] を選択し、[API キー] の [シークレット バージョン] をクリックします。シークレット バージョン名を [シークレット バージョン] 入力ボックスに貼り付けます。
    • Bearer トークンを使用する場合は、[Authentication type] で [Bearer token] を選択し、[Bearer token] の [Secret version] をクリックします。シークレット バージョン名を [シークレット バージョン] 入力ボックスに貼り付けます。
  7. [保存] をクリックします。

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

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

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

  1. サービス ディレクトリのプライベート ネットワーク構成に従って、VPC ネットワークとサービス ディレクトリ エンドポイントを構成します。

  2. 次のアドレスを含む Dialogflow Service Agent サービス アカウントが、エージェント プロジェクト用に存在している必要があります。

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Dialogflow Service Agent サービス アカウントに、次の IAM ロールを付与します。

    • サービス ディレクトリ プロジェクトの servicedirectory.viewer
    • ネットワーク プロジェクトの servicedirectory.pscAuthorizedService

  3. ツールの作成時に、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 によって生成された値、セッション パラメータ値、デフォルト値が存在しない場合、入力は指定されません。

データストア ツール

プレイブックでデータストア ツールを使用する方法については、データストア ツールのドキュメントをご覧ください。

コネクタ ツール

エージェントは、Integration Connectors で構成された接続を使用してアクションを実行するために、コネクタ ツールを使用できます。各コネクタ ツールは、1 つの接続と 1 つ以上のアクションで構成されます。必要に応じて、1 つの接続に対して複数のツールを作成して、エージェントが使用できるようにさまざまなアクションをグループ化できます。

コネクタ ツールは、次のコネクタ タイプをサポートしています。

サンプルを使用すると、エージェントがツールを呼び出してレスポンスを使用すべき方法を示すことで、エージェントがコネクタ ツールをより効果的に使用できるようになります。

接続を作成する

接続を作成してエージェントに接続するには、[ツール] > [作成] に移動し、[コネクタ] ツールタイプ、選択したコネクタ タイプを選択し、[接続を作成] ボタンを使用します。これで、いくつかのフィールドが事前入力された Integration Connectors の作成ページに移動します。

または、Integration Connectors に移動し、接続を作成する手順に沿って操作します。

コネクタのアクション

コネクタ ツールごとに、エージェントが利用できるアクションが 2 種類あります（詳細については、エンティティ、オペレーション、アクションをご覧ください）。

  1. エンティティの CRUD オペレーション

    それぞれの接続には、そのデータソースのオブジェクトに対応する「エンティティ」があります（BigQuery の場合はテーブル、Salesforce の場合は「Order」や「Case」などのオブジェクト）。

    各エンティティに対して CRUD 操作を実行できます。

    • 作成: 指定されたフィールド値を持つエンティティを作成します
    • リスト: エンティティ インスタンスのフィルタベースの検索
    • 更新: エンティティ フィールドの値を変更するフィルタベースの方法
    • 削除: エンティティを削除します
    • Get は、entityId
      を使用して単一のエンティティを取得します。

    エンティティの CRUD オペレーションの詳細については、コネクタのドキュメントをご覧ください。

  2. コネクタ固有のアクション

    多くのコネクタは ExecuteCustomQuery アクションをサポートしています。このアクションを使用すると、データソースに対して SQL クエリを実行できます。この場合、各データソース エンティティをテーブルとして参照できます。サポートされているコネクタのリストを確認する。

    追加のアクションはコネクタのタイプによって異なります。たとえば、BigQuery コネクタのアクションや Salesforce コネクタのアクションをご覧ください。

CRUD オペレーションの入出力フィールドの構成

コネクタ ツール アクションで使用する特定の入力フィールドまたは出力フィールドを選択することで、エージェントが行うこれらのアクションの複雑さを制限できます。

たとえば、フィールドのサブセットを持つエンティティのみを作成する場合、アクションでこのフィールドセットを構成すると、エージェントのアクションが簡素化されます。

出力フィールドのセットを指定すると、ツールのレスポンス サイズが削減されます（トークンの上限が懸念される場合に役立ちます）。また、関連するフィールドのみを公開することで、エージェントによる出力の処理が簡素化されます。

認証

使用している接続が認証のオーバーライドを許可するように構成されている場合は、指定されたセッション パラメータから認証情報を渡すようにツールを構成できます。

エージェント ビルダーは、これらの認証情報をセッション パラメータに入力する方法について責任を負います。ツールのアクションが呼び出されると、ツールは認証に使用するデータソースに認証情報を自動的に渡します。

関数ツール

クライアント コードからはアクセスできるものの、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. クライアント コードが別のインテント検出リクエストを送信します。