Playbook 工具

借助工具，您可以将 playbook 连接到外部系统。 这些系统可以增强 playbook 的知识，使其能够高效地执行复杂任务。

您可以使用内置工具，也可以根据自己的需求构建自定义工具。

工具测试

创建工具后，您可以使用工具测试功能来验证其是否正常运行。 查看工具时，点击工具窗格上方的测试按钮。 这会打开模拟器中的输入工具。 提供工具输入，然后点击查看输出以验证工具输出是否正确。

您还可以在向示例添加工具时使用工具测试功能。

内置工具

内置工具由 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”，则当前对话的 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 按钮，利用生成式 AI 创建架构。 您可以提供以下信息来引导生成：

  • 请求的网址
  • 一种 HTTP 方法（GET、POST 等）
  • 示例输入
  • 示例输出
  • 描述工具的文本提示

生成后，您可以根据需要进行修改，并手动添加其他网址和方法。

OpenAPI 工具 API 身份验证

调用外部 API 时，支持以下身份验证选项：

Dialogflow Service Agent 身份验证

Dialogflow 可以使用 Dialogflow 服务代理生成 ID 令牌。当 Dialogflow 调用外部 API 时，令牌会添加到授权 HTTP 标头中。

在您向 service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com 授予 roles/cloudfunctions.invoker 和 roles/run.invoker 角色后，可以使用 ID 令牌访问 Cloud Run 函数和 Cloud Run 服务。如果 Cloud Run 函数和 Cloud Run 服务位于同一资源项目中，则无需额外的 IAM 权限即可调用它们。

服务账号身份验证

服务账号可用于向支持它的任何 Google API 验证工具请求的身份。

如果您还没有服务账号，请创建一个。

由于服务账号是主账号，因此您可以为其授予角色，以便其能够访问您项目中的资源，就像为任何其他主账号授予角色一样。服务账号电子邮件地址将用于生成访问令牌，该令牌将通过工具请求的 Authorization 标头发送。

将工具配置为使用服务账号的用户必须具有以下权限：

  • roles/iam.serviceAccountUser

为了让 Conversational Agents (Dialogflow CX) 生成令牌，Dialogflow Service Agent 必须具有以下权限：

  • 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 格式）是必需字段。设置后，此客户端证书将在双向 TLS 期间用于所有工具和 webhook。

自定义 CA 证书

Secret Manager 身份验证

如果您使用 OAuth、API 密钥或不记名令牌，可以使用 Secret Manager 将凭据存储为 secret。以下是使用密钥对工具进行身份验证的必要步骤：

  1. 如果您还没有密钥，请创建密钥。
  2. 向 Dialogflow Service Agent 授予对新 Secret 的 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。
  3. 将您的凭据复制到剪贴板。
  4. 为您的密文添加新的密文版本。将您的凭据粘贴为 Secret 值。
    • 省略末尾的所有换行符。
  5. 复制您刚刚添加的密文版本的名称。名称格式为 projects/{project_id}/secrets/{secret_id}/versions/{version_id}"。
  6. 打开工具修改界面，然后：
    • 如果您使用 OAuth，请选择 OAuth 作为身份验证类型，然后点击客户端密钥下的密钥版本，并将密钥版本名称粘贴到密钥版本输入框中。
    • 如果您使用 API 密钥，请选择 API 密钥作为身份验证类型，然后点击 API 密钥下的密钥版本。将密文版本名称粘贴到密文版本输入框中。
    • 如果您使用不记名令牌，请选择不记名令牌作为身份验证类型，然后点击不记名令牌下的 Secret 版本。将密文版本名称粘贴到密文版本输入框中。
  7. 点击保存。

OpenAPI 工具专用网络访问

OpenAPI 工具与 Service Directory 专用网络访问集成，因此可以连接到 VPC 网络内的 API 目标。这样便可保留在 Google Cloud 网络内部的流量，并强制执行 IAM 和 VPC Service Controls。

如需设置以专用网络为目标的 OpenAPI 工具，请执行以下操作：

  1. 按照 Service Directory 专用网络配置中的说明来配置 VPC 网络和 Service Directory 端点。

  2. 您的代理项目必须存在具有以下地址的 Dialogflow Service Agent 服务账号：

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
     向 Dialogflow 服务代理服务账号授予以下 IAM 角色：

    • Service Directory 项目的 servicedirectory.viewer
    • 网络项目的 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 工具默认值

您可以使用开放式 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 生成的值、会话形参值或默认值，则输入将处于未指定状态。

数据存储区工具

如需了解如何将数据存储区工具与 playbook 搭配使用，请参阅数据存储区工具文档。

连接器工具

代理可以使用连接器工具，通过在集成连接器中配置的连接来执行操作。每个连接器工具都配置有单个连接和一个或多个操作。如果需要，您可以为单个连接创建多个工具，以便将不同的操作分组在一起供代理使用。

连接器工具支持以下连接器类型：

应使用示例来增强代理对连接器工具的使用，方法是演示代理应如何调用工具和使用响应。

创建连接

如需创建连接并将其连接到代理，您可以依次前往工具 > 创建，选择连接器工具类型、所选的连接器类型，然后使用创建连接按钮。这会将您引导至 Integration Connectors 创建页面，其中预先填充了多个字段。

或者，您也可以前往“Integration Connectors”，然后按照说明创建连接。

连接器操作

对于每个连接器工具，有两种类型的操作可供代理使用（如需了解详情，请参阅实体、操作和动作）：

  1. 实体 CRUD 操作

    每个连接都有与相应数据源的对象对应的“实体”（对于 BigQuery，这些是表；对于 Salesforce，这些是对象，例如“订单”或“支持请求”）。

    您可以对每个实体执行 CRUD 操作：

    • 创建：创建具有指定字段值的实体
    • 列表：基于过滤条件的实体实例搜索
    • 更新：一种基于过滤条件的方法，用于更改实体字段值
    • 删除：删除实体
    • 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"
          }
        }
      }
    ]
  }
}

以下示例展示了第二个检测 intent 请求，该请求提供了工具结果：

{
  "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. 您的客户端代码会发送另一个检测意图请求，该请求会将工具结果作为输出实参提供。
上一页
Playbook 参数
下一页
Playbook 设置