Herramienta API Externa

La herramienta External API permite que el agente consulte (o accione) un sistema tuyo durante la conversación: el estado de un pedido, el saldo de un contrato, la apertura de un ticket.

Solicitud

Campo	Qué indicar
Método HTTP	GET, POST, PUT, PATCH o DELETE
URL	La dirección del endpoint. Puede contener placeholders
Timeout de la solicitud	30 segundos (recomendado), 60 o 120
Credencial	Una credencial global delegada a esta solución, o Sin credencial

La lista de credenciales solo muestra las delegadas a esta solución; consulta Credenciales.

Headers y body

+ Agregar Header incluye las cabeceras necesarias (por ejemplo, Content-Type). El campo Body arma el cuerpo de la solicitud en los métodos que lo aceptan.

Tanto la URL como los headers y el body admiten placeholders: valores que el agente completa a partir de la conversación. Así es como el número de pedido que indica la persona llega a tu endpoint.

Nunca escribas un secreto en un header

Las claves de API, tokens y contraseñas entran por Credencial, no escritas en un header. Las credenciales se guardan de forma segura y se pueden rotar sin editar cada herramienta.

Tratamiento de la respuesta

Campo	Qué hace
Aplicar protección de truncamiento de respuestas largas	Sí (recomendado) recorta respuestas muy grandes antes de entregarlas al modelo
Truncar respuestas mayores que (caracteres)	El límite aplicado

Deja la protección activada. Una respuesta enorme de API consume el contexto del agente, encarece el turno y suele empeorar la respuesta. Si se está cortando información útil, el camino es que el endpoint devuelva menos, no subir el límite indefinidamente.

Resumen de la configuración

El bloque al pie del formulario muestra, en un solo lugar, lo que se guardará: método, URL, credencial, cantidad de headers y si hay body. Revísalo antes de guardar.

Cómo validar

1. Guarda la herramienta y confirma que aparece Habilitada en la lista.
2. Abre el chat y haz la pregunta que debería activarla.
3. Expande el bloque Actividad encima de la respuesta para ver si la llamada ocurrió.

Síntoma	Causa probable
El agente nunca llama a la herramienta	Descripción vaga o herramienta deshabilitada
La llamada falla con error de autorización	Credencial equivocada, vencida o no delegada a la solución
El agente inventa el valor de un parámetro	Falta una instrucción que diga de dónde tomar el dato; refuérzala en las instrucciones del agente
La respuesta llega cortada	Límite de truncamiento; haz que el endpoint devuelva menos