Herramientas de OpenAPI

Un agente puede conectarse a una API externa con una herramienta de OpenAPI si proporciona el OpenAPI. El agente llamará a la API en tu nombre.

Limitaciones:

  • Cada herramienta de OpenAPI solo puede tener una operación o función.

Esquema de ejemplo:

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

Cómo insertar variables de contexto de sesión

Puedes insertar variables del contexto de sesión, como el ID de sesión, en tus solicitudes de OpenAPI. Usa el campo de extensión x-ces-session-context dentro de la definición del parámetro. El valor debe ser la ruta de acceso a la variable dentro del objeto context. Para obtener más información, consulta Variables de contexto de sesión.

Por ejemplo:

      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

Consideraciones de seguridad

Cuando configures herramientas de OpenAPI, es importante comprender cómo se manejan los permisos:

  • Identidad de ejecución de la herramienta: Las acciones que realiza la herramienta de OpenAPI se ejecutan con los permisos otorgados a la cuenta de servicio de CX Agent Studio, no con los permisos directos del usuario final que interactúa con el agente.
  • Riesgo de acceso transitivo: Esto significa que, si la cuenta de servicio de CX Agent Studio tiene permisos para invocar funciones de Cloud Run, la herramienta puede llamar a cualquier función a la que pueda acceder esa cuenta de servicio, incluso si el usuario final no tiene acceso directo.

Para mitigar los riesgos potenciales asociados con este comportamiento, haz lo siguiente:

  1. Usa proyectos dedicados: Te recomendamos implementar aplicaciones de agentes en un proyecto dedicado, separado de otros recursos críticos o funciones sensibles. Este aislamiento limita el alcance de los permisos disponibles para la cuenta de servicio de CX Agent Studio.
  2. Implementa los Controles del servicio de VPC: Utiliza los Controles del servicio de VPC para definir un perímetro de servicio alrededor de tus servicios sensibles. Esto te permite controlar el acceso a servicios como las funciones de Cloud Run y evitar llamadas no deseadas desde la cuenta de servicio de CX Agent Studio.
  3. Sigue el principio de privilegio mínimo: Asegúrate de que la cuenta de servicio de CX Agent Studio solo tenga los roles y permisos de Identity and Access Management mínimos necesarios para su funcionalidad prevista.

Autenticación de API

Se admiten las siguientes opciones de autenticación cuando se llama a una API externa:

Token de ID del agente de servicio

CX Agent Studio puede generar un token de ID con el agente de servicio de Paquete de interacción con los clientes (con el formato: service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com). El token se agrega en el encabezado HTTP de autorización cuando CX Agent Studio llama a una API externa.

Si las funciones de Cloud Run y los servicios de Cloud Run están en el mismo proyecto que el agente, no necesitas permisos adicionales de IAM para llamarlos. Si están en proyectos diferentes, se puede usar un token de ID para acceder a las funciones de Cloud Run y a los servicios de Cloud Run después de otorgar los roles/cloudfunctions.invoker y roles/run.invoker roles a la dirección del agente de servicio.

Autenticación de cuenta de servicio

Las cuentas de servicio se pueden usar para autenticar solicitudes de herramientas a cualquier API de Google que las admita. Proporciona la dirección de correo electrónico de tu cuenta de servicio.

Si aún no lo hiciste, crea una cuenta de servicio.

Debido a que las cuentas de servicio son principales, pueden acceder a los recursos de tu proyecto si les otorgas un rol, al igual que lo harías con cualquier otra principal. El correo electrónico de la cuenta de servicio se usará para generar un token de acceso que se enviará en el encabezado Authorization de la solicitud de la herramienta.

El usuario que configura la herramienta para usar cuentas de servicio debe tener los siguientes permisos:

  • roles/iam.serviceAccountUser

Para que Dialogflow CX genere tokens, el agente de servicio del Paquete de interacción con los clientes debe tener los siguientes permisos:

  • roles/iam.serviceAccountTokenCreator

La cuenta de servicio también debe tener permisos para acceder al servicio que aloja la herramienta.

OAuth

Proporciona la información de OAuth para el servicio que usas.

Si usas OAuth para un servicio de Google, debes configurar OAuth para el servicio.

Clave de API

Puedes configurar la autenticación de clave de API si proporcionas el nombre de la clave, la ubicación de la solicitud (encabezado o cadena de consulta) y la clave de API para que CX Agent Studio pase la clave de API en la solicitud. Proporciona tu clave de API con la Secret Manager versión del secreto.

Autenticación de Secret Manager

Puedes almacenar credenciales como secrets con Secret Manager. Estos son los pasos necesarios para autenticar tu herramienta con secrets:

  1. Crea tu secreto si aún no tienes uno.
  2. Otorga a Customer Engagement Suite Service Agent el rol Administrador y descriptor de acceso a secretos (roles/secretmanager.secretAccessor) en el secreto nuevo.
  3. Copia tus credenciales en el portapapeles.
  4. Agrega una versión nueva del secreto a tu secreto. Pega tus credenciales como el valor del secreto.
    • Omite cualquier carácter de salto de línea al final.
  5. Copia el nombre de la versión del secreto que acabas de agregar. El formato del nombre es projects/{project_id}/secrets/{secret_id}/versions/{version_id}. Usa esta versión del secreto para la configuración de la herramienta.