應對手冊工具

您可以使用工具將劇本連結至外部系統。這些系統可以擴增劇本的知識，並協助劇本有效執行複雜工作。

您可以使用內建工具，或根據需求建構自訂工具。

工具測試

建立工具後，您可以使用工具測試功能驗證工具是否正常運作。查看工具時，按一下工具窗格上方的「測試」按鈕。 系統會開啟模擬器的輸入工具。 提供工具輸入內容，然後按一下「查看輸出內容」，確認工具輸出內容是否正確。

在範例中新增工具時，您也可以使用工具測試功能。

內建工具

內建工具由 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 建立結構定義。您可以提供下列資訊，引導系統生成圖片：

  • 要求網址
  • HTTP 方法 (GET、POST 等)
  • 輸入內容範例
  • 輸出範例
  • 描述工具的文字提示

產生後，您可以視需要編輯，並手動新增其他網址和方法。

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 函式和 Cloud Run 服務。如果 Cloud Run 函式和 Cloud Run 服務位於同一個資源專案，則不需要額外的 IAM 權限即可呼叫。

服務帳戶驗證

服務帳戶可用於驗證對任何支援的 Google API 發出的工具要求。

如果尚未建立服務帳戶，請建立服務帳戶。

由於服務帳戶是主體，因此可以授予角色來存取專案中的資源，就像您對任何其他主體所做的一樣。服務帳戶電子郵件地址會用於產生存取權杖，並在工具要求的 Authorization 標頭中傳送。

設定工具以使用服務帳戶的使用者必須具備下列權限：

  • roles/iam.serviceAccountUser

如要讓 Conversational Agents (Dialogflow CX) 生成權杖，Dialogflow 服務代理程式必須具備下列權限：

  • roles/iam.serviceAccountTokenCreator

服務帳戶也必須具備存取工具代管服務的權限。

API 金鑰

  • 您可以提供金鑰名稱、要求位置 (標頭或查詢字串) 和 API 金鑰，設定 API 金鑰驗證，讓 Dialogflow 在要求中傳遞 API 金鑰。
  • 建議您使用 Secret Manager 提供 API 金鑰。 2025 年 8 月 15 日後，匯出的代理程式將不再包含原始值 API 金鑰。

OAuth

  • 伺服器對伺服器驗證支援 OAuth 用戶端憑證流程：

    • 如果 AI 應用程式控制台是資源擁有者，且不需要使用者授權，即可使用此流程。
    • 您需要在 Dialogflow 中設定 OAuth 供應商的用戶端 ID、用戶端密鑰和權杖端點。
      • 建議您使用 Secret Manager 提供用戶端密鑰。 2025 年 8 月 15 日後，匯出的代理程式將不再包含原始值用戶端密鑰。
    • Dialogflow 會向 OAuth 提供者換取 OAuth 存取權杖，並在要求的驗證標頭中傳遞該權杖。

  • 對於其他需要使用者授權的 OAuth 流程，例如授權碼流程和 PKCE 流程：

    1. 您必須自行導入登入使用者介面，並在用戶端取得存取權杖。

    2. 接著，你可以執行以下任一操作：

      a. 使用不記名權杖驗證選項，將權杖傳遞至 OpenAPI 工具。Dialogflow 呼叫工具時，會在授權標頭中加入這個權杖。

      b. 使用函式工具在用戶端自行叫用工具，並將工具呼叫結果傳遞至 Dialogflow。

不記名憑證

  • 您可以設定 Bearer 驗證，從用戶端動態傳遞 Bearer 權杖。這個權杖會加入要求的驗證標頭。
  • 設定工具驗證時，您可以指定做為 Bearer 權杖的工作階段參數。舉例來說，使用 $session.params.<parameter-name-for-token> 指定權杖。

  • 在執行階段，將 Bearer 權杖指派給工作階段參數：

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

  • 如果您需要設定靜態權杖，而非從工作階段參數擷取權杖，建議您使用 Secret Manager 提供權杖。2025 年 8 月 15 日後，匯出的代理程式將不再包含原始值 Bearer 權杖。

雙向傳輸層安全標準 (TLS) 驗證

  • 請參閱雙向傳輸層安全標準 (TLS) 驗證說明文件。
  • 支援自訂用戶端憑證。您可以在代理程式設定的「安全性」分頁中，設定代理程式層級的用戶端憑證。憑證 (PEM 格式) 和私密金鑰 (PEM 格式) 為必填欄位。設定完成後，所有工具和 Webhook 的雙向 TLS 都會使用這個用戶端憑證。

自訂 CA 憑證

Secret Manager 驗證

如果您使用 OAuth、API 金鑰或 Bearer 權杖，可以透過 Secret Manager 將憑證儲存為密鑰。如要使用密鑰驗證工具，請按照下列步驟操作：

  1. 如果沒有密鑰，請建立密鑰。
  2. 為 Dialogflow 服務代理程式授予新密鑰的 Secret Manager 密鑰存取者 (roles/secretmanager.secretAccessor) 角色。
  3. 將憑證複製到剪貼簿。
  4. 為密鑰新增版本。將憑證貼到密碼值。
    • 結尾請省略任何換行字元。
  5. 複製您剛新增的密鑰版本名稱。名稱格式為 projects/{project_id}/secrets/{secret_id}/versions/{version_id}"。
  6. 開啟工具編輯畫面，然後：
    • 如果使用 OAuth，請選取「OAuth」做為「驗證類型」，然後按一下「用戶端密鑰」下方的「密鑰版本」，並將密鑰版本名稱貼到「密鑰版本」輸入方塊。
    • 如果使用 API 金鑰，請選取「API key」(API 金鑰) 做為「Authentication type」(驗證類型)，然後按一下「API key」(API 金鑰) 下方的「Secret version」(密碼版本)。將密鑰版本名稱貼到「密鑰版本」輸入方塊。
    • 如果使用 Bearer 權杖，請選取「Bearer token」做為「Authentication type」，然後按一下「Bearer token」下方的「Secret version」。將密鑰版本名稱貼到「Secret version」(密鑰版本) 輸入方塊。
  7. 按一下 [儲存]。

OpenAPI 工具私人網路存取權

OpenAPI 工具會整合服務目錄私人網路存取權，因此可以連線至虛擬私有雲網路內的 API 目標。這樣一來，流量就會留在 Google Cloud 網路中，並強制執行 IAM 和 VPC Service Controls。

如要設定以私人網路為目標的 OpenAPI 工具，請按照下列步驟操作：

  1. 請按照「Service Directory 私人網路設定」一文的說明，設定虛擬私有雲網路和 Service Directory 端點。

  2. 代理程式專案必須有下列地址的 Dialogflow 服務代理程式 服務帳戶：

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
     將下列 IAM 角色授予 Dialogflow 服務代理程式服務帳戶：

    • servicedirectory.viewer Service Directory 專案
    • servicedirectory.pscAuthorizedService 網路專案

  3. 建立工具時，請提供 Service Directory 服務，以及 OpenAPI 結構定義和選用的驗證資訊。

存取 OpenAPI 工具工作階段參數

開放式 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. 實體 CRUD 作業

    每個連線都有對應於該資料來源物件的「實體」(如果是 BigQuery，這些是資料表；如果是 Salesforce，這些是物件，例如「Order」或「Case」)。

    您可以對每個實體執行 CRUD 作業：

    • 建立：使用指定欄位值建立實體
    • 清單：根據篩選條件搜尋實體例項
    • 更新：根據篩選器變更實體欄位值的方法
    • 刪除：刪除實體
    • Get 會使用 entityId
      擷取單一實體

    如要進一步瞭解實體 CRUD 作業的詳細資料，請參閱 Connectors 說明文件。

  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"
          }
        }
      }
    ]
  }
}

以下範例顯示第二個偵測意圖要求，其中提供工具結果：

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

用戶端執行作業

與函式工具類似，OpenAPI 和資料儲存庫工具也可以在與工作階段互動時套用 API 覆寫，在用戶端執行。

例如：

DetectIntentRequest {
  ...
  query_params {
    playbook_state_override {
      playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
    }
  }
  ...
}

程序如下：

  1. 用戶端程式碼會傳送偵測意圖要求，並指定用戶端執行作業。
  2. 代理程式偵測到需要工具，且偵測意圖回應包含工具名稱和輸入引數。在收到附有工具結果的另一個偵測意圖要求前，這個工作階段會暫停。
  3. 您的用戶端程式碼會呼叫這項工具。
  4. 用戶端程式碼會傳送另一個偵測意圖要求，將工具結果做為輸出引數提供。
上一頁
應對手冊參數
下一頁
應對手冊設定