Creación de una extensión personalizada

Si necesita integrar el asistente con un servicio externo que tiene una API REST, puede crear una extensión personalizada importando un documento de OpenAPI.

Después de crear una extensión personalizada, puede conectarla a un asistente como una integración. En las acciones, puede definir pasos que interactúen con el servicio externo llamando a la extensión.

El repo del kit de inicio de la extensión AI assistant builder en GitHub proporciona archivos y consejos de uso avanzado que puedes utilizar para crear rápidamente una extensión que funcione. Cada kit de inicio incluye una definición OpenAPI probada que puede utilizar para crear una extensión que acceda a una API de terceros, junto con un archivo JSON descargable que puede importar para crear un asistente que acceda a la extensión.

Visión general

OpenAPI (antes denominado Swagger) es un estándar abierto para describir y documentar las API REST. Un documento OpenAPI define los recursos y operaciones que admite una API, incluidos los parámetros de solicitud y los datos de respuesta, junto con detalles como las URL del servidor y los métodos de autenticación.

Un documento de OpenAPI describe una API REST en términos de rutas y operaciones. Una ruta identifica un recurso concreto al que se puede acceder mediante la API (por ejemplo, una reserva de hotel o un registro de cliente). Una operación define una acción concreta que puede realizarse sobre ese recurso (como crearlo, recuperarlo, actualizarlo o eliminarlo).

El documento OpenAPI especifica todos los detalles de cada operación, incluido el método HTTP que se utiliza, los parámetros de la solicitud, los datos incluidos en el cuerpo de la solicitud y la estructura del cuerpo de la respuesta.

Para más información sobre la especificación OpenAPI, consulte EspecificaciónOpenAPI.

Cuando se crea una extensión personalizada, se importa un documento OpenAPI que describe la API REST de un servicio externo. El generador de asistentes de AI analiza el documento OpenAPI para identificar las operaciones admitidas por el servicio externo, junto con información sobre los parámetros de entrada y la respuesta para cada operación y los métodos de autenticación admitidos.

Una vez finalizado este proceso, la extensión personalizada estará disponible como una nueva integración que podrá conectar al asistente. El asistente podrá utilizar la extensión para enviar solicitudes al servicio externo en función de las conversaciones con los clientes. Los valores que se incluyen en la respuesta del servicio se asignan a variables de acción, a las que se puede acceder mediante pasos de acción posteriores.

(Para obtener más información sobre cómo conectar una extensión personalizada a un asistente, consulte Añadir una extensión personalizada).

Preparación de la definición de API

Para crear una extensión personalizada, necesita acceso a un documento de OpenAPI que describa la API REST con la que desea realizar la integración. Muchos servicios de terceros publican documentos de OpenAPI que describen sus API, que puede descargar e importar. Para una API que mantenga su empresa, puede utilizar herramientas estándar para crear un documento OpenAPI que la describa.

El sitio web SwaggerHub ofrece un tutorial deOpenAPI 3.0 y herramientas para ayudarle a desarrollar y validar su documento OpenAPI. Puede utilizar el editor Swagger en línea para convertir su documento OpenAPI al formato y versión OpenAPI correctos.

El documento de OpenAPI debe cumplir los siguientes requisitos y restricciones:

El documento debe ser compatible con la especificación OpenAPI 3.0. Si tiene un documento de OpenAPI (o Swagger) que utiliza una versión anterior de la especificación, puede utilizar el editor de Swagger en línea para convertirlo a OpenAPI 3.0.
El documento debe estar en formato JSON (no se da soporte a YAML). Si tiene un documento YAML, puede utilizar el editor de Swagger en línea para convertirlo a JSON.
El cuerpo de la petición en el script JSON debe presentarse como un objeto. Por ejemplo:
```
{
    name: "Bob",
    hobbies: ["sleeping", "eating", "walking"]
}
```
El tamaño del documento no debe ser superior a ' 8 MB.
El content-type debe ser application/json.
Cada operación debe tener un summary claro y conciso. El texto de resumen se utiliza en la interfaz de usuario para describir las operaciones que están disponibles desde una acción, por lo que debe ser corto y significativo para alguien que está construyendo un asistente.
Actualmente no se admiten las URL relativas.
Sólo se admite la autenticación básica, de portador, OAuth 2.0 y de clave de API.
Para la autenticación OAuth 2.0 0, se admiten el código de autorización, las credenciales de cliente, la contraseña y los tipos de concesión personalizados que empiezan por " x- ". Tenga en cuenta que x-es utilizado por el mecanismo de autenticaciónIBM IAM y por watsonx.
Los esquemas que se definen utilizando " anyOf, " oneOf y " allOf " no se admiten actualmente.

Además, cualquier llamada a la API externa debe completarse en 48 segundos.

Creación de la extensión personalizada

Cuando se configura una extensión personalizada con autenticación OAuth, el generador de asistentes AI no admite la especificación o definición de ámbitos OAuth. Sin embargo, el AI assistant builder proporciona soporte para ámbitos OAuth a través de la autenticación más reciente OAuth 2.0 utilizada en webhooks pre-mensaje y post-mensaje.

Para crear una extensión personalizada basada en la definición de API, siga estos pasos:

Vaya a la página Integrations.
Desplácese a la sección Extensiones y pulse Crear extensión personalizada.
Lea la información de Cómo empezar y pulse Siguiente para continuar.
En el paso Información básica, especifique la siguiente información sobre la extensión que va a crear:
- Nombre de extensión: un nombre abreviado y descriptivo para la extensión (por ejemplo, CRM system o Weather service). Este nombre que se muestra en el mosaico de la extensión en la página Integraciones, y en la lista de extensiones disponibles en el editor de acciones.
- Descripción de la extensión: un breve resumen de la extensión y su función. La descripción está disponible en la página Integraciones.
Pulse Siguiente.
En el paso Importar OpenAPI, haga clic o arrastre para añadir el documento OpenAPI que describe la API REST con la que desea integrarse.

Si se produce un error al intentar importar el archivo JSON, asegúrese de que el archivo cumple todos los requisitos enumerados en Preparar la definición de API. Edite el archivo para corregir errores o eliminar características no soportadas. Pulse X para borrar el mensaje de error y vuelva a intentar la importación.

Después de importar el archivo correctamente, haga clic en Siguiente.
En el paso Gestionar extensión, puede revisar el documento OpenAPI importado si es necesario.

En la pestaña Autenticación, verá información sobre los métodos de autenticación definidos en el documento OpenAPI. Tabla. Campos de la pestaña Autenticación ' ofrece detalles sobre los campos de la pestaña Autenticación:

Nombre de campo	Descripción	Valores
Tipo de autenticación	El tipo de autenticación configurado en el script OpenAPI.	- `OAuth 2.0` - `Basic Auth` - `API key auth` - `Bearer auth`
Nombre de usuario	La credencial del nombre de usuario en el script OpenAPI.	Por ejemplo: `user`
Contraseña	La credencial de contraseña configurada en el script OpenAPI.	Por ejemplo: `Password@123`
Servidores	El enlace al servidor que se define en el documento Open API para conectarse. a la extensión de la API.	Por ejemplo: `https://custom-extension-server.xyz`

La tabla Revisar operaciones muestra las operaciones que el asistente puede llamar desde un paso de acción. Una operación es una solicitud mediante el uso de un método concreto de HTTP, como GET o POST, en un recurso concreto.
```
 For each operation, a row in the table shows the following information:
```
- Operación: descripción de la operación, que se deriva de summary (si está presente) o de description en el archivo OpenAPI.
- Método: el método HTTP utilizado para enviar la solicitud de API para la operación.
- Recurso: la vía de acceso al recurso sobre el que actúa la operación.
Para ver más información sobre una operación, haga clic en el icono situado junto a su fila en la tabla. Se muestran los siguientes detalles:
- Parámetros de solicitud: la lista de parámetros de entrada definidos para la operación, junto con el tipo de cada parámetro y si el parámetro es necesario u opcional.
- Propiedades de la respuesta: Las propiedades del cuerpo de la respuesta que se asignan a variables a las que puede acceder el asistente.
Si está satisfecho con la extensión, pulse Finalizar.

Si desea cambiar algo, suprima la extensión, edite el archivo JSON para realizar los cambios y repita el proceso de importación.

La nueva extensión estará ahora disponible como recuadro en la sección Extensiones del catálogo de integraciones y podrá añadirla al asistente.