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:
- 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.
- 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.
- 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:
- Crea tu secreto si aún no tienes uno.
- 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. - Copia tu credencial en el portapapeles.
- 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.
- 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.