Herramientas del agente (resumen)

Las herramientas del agente otorgan capacidades personalizadas a tu IA. En lugar de responder solo desde el texto que conoce, la IA puede llamar a tus sistemas mientras redacta una respuesta — por ejemplo para "consultar el estado de un pedido" o "verificar una fecha de entrega" — e incorporar el resultado en su respuesta. Esta guía es el resumen conceptual y orientado a tareas: qué son las herramientas, los dos tipos, cómo crear una, cómo escribir una descripción que la IA use correctamente, importar desde OpenAPI y asignar herramientas a canales. Para especificaciones de endpoints, seguridad y JSON Schema, consulta la guía del integrador enlazada a lo largo del texto.

Encontrarás las herramientas en Configuración → Herramientas del agente (ruta /settings/agent-tools). Para gestionar herramientas del agente se requiere el rol OWNER o ADMIN; los agentes y visualizadores generalmente pueden consultarlas.

Qué es una herramienta del agente#

Una herramienta es una capacidad personalizada que le otorgas a la IA. Cuando el mensaje de un cliente requiere información en tiempo real o específica de su cuenta — por ejemplo, el estado de su pedido — la IA puede llamar a la herramienta, obtener datos reales y utilizarlos para redactar una respuesta precisa. Esto transforma la IA de algo que solo conoce tu documentación en algo que puede actuar en tu nombre dentro de los límites que tú defines.

Los dos tipos de herramienta#

Del lado del servidor (SERVER_SIDE)

HelpStack llama a un endpoint HTTP que tú provees. Tú defines:

• Nombre
• Descripción (consulta Cómo escribir una gran descripción — este es el campo más importante)
• URL de tu endpoint
• Método HTTP
• Cabeceras opcionales
• Un JSON Schema de parámetros que describe los datos que la IA debe proporcionar

Este es el caso habitual: HelpStack se comunica con tu backend, que devuelve los datos.

Del lado del cliente (CLIENT_SIDE)

La herramienta se ejecuta en el navegador del visitante del sitio web en lugar de en tu servidor. Es avanzado — úsalo solo cuando la acción genuinamente necesite ocurrir en el contexto del navegador del visitante.

Crear y gestionar herramientas#

Desde Configuración → Herramientas del agente puedes:

• Crear una herramienta (elige su tipo y rellena sus campos).
• Editar una herramienta existente.
• Eliminar una herramienta.
• Activar o desactivar una herramienta como Activa / inactiva sin eliminarla.

Las llamadas a herramientas quedan registradas, por lo que puedes revisar lo que invocó la IA.

Cómo escribir una gran descripción#

La descripción es fundamental — es lo que lee la IA para decidir cuándo llamar a la herramienta. Escríbela como instrucciones para un nuevo compañero que nunca ha visto tus sistemas:

• Di cuándo usarla y para qué sirve.
• Di qué información se necesita para llamarla.

Un buen ejemplo:

"Usa esto cuando el cliente pregunte sobre el estado de un pedido existente. Requiere su número de pedido."

En este caso, ORDER_NUMBER sería uno de los parámetros definidos en el JSON Schema de parámetros de la herramienta. Una descripción vaga lleva a que la IA llame a la herramienta en el momento equivocado o la ignore por completo; una clara la hace fiable.

Importar desde OpenAPI#

Si tus sistemas ya tienen una especificación OpenAPI, no tienes que definir las herramientas una por una. Usa "Importar desde OpenAPI" y proporciona tu especificación — HelpStack genera las herramientas a partir de ella. Esta es la forma más rápida de exponer una API existente a la IA.

Herramientas globales de la organización vs. por canal#

• Las herramientas pueden definirse a nivel de organización para que estén disponibles en todas partes.
• Las herramientas también pueden asignarse o anularse por canal en Configuración → Canales → canal → Herramientas.

Esto significa que puedes mantener un conjunto compartido de herramientas y aun así adaptar cuáles puede usar un canal en particular — por ejemplo, exponer una herramienta de consulta de pedidos solo en tu canal de soporte.

Dónde profundizar#

Esta guía es intencionadamente conceptual. Para los detalles técnicos — contratos de endpoints, autenticación y seguridad, cabeceras, y cómo escribir el JSON Schema de parámetros — consulta la guía del integrador:

• Herramientas de agente personalizadas (guía del integrador)

Relacionado#

• Herramientas de agente personalizadas (guía del integrador) — especificaciones de endpoints, seguridad y JSON Schema.
• Canales — asigna o anula herramientas por canal en la pestaña Herramientas.
• Proveedores de IA — el modelo que decide cuándo llamar a tus herramientas.
• Respuestas de IA — cómo encajan las herramientas en la redacción de una respuesta.
• Base de conocimiento — fundamenta las respuestas en tu contenido (las herramientas proveen datos en tiempo real).
• Glosario — definiciones de del lado del servidor, del lado del cliente, OpenAPI y más.