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

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 セッション 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 ヘッダーに追加されます。

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

サービスアカウント認証

サービスアカウントは、サービスアカウントをサポートする 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 クライアント認証情報フローは、サーバー間認証でサポートされています。
- このフローは、Generative AI App Builder がリソースオーナーであり、エンドユーザーの認可が不要な場合に使用できます。
- OAuth プロバイダのクライアント ID、クライアントシークレット、トークンエンドポイントは、Dialogflow で構成する必要があります。
- クライアントシークレットは、Secret Manager を使用して指定することをおすすめします。2025 年 8 月 15 日以降、エクスポートされたエージェントには、未加工の値のクライアントシークレットが含まれなくなります。
- Dialogflow は、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 Service Agent サービスアカウントが、エージェントプロジェクト用に存在している必要があります。
```
service-agent-project-number@gcp-sa-dialogflow.
```
Dialogflow サービスエージェントのサービスアカウントに、次の Identity and Access Management ロールを付与します。
- サービスディレクトリプロジェクトの 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 の作成に移動し、いくつかのフィールドが事前入力されます。

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

コネクタアクション

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

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

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

各エンティティで CRUD オペレーションを行うことができます。
- Create: 指定されたフィールド値を持つエンティティを作成します。
- List: エンティティインスタンスのフィルタベースの検索
- Update: エンティティフィールドの値を変更するためのフィルタベースの方法
- 削除: エンティティを削除します。
- 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 ツールとデータストアツールをクライアントサイドで実行できます。