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

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 に接続できます。 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 は、 ID トークンを Dialogflow サービスエージェントを使用して生成できます。トークンは、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 クライアント認証情報フローは、サーバー間認証でサポートされています。
- Vertex AI Agent Builder コンソールがリソースオーナーであり、エンドユーザーの承認が不要な場合は、このフローを使用できます。
- 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 日以降、エクスポートされたエージェントに未加工の値の署名なしトークンは含まれなくなります。

相互 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 キー] の [シークレットバージョン] をクリックします。シークレットバージョン名を [シークレットバージョン] 入力ボックスに貼り付けます。
- 署名なしトークンを使用する場合は、[**認証タイプ**] として [**署名なしトークン**] を選択し、 [**署名なしトークン**] の [**シークレットバージョン**] をクリックします。シークレットバージョン名を [シークレットバージョン] 入力ボックスに貼り付けます。
[保存] をクリックします。

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

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

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

接続を作成する

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

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

コネクタアクション

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

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

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

各エンティティに対して CRUD オペレーションを実行できます。
- 作成: 指定されたフィールド値を持つエンティティを作成します
- リスト: エンティティインスタンスのフィルタベースの検索
- 更新: エンティティフィールドの値を変更するためのフィルタベースの方法
- 削除: エンティティを削除します
- 取得 : entityId を使用して単一のエンティティを取得します。
注: Get オペレーションを使用できるのは、主キーがあるエンティティから単一のレコードを取得する場合のみです。多くの場合、List オペレーションを filterClause とともに使用してエンティティを取得する方が実用的です。

エンティティの 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
    }
  }
  ...
}