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

このページは 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 ツールのスキーマ生成

スキーマを指定する際に、[Gemini を使用] ボタンを使用して、生成 AI でスキーマを作成できます。生成をガイドするために、次の情報を指定できます。

リクエストの URL
HTTP メソッド（GET、POST など）
入力例
出力例
ツールを説明するテキストプロンプト

生成されたら、必要に応じて編集し、追加の URL とメソッドを手動で追加できます。

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 権限は必要ありません。

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

サービスアカウントは、サポートされている Google API へのツールリクエストの認証に使用できます。

まだ作成していない場合は、サービスアカウントを作成します。

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

サービスアカウントを使用するようにツールを構成するユーザーには、次の権限が必要です。

roles/iam.serviceAccountUser

会話エージェント（Dialogflow CX）がトークンを生成するには、Dialogflow サービスエージェントに次の権限が必要です。

roles/iam.serviceAccountTokenCreator

サービスアカウントには、ツールをホストしているサービスにアクセスするための権限も必要です。

API キー

API キー認証は、キー名、リクエストの場所（ヘッダーまたはクエリ文字列）、API キーを指定して、Dialogflow がリクエストで API キーを渡すことで構成できます。
Secret Manager を使用して API キーを指定することをおすすめします。2025 年 8 月 15 日以降、エクスポートされたエージェントに未加工の値の API キーが含まれなくなります。

OAuth

OAuth クライアント認証情報フローは、サーバー間認証でサポートされています。
- このフローは、AI アプリケーションコンソールがリソースオーナーであり、エンドユーザーの承認が不要な場合に使用できます。
- OAuth プロバイダのクライアント ID、クライアントシークレット、トークンエンドポイントは、Dialogflow で構成する必要があります。
  - Secret Manager を使用してクライアントシークレットを指定することをおすすめします。2025 年 8 月 15 日以降、エクスポートされたエージェントには未加工の値のクライアントシークレットが含まれなくなります。
- Dialogflow は、OAuth プロバイダから OAuth アクセストークンを交換し、リクエストの認証ヘッダーでそれを渡します。
Authorization Code Flow や PKCE フローなど、エンドユーザーの承認が必要な他の OAuth フローの場合:
1. 独自のログイン UI を実装し、クライアントサイドでアクセストークンを取得する必要があります。
2. そして、次のいずれかを行います。
  
  a. 署名なしトークン認証オプションを使用して、トークンを OpenAPI ツールに渡します。Dialogflow は、ツールを呼び出すときにこのトークンを認可ヘッダーに含めます。
  
  b. 関数ツールを使用して、クライアントサイドでツールを自分で呼び出し、ツール呼び出しの結果を Dialogflow に渡します。

署名なしトークン

クライアントから署名なしトークンを動的に渡すように署名なし認証を構成できます。このトークンはリクエストの認証ヘッダーに含まれます。
ツール認証を設定するときに、セッションパラメータを署名なしトークンとして指定できます。たとえば、トークンを指定するには $session.params.<parameter-name-for-token> を使用します。

実行時に、署名なしトークンをセッションパラメータに割り当てます。

DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}

セッションパラメータからトークンを取得するのではなく、静的トークンを構成する必要がある場合は、Secret Manager を使用してトークンを指定することをおすすめします。2025 年 8 月 15 日以降、エクスポートされたエージェントに未加工の値の Bearer トークンが含まれなくなります。

相互 TLS 認証

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

カスタム CA 証明書

カスタム CA 証明書のドキュメントをご覧ください。

Secret Manager の認証

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

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

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 生成値、セッションパラメータ値、デフォルト値のいずれも存在しない場合、入力は指定されません。

データストアツール

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

コネクタツール

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

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

サンプルは、エージェントがツールを呼び出してレスポンスを使用する方法を示すことで、コネクタツールのエージェントによる使用を強化するために使用する必要があります。

接続を作成する

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

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

コネクタアクション

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

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

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

各エンティティに対して CRUD オペレーションを実行できます。
- 作成: 指定されたフィールド値でエンティティを作成します。
- リスト: エンティティインスタンスのフィルタベースの検索
- 更新: エンティティフィールドの値を変更するフィルタベースの方法
- 削除: エンティティ
  を削除します
- Get は、entityId
  を使用して単一のエンティティを取得します。
注: Get オペレーションを使用できるのは、主キーがあるエンティティから単一のレコードを取得する場合のみです。通常は、filterClause を指定して List オペレーションを使用し、エンティティを取得する方が実用的です。
エンティティの CRUD オペレーションの詳細については、Connectors のドキュメントをご覧ください。
コネクタ固有のアクション

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

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

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

コネクタツールの操作で使用する特定の入力フィールドまたは出力フィールドを選択することで、エージェントの操作の複雑さを軽減できます。

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

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

認証

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

エージェントビルダーは、これらの認証情報をセッションパラメータに設定する方法を決定する必要があります。ツールの操作が呼び出されると、ツールは認証に使用するデータソースにこれらの認証情報を自動的に渡します。

関数ツール

クライアントコードからはアクセスできるものの、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
    }
  }
  ...
}