Servicios API Rest

Introducción

Este documento menciona como se puede conectar el agente a Servicios externos del cliente, por ejemplo consultar servicios a base de datos, productos, reservar citas, etc.

Campos del Servicio

Formatos de Campos

Los campos que se usan en el bodyTemplate pueden usar formatos especiales para diferentes tipos de datos:

Para fechas:

• {{fecha|format('yyyy-MM-dd')}} → "2024-01-15"

• {{fecha|format('dd/MM/yyyy')}} → "15/01/2024"

• {{fecha|format('yyyy-MM-dd HH:mm:ss')}} → "2024-01-15 14:30:00"

Para números:

• {{precio|number}} → 1500 (número entero)

• {{precio|format('0.00')}} → "1500.00" (dos decimales)

• {{cantidad|number}} → 5

Para texto:

• {{nombre}} → "Juan Pérez"

• {{email}} → "juan@email.com"

Variables dinámicas del usuario:

• Las variables {{variable}} se reemplazan con los datos que el usuario proporciona durante la conversación

• Solo funcionan las variables que están definidas en requiredFields o que el usuario haya proporcionado

👉 Formatos de Campos Completos

Tip: Importante: Las variables {{variable}} solo se reemplazan con datos que el usuario proporciona durante la conversación. Deben estar definidas en requiredFields para que el agente las solicite automáticamente.

Advertencia: Limitación actual: El sistema no incluye variables automáticas como fecha actual o IDs del sistema. Solo se interpolan las variables recopiladas del usuario.

Ejemplo de responseMapping

El responseMapping te permite extraer datos específicos de la respuesta de tu API externa usando JSONPath. Estos valores extraídos luego se pueden usar en el responseMessage y responseConditions.

responseMapping básico:

Ejemplo con API de citas médicas:

Si tu API responde:

Tu responseMapping sería:

Ejemplo con API de e-commerce:

Si tu API responde:

Tu responseMapping sería:

Ejemplo con arrays y datos anidados:

Sintaxis JSONPath

Acceso básico:

• $.campo → Accede a un campo en la raíz

• $.objeto.subcampo → Accede a campos anidados

• $.array[0] → Primer elemento de un array

• $.array[*] → Todos los elementos de un array

Ejemplos de rutas:

• $.response.message → response.message

• $.data.user.email → data.user.email

• $.items[0].price → Precio del primer item

• $.orders[-1].id → ID de la última orden

Tip: Los valores extraídos con responseMapping se convierten automáticamente en variables que puedes usar en responseMessage como {{variable}}. Por ejemplo, si extraes "fecha": "$.data.date", puedes usar {{fecha}} en tu mensaje de respuesta.

Advertencia: Si la ruta JSONPath no existe en la respuesta de la API, esa variable simplemente no se creará. Asegúrate de que las rutas coincidan con la estructura real de tu API.

Campos requeridos

Los campos requeridos son la base fundamental de los servicios. Definen qué información debe recopilar el agente del usuario antes de ejecutar el servicio. Estos campos son las variables que alimentarán el bodyTemplate.

[imagen]

Configuración de campos requeridos

Cada campo requerido se define con las siguientes propiedades:

Tipos de datos soportados

Tipo Array (Objects) - arrayObject

El tipo arrayObject permite definir campos que son arrays de objetos con propiedades configurables. Esto es útil cuando necesitas que el usuario proporcione una lista de elementos con múltiples atributos cada uno.

Ejemplo de caso de uso: Un servicio de portabilidad numérica donde el usuario debe proporcionar una lista de números a portar, cada uno con su tipo de plan, operador y número.

Resultado esperado del LLM:

Tip: Las sub-propiedades del arrayObject solo admiten tipos simples: string, number, integer, boolean. Cada propiedad se define con name y type.

Playground

Aquí puedes experimentar con la configuración de servicios y campos requeridos, para eso existe una pantalla en cada uno de los servicios creados para probar el servicio y poder saber el retorno que se tendra.

[imagen]

Flujo de recopilación

1. El usuario expresa una intención que coincide con el servicio

2. El agente identifica campos faltantes comparando con requiredFields

3. Pregunta los campos uno por uno usando promptHint como guía

4. Valida cada respuesta según el type especificado

5. Una vez completos todos los campos, ejecuta el servicio con bodyTemplate

Tip: Importante: Los nombres de los campos en requiredFields deben coincidir exactamente con las variables usadas en bodyTemplate. Por ejemplo, si defines "name": "email", debes usar {{email}} en el bodyTemplate.

Advertencia: Validación parcial: El sistema actualmente valida automáticamente fechas (date/datetime) y campos vacíos (string). Si el usuario proporciona una fecha inválida, el agente pedirá el dato nuevamente con un mensaje de error. Para otros tipos como number o boolean, la validación es más básica.

Campos Condicionales

Con la plataforma se puede tener condicionales para que el Agente pueda responder de forma diferente en base a la respuesta del servicio.

[imagen]

Ejemplo de responseConditions

Operadores Condicionales

• == (Igual a)

• != (Distinto a)

• < (Menor que)

• > (Mayor que)

• <= (Menor o igual a)

• >= (Mayor o igual a)

Tip: El responseMessage por defecto se usa solo si ninguna de las condiciones en responseConditions se cumple, funcionando como un fallback.

Encadenamiento de Servicios (nextService)

Cada condicion dentro de responseConditions puede incluir un campo nextService que indica el intent de otro servicio que debe ejecutarse automaticamente si esa condicion se cumple. Esto permite encadenar servicios de forma secuencial.

Nota: El nextService es opcional. Si no se define, el flujo termina despues de mostrar el mensaje. Si se define, el agente ejecutara el siguiente servicio usando los datos ya recopilados del usuario.

Consideraciones

• El Agente de IA consultará al usuario, los campos que se encuentran en el campo requiredFields en el formato: campo: campo, el usuario puede llenar un campo o todos, la IA entenderá si faltan o no campos antes del consumir el servicio.

• El responseMapping te ayudará a poder completar los datos del campo requiredMessage, colocando la información en las llaves correspondientes, el json que te trae el servicio deberia de poder colocar los campos dentro del Mensaje.

• Se pueden crear uno o varios servicios dentro de la configuración del Agente, para que pueda consultar sus servicios.