應對手冊工具

您可以使用工具，將 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 工作階段 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 工具結構定義

提供結構定義時，您可以點選「Use Gemini」(使用 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 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 用戶端憑證流程支援伺服器對伺服器驗證：
    • 如果生成式 AI 應用程式建構工具是資源擁有者，且不需要使用者授權，則可使用這個流程。
    • 您必須在 Dialogflow 中設定 OAuth 供應商的用戶端 ID、用戶端密鑰和權杖端點。
    • 建議您使用 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 進行 mTLS 時，都會使用這個用戶端憑證。

自訂 CA 憑證

Secret Manager 驗證

如果您使用 OAuth、API 金鑰或不記名權杖，可以使用 Secret Manager 將憑證儲存為密鑰。以下是使用密鑰驗證工具的必要步驟：

  1. 如果還沒有 Secret，請建立 Secret。
  2. 將新 Secret 的 Secret Manager Secret 存取者 (roles/secretmanager.secretAccessor) 角色授予 Dialogflow 服務代理。
  3. 將憑證複製到剪貼簿。
  4. 在 Secret 中新增 Secret 版本。將憑證貼上為 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」(密鑰版本) 輸入方塊。
    • 如果使用不記名權杖，請在「Authentication type」(驗證類型) 中選取「Bearer token」(不記名權杖)，然後點選「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 服務代理 服務帳戶，且位址如下：
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
     將下列 Identity and Access Management 角色授予 Dialogflow 服務代理服務帳戶：
    • Service Directory 專案的 servicedirectory.viewer
    • 網路專案的servicedirectory.pscAuthorizedService
  3. 建立工具時，請提供 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中設定的連線執行動作。每個連接器工具都設定為使用單一連線和一或多個動作。您可以視需求為單一連線建立多個工具，將不同的動作分組，供代理使用。

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

範例應示範代理如何呼叫工具及使用回覆，藉此強化代理對連接器工具的使用。

建立連線

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

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

連接器動作

每個連接器工具都有兩種動作可供代理使用 (詳情請參閱「實體、作業和動作」)：

  1. 實體 CRUD 作業

    每個連線都有對應資料來源物件的「實體」(BigQuery 為資料表；Salesforce 為「訂單」或「案件」等物件)。

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

    • Create：建立具有指定欄位值的實體
    • List：根據篩選條件搜尋實體執行個體
    • 更新：根據篩選條件變更實體欄位值的方法
    • Delete：刪除實體
    • 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. 用戶端程式碼會傳送另一個偵測意圖要求，並提供工具結果做為輸出引數。
上一頁
應對手冊參數
下一頁
應對手冊設定