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: session id
          required: true
          schema:
            type: string
          x-ces-session-context: $context.session_id
      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

注入会话上下文变量

您可以将会话上下文中的变量（例如会话 ID）注入到 OpenAPI 请求中。在参数定义中使用 x-ces-session-context 扩展字段。该值应为 context 对象中变量的路径。

例如：

      parameters:
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          # This extension injects the session ID
          x-ces-session-context: $context.session_id

安全注意事项

配置 OpenAPI 工具时，请务必了解权限的处理方式：

工具执行身份：OpenAPI 工具执行的操作使用授予 CX Agent Studio 服务账号的权限，而不是与代理互动的最终用户的直接权限。
传递性访问风险：这意味着，如果 CX Agent Studio 服务账号有权调用 Cloud Run 函数，则该工具可能会调用该服务账号可访问的任何函数，即使最终用户没有直接访问权限也是如此。

为缓解与此行为相关的潜在风险，请执行以下操作：

使用专用项目：我们强烈建议您将代理应用部署在专用项目中，与其他关键资源或敏感功能分开。这种隔离限制了 CX Agent Studio 服务账号可用的权限范围。
实施 VPC Service Controls：利用 VPC Service Controls 为敏感服务定义服务边界。这样一来，您就可以控制对 Cloud Functions 函数等服务的访问权限，并防止 CX Agent Studio 服务账号进行不必要的调用。
遵循最小权限原则：确保仅向 CX Agent Studio 服务账号授予其预期功能所需的最低必要 Identity and Access Management 角色和权限。

API 身份验证

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

服务代理 ID 令牌

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

如果 Cloud Run 函数和 Cloud Run 服务与代理位于同一项目中，则无需额外的 IAM 权限即可调用它们。如果它们位于不同的项目中，您可以在向服务代理地址授予 roles/cloudfunctions.invoker 和 roles/run.invoker 角色后，使用 ID 令牌访问 Cloud Run 函数和 Cloud Run 服务。

服务账号身份验证

服务账号可用于向支持它的任何 Google API 验证工具请求的身份。提供您的服务账号电子邮件地址。

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

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

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

roles/iam.serviceAccountUser

为了让 Dialogflow CX 生成令牌，Customer Engagement Suite 服务代理必须具有以下权限：

roles/iam.serviceAccountTokenCreator

服务账号还必须具有访问托管该工具的服务的权限。

OAuth

提供您所用服务的 OAuth 信息。

如果您要将 OAuth 用于 Google 服务，则需要为该服务配置 OAuth。

API 密钥

您可以提供密钥名称、请求位置（标头或查询字符串）和 API 密钥来配置 API 密钥身份验证，以便 CX Agent Studio 在请求中传递 API 密钥。使用 Secret Manager Secret 版本提供 API 密钥。

Secret Manager 身份验证

您可以使用 Secret Manager 将凭据存储为密文。以下是使用密钥对工具进行身份验证的必要步骤：

如果您还没有密钥，请创建密钥。
为 Customer Engagement Suite Service Agent 授予新 Secret 的 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。
将您的凭据复制到剪贴板。
向您的密文添加新的密文版本。将您的凭据粘贴为 Secret 值。
- 省略末尾的所有换行符。
复制您刚刚添加的密文版本的名称。名称格式为 projects/{project_id}/secrets/{secret_id}/versions/{version_id}。将此 Secret 版本用于工具配置。