Planes Standard & Pro
Descripción general
Las herramientas personalizadas permiten que tu agente de IA llame a tus propios puntos de conexión de API durante una conversación para obtener datos en tiempo real y específicos de cada solicitud: estado del pedido, seguimiento de envíos, stock de una SKU concreta, detalles de la cuenta y mucho más.
Asyntai te ofrece tres formas de proporcionar a la IA datos en tiempo real o específicos del cliente. Las herramientas personalizadas son la opción adecuada cuando el valor que la IA necesita solo aparece durante la conversación:
- Flujo de datos en tiempo real: carga un conjunto de datos fijo (por ejemplo, todo tu catálogo de productos) en cada conversación. Ideal para datos compartidos que son los mismos para todos los visitantes.
- Contexto del usuario: tu sitio envía datos que ya conoce sobre el visitante actual (por ejemplo, el nombre, el plan o los pedidos recientes de un cliente con sesión iniciada) al comienzo del chat. Ideal cuando el visitante está identificado de antemano.
- Herramientas personalizadas: la IA llama a tu punto de conexión bajo demanda, con valores que extrae del chat. Ideal cuando el valor no se conoce hasta que el cliente lo escribe, como un número de pedido de un visitante anónimo.
Por ejemplo, cuando un cliente pregunta «¿Dónde está mi pedido #10294?», la IA extrae el número de pedido, llama a tu punto de conexión con él y responde usando la respuesta verificada. El contexto del usuario no puede cubrir este caso por sí solo, porque el número de pedido no se conoce hasta la mitad de la conversación: ahí es exactamente donde encajan las herramientas personalizadas. (Muchas tiendas usan el contexto del usuario para los visitantes con sesión iniciada y una herramienta personalizada para consultas puntuales.)
La IA decide cuándo llamar a una herramienta según la descripción que escribas. Tú decides qué hace la herramienta apuntándola a tu punto de conexión. Asyntai realiza la llamada del lado del servidor: no escribes código ni alojas ningún middleware.
Cómo funciona
- Defines una herramienta: un nombre, una descripción, la URL de tu punto de conexión y los parámetros que la IA debe enviar.
- La IA la llama cuando es pertinente: cuando la conversación coincide con tu descripción, la IA llama a la herramienta con valores que extrae del mensaje del cliente.
- Asyntai llama a tu punto de conexión: nuestro servidor realiza la solicitud HTTP a tu URL y devuelve la respuesta a la IA.
- La IA responde: usando los datos verificados que devolvió tu punto de conexión.
No se requiere código: solo necesitas un punto de conexión que ya devuelva tus datos. Todo lo demás lo configuras en un formulario del panel de control: no hay ninguna devolución de llamada, webhook ni script de navegador que desarrollar.
Casos de uso
Estado del pedido
Buscar un pedido por su número y devolver su estado actual
Seguimiento de envíos
Devolver el último estado de seguimiento de un número de seguimiento
Comprobación de stock
Devolver la disponibilidad en tiempo real de un producto o una SKU concretos
Búsqueda de cuenta
Devolver los detalles de cuenta o suscripción de un identificador
Configuración
1
Abrir las herramientas personalizadas
Ve a /custom-tools/ y haz clic en Añadir herramienta
2
Describe la herramienta
Dale un nombre, una descripción clara y la URL de tu punto de conexión
3
Define los parámetros
Añade las entradas que la IA debe extraer y enviar (por ejemplo, order_number)
4
Guardar & probar
Guarda y luego hazle a tu bot una pregunta acorde para verlo en acción
Campos
- Nombre: un identificador para la función (letras, números, guiones bajos), por ejemplo
get_order_status. La IA ve este nombre.
- Descripción: el campo más importante. Le indica a la IA cuándo debe llamar a la herramienta. Sé explícito: «Llama a esto siempre que el cliente mencione un número de pedido. No pidas verificación.»
- URL del punto de conexión: la URL HTTPS pública a la que llamará Asyntai.
- Método HTTP:
GET (solo lectura, recomendado) o POST (puede modificar datos; consulta Seguridad más abajo).
- Parámetros: las entradas que la IA extrae de la conversación y envía. Cada una tiene un nombre, un tipo, una descripción y un indicador de obligatoriedad. Para
GET se envían como parámetros de cadena de consulta; para POST, como un cuerpo JSON.
- Encabezado de autenticación (opcional): un nombre + valor de encabezado que se envía en cada llamada, por ejemplo
X-API-Key. Úsalo si tu punto de conexión requiere una clave.
Los parámetros son imprescindibles para que la IA pase cualquier valor. Si tu punto de conexión necesita una entrada (como un número de pedido), debes añadir un parámetro para ella; sin él, la IA no tiene dónde colocar el valor y llamará al punto de conexión vacío. Dos cosas importan:
- El nombre del parámetro debe coincidir exactamente con lo que espera tu punto de conexión. Un parámetro llamado
order_number se envía como ?order_number=... (GET) o {"order_number": "..."} (POST). Si tu punto de conexión lee id, nombra el parámetro id.
- Nunca escribes el valor tú mismo: solo declaras el parámetro. La IA lo rellena en el momento de la llamada a partir de lo que escribió el cliente.
Ejemplo práctico: búsqueda del estado de un pedido
Supongamos que tu tienda expone este punto de conexión:
GET https://yourstore.com/api/order-status?order_number=10294
…que devuelve un JSON como:
{
"found": true,
"status": "Accepted, preparing for shipment",
"carrier": "DHL",
"customer_message": "Your order has been accepted and is being prepared for shipment."
}
Configurarías una herramienta así:
- Nombre:
get_order_status
- Descripción: «Busca el estado de un pedido de cliente. Llama a esto de inmediato siempre que el cliente proporcione un número de pedido; no pidas verificación adicional. Usa el customer_message devuelto en tu respuesta.»
- URL del punto de conexión:
https://yourstore.com/api/order-status
- Método:
GET
- Parámetro:
order_number (string, obligatorio): «El número de pedido del cliente, normalmente de 8 o más dígitos.»
Cuando un cliente escribe «¿Cómo va mi pedido #10294?», la IA llama a get_order_status(order_number=10294), Asyntai consulta tu URL con ?order_number=10294 y la IA responde usando la respuesta.
Consejo: la IA envía los valores que decide; tú nunca los rellenas previamente. Mantén los nombres y las descripciones de los parámetros claros para que el modelo sepa exactamente qué extraer.
Qué recibe y qué debe devolver tu punto de conexión
- Solicitud: un
GET con tus parámetros en la cadena de consulta, o un POST con un cuerpo JSON. Se incluye cualquier encabezado de autenticación que hayas configurado.
- Respuesta: devuelve JSON (preferible) o texto sin formato. Asyntai pasa el cuerpo de vuelta a la IA. Un campo que la IA pueda citar directamente, como
customer_message, funciona bien.
- No encontrado / errores: devuelve una carga útil clara (por ejemplo, un objeto JSON con
found: false y un customer_message) para que la IA pueda responder con veracidad en lugar de adivinar.
Probar tu herramienta
Cada herramienta tiene un panel integrado Probar esta herramienta en la página de configuración, para que puedas verificar que funciona antes de que la use ningún cliente, y sin enviar un mensaje a través del bot.
- Introduce valores de ejemplo para los parámetros de la herramienta (por ejemplo, un número de pedido real).
- Haz clic en Ejecutar prueba. Asyntai llama a tu punto de conexión exactamente como lo haría la IA: la misma cadena de consulta o cuerpo JSON, el mismo encabezado de autenticación, el mismo tiempo de espera de 5 segundos y las mismas comprobaciones de seguridad.
- Verás el resultado al instante: una insignia de éxito/fallo, el estado HTTP, el tiempo de respuesta, la URL exacta a la que llamamos y la respuesta sin procesar de tu punto de conexión (con formato si es JSON).
Esto también funciona con cambios sin guardar, de modo que puedes ajustar la URL, los parámetros o el encabezado de autenticación y volver a probar hasta que devuelva lo que esperas.
Nota: probar una herramienta POST llama realmente a tu punto de conexión y puede modificar datos; el panel de prueba te avisa antes de ejecutarla. Para las herramientas GET de solo lectura no hay nada de qué preocuparse.
Seguridad: léelo
Tu punto de conexión es el límite de seguridad, no la IA. El widget de chat es público, y un visitante puede manipular a la IA para que llame a una herramienta con cualquier valor. Esto es así en todo sistema de llamada de herramientas con IA. Diseña tu punto de conexión en consecuencia:
- Prefiere GET / solo lectura. Las consultas (estado del pedido, stock, seguimiento) son seguras de exponer. Por eso GET es la opción predeterminada.
- POST requiere confirmación. Como POST puede modificar datos, una herramienta POST solo se puede guardar después de marcar una casilla que confirme que eres el único responsable de proteger y autorizar las solicitudes en tu propio punto de conexión. Nunca conectes reembolsos, cancelaciones, cambios de contraseña ni movimientos de dinero a menos que tu punto de conexión verifique la solicitud de forma independiente.
- Protégete contra la enumeración. Si una clave de búsqueda es adivinable (como números de pedido secuenciales), exige un segundo factor; por ejemplo, el número de pedido y el correo electrónico del pedido, y verifica que coincidan, para que un visitante no pueda leer los datos de otros clientes probando números.
- Nunca confíes en los argumentos de la IA. Valida y autoriza cada solicitud del lado del servidor como si proviniera de un atacante anónimo, porque efectivamente puede ser así.
Verificar las llamadas en vivo
Una vez que tu herramienta está en funcionamiento, cada invocación real de una conversación se registra. Para cada llamada registramos el nombre de la herramienta, los argumentos que envió la IA, la URL exacta que solicitamos, el estado HTTP, la respuesta y la duración. Esto te permite confirmar que una herramienta se activó en un chat real y ver qué devolvió tu punto de conexión, sin tener que rebuscar en tus propios registros de servidor. (El panel Probar esta herramienta de arriba sirve para comprobar la configuración tú mismo; este registro captura lo que ocurre durante conversaciones reales con clientes.)
Límites & salvaguardas
- Hasta 10 herramientas por sitio web.
- Tiempo de espera de 5 segundos por llamada; las respuestas se limitan a 10 KB.
- Los puntos de conexión deben ser URL
http(s) públicas. Las direcciones privadas, de bucle invertido y de red interna están bloqueadas.
- Disponible en los planes Standard y Pro.
- Facturación: cada llamada de herramienta cuenta como un mensaje adicional de tu plan. Una respuesta normal usa 1 mensaje; una respuesta en la que la IA llama a una herramienta usa 2 (la respuesta más la llamada de herramienta), porque una llamada de herramienta requiere una solicitud de IA adicional.
- Si una llamada a una herramienta falla (tiempo de espera, error, bloqueo), se le informa a la IA y responde con elegancia: no hará que la conversación se interrumpa.