Herramientas de OpenAPI

Un agente puede conectarse a una API externa con una herramienta de OpenAPI proporcionando 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. 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 las herramientas de OpenAPI, es importante que comprendas 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 las aplicaciones de agentes en un proyecto dedicado, independiente 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 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 se le otorguen solo 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 del 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 de IAM adicionales para llamarlos. Si están en proyectos diferentes, se puede usar un token de ID para acceder a Cloud Run Functions y a 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 las solicitudes de herramientas a cualquier API de Google que lo 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 otorgándoles 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 de 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

Para configurar la autenticación de la clave de API, proporciona 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 del secreto 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 Paquete de interacción con los clientes el rol de Usuario con acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor) en el secreto nuevo.
  3. Copia tu credencial en el portapapeles.
  4. Agrega una nueva versión del Secret a tu Secret. Pega tu credencial como el valor del Secret.
    • Omite cualquier carácter de línea nueva 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 Secret para la configuración de la herramienta.

Token del portador

Puedes configurar la autenticación con token del portador para pasar un token del portador almacenado en una variable de contexto de sesión en el encabezado Authorization de la solicitud de la herramienta de OpenAPI. Esta opción es útil cuando el agente necesita pasar un token recopilado del usuario final a otra API.

Especifica la variable de contexto de la sesión con el siguiente formato: $context.variables.VARIABLE_NAME, en el que VARIABLE_NAME es el nombre de la variable que almacena el token del portador.