Herramientas de OpenAPI

Un agente puede conectarse a una API externa con una herramienta de OpenAPI si proporciona el esquema de 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 la 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.

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 Cloud Run Functions, 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 que implementes 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 del 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 Cloud Run Functions 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 a la cuenta de servicio de CX Agent Studio solo se le otorguen los roles y permisos mínimos necesarios de Identity and Access Management 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 Customer Engagement Suite. El token se agrega en el encabezado HTTP de autorización cuando CX Agent Studio llama a una API externa.

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

Autenticación de la cuenta de servicio

Las cuentas de servicio se pueden usar para autenticar solicitudes de herramientas en 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. La dirección de 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 de Customer Engagement Suite 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 la clave de API proporcionando 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 versión secreta de Secret Manager.

Autenticación de Secret Manager

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

  1. Crea tu secreto si aún no tienes uno.
  2. Otorga al agente de servicio de Customer Engagement Suite el rol de Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) en el secreto nuevo.
  3. Copia tu credencial en el portapapeles.
  4. Agrega una versión nueva del secreto a tu secreto. Pega tu credencial 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 secreta para la configuración de la herramienta.