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

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

ハンドブックツール

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

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

ツールのテスト

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

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

組み込みツール

組み込みツールは 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 CX セッション 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 型はサポートされていません。
コンソールのサンプルエディタでクエリパラメータを指定することはできません。
リクエスト本文とレスポンス本文は空にするか、application/json 形式を使用する必要があります。

OpenAPI ツールスキーマの生成

スキーマを指定するときに、[Gemini を使用] をクリックして、生成 AI を使用してスキーマを作成します。

生成をガイドするために、次の詳細を指定します。

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

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

OpenAPI ツールの API 認証

外部 API を呼び出す際は、次の認証オプションを使用できます。

Dialogflow CX サービスエージェントの認証

Dialogflow CX は、Dialogflow CX サービスエージェントを使用して ID トークンを生成できます。トークンは、Dialogflow CX が外部 API を呼び出すときに認可 HTTP ヘッダーに追加されます。

service-agent-project-number@gcp-sa-dialogflow. に roles/cloudfunctions.invoker ロールと roles/run.invoker ロールを付与すると、ID トークンを使用して Cloud Run functions と Cloud Run サービスにアクセスできます。

Cloud Run functions と Cloud Run のサービスが同じリソースプロジェクト内にある場合、これらを呼び出すための追加の Identity and Access Management（IAM）権限は必要ありません。

サービスアカウント認証

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

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

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

roles/iam.serviceAccountUser

Dialogflow CX でトークンを生成できるようにするには、Dialogflow CX サービスエージェントに次の権限を付与します。

roles/iam.serviceAccountTokenCreator

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

API キー認証

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

OAuth

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

Generative AI App Builder がリソースオーナーであり、エンドユーザーの認可が不要な場合は、このフローを使用できます。
Dialogflow CX で、OAuth プロバイダのクライアント ID、クライアントシークレット、トークンエンドポイントを構成する必要があります。
クライアントシークレットは、Secret Manager を使用して指定することをおすすめします。2025 年 8 月 15 日以降、エクスポートされたエージェントには、未加工の値のクライアントシークレットは含まれません。
Dialogflow CX は、OAuth プロバイダから OAuth アクセストークンを交換し、リクエストの認証ヘッダーで渡します。

署名なしトークン

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

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

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

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

相互 TLS 認証

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

カスタム CA 証明書

詳細については、カスタム CA 証明書をご覧ください。

Secret Manager の認証

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

シークレットを使用してツールを認証する手順は次のとおりです。

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

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

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

プライベートネットワークをターゲットとする OpenAPI ツールを設定するには、次のようにします。

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

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

OpenAPI ツールの入力は、スキーマをガイドとして使用して、ユーザーと 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: Breed of the pet.

このようなセッションパラメータがない場合、LLM 生成の入力がツールに渡されます。

OpenAPI ツールのデフォルト値

OpenAPI スキーマを使用してデフォルト値を指定できます。これらのデフォルト値は、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: Breed 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 種類作成できます。詳細については、エンティティ、オペレーション、アクションをご覧ください。

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

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

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

多くのコネクタは 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 ツールとデータストアツールをクライアントサイドで実行できます。