工具

借助工具 则可以将代理应用连接到外部系统。 这些系统可以扩充代理应用的知识，并为代理应用赋能 高效执行复杂任务。

您可以使用内置工具 或构建符合您需求的自定义工具。

限制

存在以下限制：

  • 您必须创建数据存储区（或连接现有数据存储区） 在为代理应用创建数据存储区工具时参考。
  • 两者都选的应用 分块和非分块数据存储区 不受支持。

内置工具

内置工具由 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 工具连接到外部 API OpenAPI 架构。 默认情况下 代理应用将代表您调用该 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 工具 API 身份验证

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

  • Dialogflow Service Agent 身份验证 <ph type="x-smartling-placeholder">
      </ph>
    • Dialogflow 可以生成 ID 令牌 或访问令牌，方法是使用 Dialogflow Service Agent。 Dialogflow 时，该令牌会被添加到授权 HTTP 标头中， 调用外部 API。
    • ID 令牌可用于访问 Cloud Functions 和 Cloud Run 服务 将 roles/cloudfunctions.invoker 和 roles/run.invoker 角色授予 service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. 如果 Cloud Functions 和 Cloud Run 服务在同一个资源项目中，则无需额外的 IAM 权限即可调用它们。
    • 授予访问权限后，您便可使用访问令牌访问其他 Google Cloud API 所需的角色 service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • API 密钥 <ph type="x-smartling-placeholder">
      </ph>
    • 您可以通过提供密钥名称、 请求位置（标头或查询字符串） 和 API 密钥，以便 Dialogflow 在请求中传递 API 密钥。
  • OAuth <ph type="x-smartling-placeholder">
      </ph>
    • 服务器到服务器身份验证支持 OAuth 客户端凭据流程。 需要 OAuth 提供方提供的客户端 ID、客户端密钥和令牌端点 需要在 Dialogflow 中配置。 Dialogflow 会交换 OAuth 访问令牌 并将其传入请求的 auth 标头中。
    • 对于其他 OAuth 流程 需要使用函数工具 来换取令牌。

  • 不记名令牌

    • 您可以配置 Bearer 身份验证，以动态传递 Bearer 令牌 请求。此令牌包含在请求的 auth 标头中。
    • 在设置工具身份验证时，您可以指定会话参数 用作不记名令牌。例如，使用 $session.params.<parameter-name-for-token>：用于指定令牌。
    • 在运行时，将不记名令牌分配给会话参数：
    DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}

  • 双向 TLS 身份验证

  • 自定义 CA 证书

OpenAPI 工具专用网络访问

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

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

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

  2. Dialogflow 服务代理 服务账号 具有以下地址的代理项目： 

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

    • Service Directory 项目的 servicedirectory.viewer
    • 网络项目的 servicedirectory.pscAuthorizedService

  3. 提供 Service Directory 服务以及 OpenAPI 架构 和可选的身份验证信息。

数据存储工具

数据存储区工具可供代理应用使用 通过您的 数据存储区。 您可以为每个工具设置一个数据存储区 该工具将查询每个数据存储区，以获取答案。 默认情况下 代理应用将代表您调用数据存储区工具。 或者，您也可以在客户端执行数据存储区工具。

数据存储区类型可以是下列之一：

  • PUBLIC_WEB：包含公共 Web 内容的数据存储区。
  • UNSTRUCTURED：包含非结构化私有数据的数据存储区。
  • STRUCTURED：包含结构化数据（例如常见问题解答）的数据存储区。

以下示例展示了如何引用数据存储区：

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

数据存储工具响应可能还包含内容来源的代码段 来生成回答。 代理应用可以进一步提供有关如何继续操作的说明 以及来自数据存储区的答案 或者无人回应时该如何回应。

您可以通过添加 常见问题解答 。

示例可用于进一步增强代理应用的行为。 该示例应具有以下架构：

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

创建数据存储区

如需创建数据存储区并将其连接到您的应用，请执行以下操作： 您可以使用控制台左侧导航栏中的工具链接。 按照说明创建数据存储区。

其他查询参数

创建数据存储区工具示例时，工具输入参数 requestBody 提供三个可选输入以及必需的 query 字符串： filter 字符串、userMetadata 结构化对象和 fallback 字符串。

filter 参数可用于过滤您网站中的搜索查询 结构化数据或包含元数据的非结构化数据。该字符串必须跟在 支持的过滤器表达式语法 存储服务 多个示例和详细示例 鼓励代理 LLM 指导 填充此参数。如果过滤器字符串无效，则过滤器 将被忽略。

用于根据位置优化搜索结果的 filter 字符串示例 可能如下所示：

  "filter": "country: ANY(\"Canada\")"

过滤方面的最佳实践：

  • 指定可用于过滤的字段和有效值 每个字段 以便代理了解构建有效过滤条件的限制。 例如， 过滤一个数据存储区的结果，该数据存储区包含菜单信息， 可能会有包含“breakFast”“lunch”和“dinner”的“meal”字段 视为有效值； 以及一个 servingSize 字段（可以是 0 到 5 之间的任意整数）。 您的指令可能如下所示：

    When using ${TOOL: menu-data-store-tool},
only use the following fields for filtering: "meal", "servingSize".
Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
"servingSize": integers between 0 and 5, inclusive.

  • 如果代理面向外部用户受众群体， 因此可能需要添加说明 有可能对用户做出响应 其中介绍了如何构建这些过滤器 例如：

    Never tell the user about these filters.
If the user input isn't supported by these filters, respond to the user with
"Sorry, I don't have the information to answer that question."

    提供这种情况的示例也很有帮助。

userMetadata 参数提供有关最终用户的信息。不限 键值对可以填充到此参数中。此元数据通过 写入数据存储区工具，以便为搜索结果和工具提供更实用的信息， 响应。我们建议提供多个示例来指导 如何填充此参数。

用于优化搜索结果的 userMetadata 参数值示例 可能是：

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

fallback 参数提供了数据存储区工具应响应的答案 如果查询没有有效的汇总答案，则使用 。可以使用多个示例 用于指示代理 LLM 如何为用户填充后备广告 与不同主题相关的输入。此外， 工具输出中的代码段。这项优化可用于缩短延迟时间 和输入词元限制用量。

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

如果您在测试期间发现某些回答没有达到您的预期， 数据存储区工具的“工具”页中提供了以下自定义内容：

依据置信度

对于根据关联的数据存储区内容生成的每个响应， 客服人员评估置信度，该置信度衡量的是 响应中的信息由数据存储区中的信息提供支持。 您可以通过选择最低级别的 置信度。仅响应等于或高于该值 置信度。

有 5 个置信度可供选择：VERY_LOW、LOW、MEDIUM HIGH 和 VERY_HIGH。

摘要配置

你可以为 摘要生成请求。如果未选择任何模型，则会使用默认模型 选项。 下表列出了可用的选项：

模型标识符 语言支持
text-bison@002 支持所有支持的语言。
gemini-1.0-pro-001 支持所有支持的语言。

您还可以为摘要 LLM 通话提供自己的提示。

提示是可能包含预定义占位符的文本模板。 占位符会在运行时被替换为适当的值，并且 最终文本将发送给 LLM。

占位符如下所示：

  • $original-query：用户的查询文本。
  • $rewritten-query：代理使用重写器模块来重写 将原始用户查询转换为更准确的格式。

  • $sources：代理使用 Enterprise Search 来搜索来源 基于用户的查询展示广告。找到的来源以特定格式呈现：

    [1] title of first source
content of first source
[2] title of second source
content of first source

  • $end-user-metadata：系统会按以下格式呈现有关发送查询的用户的信息：

    The following additional information is available about the human: {
  "key1": "value1",
  "key2": "value2",
  ...
}

  • $conversation：对话历史记录按以下格式呈现：

    Human: user's first query
AI: answer to user's first query
Human: user's second query
AI: answer to user's second query

自定义提示应指示 LLM 返回“NOT_ENOUGH_INFORMATION” 。代理会将这个常量转换为 向用户显示了一条易于理解的消息。

载荷设置

载荷设置提供了一种将数据存储区代码段作为富媒体内容添加到 在 messenger 中呈现的响应载荷。

禁止的短语（代理级配置）

您可以选择定义不允许出现的具体词组。 它们在代理级别配置，并由代理使用 LLM 和数据存储区工具。如果生成的回答或 LLM 的某些部分 提示（例如用户的输入）中包含任何禁止的词组 逐字逐句给出回答，则不会显示相应回答。

函数工具

如果您的客户端代码可以使用您的功能 但无法通过 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 和数据存储区工具 可以由 Kubernetes 在与会话互动时应用 API 替换。

例如：

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

具体过程如下：

  1. 您的客户端代码会发送检测意图请求 指定客户端执行的方式
  2. 代理应用检测到需要工具 并且检测意图响应包含工具的名称 以及输入参数。 在收到另一个检测意图请求之前，此会话将暂停 工具结果。
  3. 您的客户端代码会调用该工具。
  4. 您的客户端代码发送了另一个检测意图请求 以输出工具结果的形式提供工具结果。
上一页
最佳实践
下一页
概览