工具

您可以使用工具将代理应用连接到外部系统。这些系统可以扩充代理应用的知识，使代理应用能够高效执行复杂的任务。

您可以使用内置工具或构建自定义工具，以满足自己的需求。

限制

存在以下限制：

  • 为代理应用创建数据存储区工具时，必须创建数据存储区（或连接现有数据存储区）。
  • 不支持同时包含分块和非分块数据存储区的应用。

内置工具

内置工具由 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 工具 API 身份验证

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

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

  • 不记名令牌

    • 您可以将不记名身份验证配置为从客户端动态传递不记名令牌。此令牌包含在请求的 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 服务帐号：

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

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

  3. 在创建该工具时，提供 Service Directory Service 以及 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\")"

过滤方面的最佳实践：

  • 指定可用于过滤的字段以及每个字段的有效值，以便代理了解构建有效过滤条件的限制。例如，如需过滤存储菜单信息的数据存储区的结果，可以使用 meal 字段作为有效值：“breakfast”、“lunch”和“dinner”以及 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 参数提供有关最终用户的信息。任何键值对都可以在此参数中填充。这些元数据会传递到数据存储区工具，为搜索结果和工具响应提供更实用的信息。建议提供多个示例，以指导代理 LLM 如何填充此参数。

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

客户端执行

与函数工具一样，通过在与会话交互时应用 API 替换，可以在客户端执行 OpenAPI 和数据存储区工具。

例如：

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

具体过程如下：

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