應對手冊工具

您可以使用工具，將 Playbook 連結至外部系統。這些系統可擴充 Playbook 的知識，並讓 Playbook 有能力有效率地執行複雜工作。

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

工具測試

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

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

內建工具

內建工具由 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 工具結構定義

提供結構定義時，請按一下「Use Gemini」(使用 Gemini)，透過生成式 AI 建立結構定義。

提供下列詳細資料，引導生成作業：

  • 要求網址。
  • HTTP 方法，例如 GET 或 POST。
  • 輸入內容範例。
  • 輸出內容範例。
  • 描述工具的文字提示詞。

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

OpenAPI 工具 API 驗證

呼叫外部 API 時，您可以使用下列驗證選項。

Dialogflow CX 服務代理驗證

Dialogflow CX 可使用 Dialogflow CX 服務代理產生 ID 權杖。Dialogflow CX 呼叫外部 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 服務位於同一個資源專案，您就不需要額外的 Identity and Access Management (IAM) 權限，即可呼叫這些函式和服務。

服務帳戶驗證

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

如果您尚未建立服務帳戶，請立即建立。服務帳戶是主體，因此您可以授予角色，讓服務帳戶存取專案中的資源，就像其他主體一樣。您可以使用服務帳戶電子郵件產生存取權杖，並在工具要求的 Authorization 標頭中傳送。

如果您將工具設為使用服務帳戶，則必須具備下列權限：

  • roles/iam.serviceAccountUser

如要讓 Dialogflow CX 生成權杖，請將下列權限授予 Dialogflow CX 服務代理：

  • roles/iam.serviceAccountTokenCreator

服務帳戶也必須具備權限，才能存取託管工具的服務。

API 金鑰驗證

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

OAuth

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

  • 如果生成式 AI 應用程式建構工具是資源擁有者，且您不需要使用者授權，則可使用這個流程。
  • 您必須在 Dialogflow CX 中，設定 OAuth 供應商的用戶端 ID、用戶端密鑰和權杖端點。
  • 建議您使用 Secret Manager 提供用戶端密鑰。2025 年 8 月 15 日後，匯出的代理不含原始值用戶端密鑰。
  • Dialogflow CX 會從 OAuth 供應商交換 OAuth 存取權杖，並在要求的授權標頭中傳遞該權杖。

不記名權杖

  • 您可以設定 Bearer 驗證，動態傳遞用戶端的不記名權杖。這個權杖會包含在要求的授權標頭中。
  • 設定工具驗證時，您可以指定工作階段參數做為不記名權杖。例如，使用 $session.params.<parameter-name-for-token> 指定權杖。

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

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

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

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

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

自訂 CA 憑證

Secret Manager 驗證

如果您使用 OAuth、API 金鑰或不記名權杖，可以使用 Secret Manager 將憑證儲存為密鑰。

請按照下列步驟，使用密鑰驗證工具：

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

OpenAPI 工具私人網路存取權

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

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

  1. 按照「Service Directory 私人網路設定」一文的指示，設定虛擬私有雲網路和 Service Directory 端點。
  2. 請確認代理專案具備 Dialogflow CX 服務代理 服務帳戶，且位址如下：
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
     將下列 IAM 角色授予 Dialogflow CX 服務代理服務帳戶：
    • Service Directory 專案的 servicedirectory.viewer
    • 網路專案的servicedirectory.pscAuthorizedService
  3. 建立工具時，請提供 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 生成的值、工作階段參數值或預設值，輸入內容就會是不指定。

資料儲存庫工具

如要進一步瞭解如何搭配使用資料儲存庫工具和 playbook，請參閱資料儲存庫工具。

連接器工具

連接器工具可讓您設定代理，使用Integration Connectors中設定的連線執行動作。每個連接器工具都設定為使用單一連線和一或多個動作。您可以為單一連線建立多個工具，將不同的動作分組，供代理使用。

連接器工具支援下列連接器類型：

您可以提供範例，示範如何呼叫工具及使用回覆，協助代理有效運用連接器工具。

建立連線

如要建立連線並連結至代理，請依序前往「Tools」 >「Create」，選取「Connector」工具類型和您選擇的連接器類型，然後按一下「Create Connection」。系統會開啟 Integration Connectors 建立頁面，並預填多個欄位。

或者，您也可以前往 Integration Connectors，並按照操作說明建立連線。

連接器動作

您可以為每個連接器工具提供兩種動作，詳情請參閱「實體、作業和動作」。

  1. 實體 CRUD 作業：

    每個連線都有對應資料來源物件的實體 (BigQuery 為資料表，Salesforce 則為 Order 或 Case 等物件)。

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

    • Create：驗證並建立具有指定欄位值的實體。
    • List：根據篩選條件搜尋實體執行個體。
    • 更新：根據篩選條件變更實體欄位值的方法。
    • 刪除：刪除實體。
    • Get：使用 entityId 擷取單一實體。

    如要進一步瞭解實體 CRUD 作業，請參閱連接器說明文件。

  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. 用戶端程式碼會傳送另一個偵測意圖要求，並提供工具結果做為輸出引數。
上一頁
應對手冊參數
下一頁
應對手冊設定