Skip to main content
Las herramientas permiten consultar datos en tiempo real o ejecutar acciones aprobadas, como comprobar disponibilidad, crear un ticket o consultar un pedido.
Para una configuración guiada, empieza con Conecta tu agente a un sistema de pedidos. Usa el endpoint ejecutable de ejemplo junto con esta referencia.

​
Endpoints

Scopes: tools:read, tools:write, tools:execute y tools:logs:read según la operación.

​
Definir una herramienta

Incluye:
  • Nombre y descripción que indiquen cuándo debe usarla la IA.
  • Método y endpoint HTTPS.
  • Autenticación almacenada de forma segura.
  • Parámetros definidos con JSON Schema.
  • Estado inactivo hasta completar las pruebas.

​
Requisitos del endpoint

  • Valida todos los parámetros.
  • Responde con JSON breve y estable.
  • Usa timeouts y operaciones idempotentes cuando existan mutaciones.
  • No registres tokens, contraseñas ni datos innecesarios.
  • Devuelve errores claros sin filtrar información interna.

​
Ejemplo de conversación y registro de herramienta

Supón que get_order_status está activa, es de solo lectura y está habilitada en Área de pruebas.

​
1. El cliente solicita información actual

La IA identifica que necesita datos en tiempo real y llama a la herramienta con:

​
2. El backend devuelve un resultado estructurado

Devuelve hechos en lugar de texto dirigido al cliente. Así la IA puede adaptar la respuesta al idioma y al contexto de la conversación.

​
3. Visito registra la llamada para el operador

Mientras se ejecuta, Área de pruebas puede mostrar:
Cuando termina correctamente, la actividad cambia a:
En una conversación activa, la línea de tiempo de Conversaciones muestra actualmente el registro compacto Action completed. El cliente no recibe este registro ni la respuesta JSON del backend. Abre Build → Llamadas a herramientas → Logs de actividad para consultar el detalle:

​
4. La IA responde al cliente

El registro confirma que se intentó una acción; no es la respuesta para el cliente. Si el endpoint falla, aparece Action failed y el log contiene el error. La IA no debe afirmar que una consulta o modificación terminó correctamente cuando la herramienta falló.

​
Pruebas y registros

Usa /test antes de activar la herramienta. Revisa los logs para analizar entrada, salida, duración, estado y errores. Un intento de herramienta consume un crédito aunque no devuelva el resultado esperado.
Mantén credenciales y lógica sensible en el servidor. Solicita aprobación humana antes de habilitar acciones con efectos importantes.