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 cuatro tipos que creas tú, 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.

Las herramientas de agente personalizadas requieren el plan Growth o superior. En Free y Starter, crear una herramienta o asignarla a un canal se rechaza con «Las herramientas de agente personalizadas están disponibles a partir del plan Growth». Las herramientas de Shopify y WooCommerce que aparecen automáticamente al conectar una tienda no se ven afectadas: vienen con la integración en cualquier plan.

Las herramientas de tienda integradas comprueban quién pregunta. Las herramientas de pedidos y seguimiento que llegan con una conexión de Shopify o WooCommerce necesitan el número de pedido y el correo con el que se realizó, y no devuelven nada si los dos no coinciden. Una herramienta que construyas tú no obtiene esa comprobación por sí sola: si devuelve los datos de un cliente a partir de un identificador que otro cliente podría adivinar, la IA los entregará. Cómo se comportan las integradas se explica en Primeros pasos con Shopify.

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 cuatro tipos de herramienta que creas tú#

HelpStack tiene siete tipos de herramienta en total. Cuatro son las que construyes tú y se describen abajo. Las otras tres aparecen solas y no se crean desde esta pantalla: las herramientas de Shopify y WooCommerce aparecen al conectar una tienda, y las de Control vienen integradas con HelpStack. Esas tres no se pueden crear ni eliminar, pero sí puedes añadirles una nota para que la IA sepa cómo lo gestiona tu negocio.

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. Úsala cuando la acción pertenezca de verdad al navegador del visitante: señalar un botón de tu propia interfaz, leer en qué pantalla está, abrirle un panel.

Tu página proporciona el handler. Regístralo por nombre con el script del widget:

window.HelpStack('registerTool', 'highlight', async ({ section }) => {
  document.querySelector(`#${section}`)?.scrollIntoView({ behavior: 'smooth' });
  return { highlighted: section };
});

Lo que devuelva el handler es lo que lee la IA. Consulta Herramientas de agente personalizadas para el shim de cola que te permite registrar antes de que cargue el script, y para el contrato postMessage subyacente si prefieres responderlo tú mismo.

Consulta por correo electrónico (EMAIL_INQUIRY)

Los otros dos tipos responden dentro de la misma respuesta. Una consulta por correo electrónico no. Hay preguntas que no se pueden responder desde tus propios sistemas: un paquete se retrasa y solo el transportista sabe dónde está; una pieza va con retraso y solo el proveedor puede decir cuándo sale. Este tipo deja que la IA se lo pregunte a ellos y retoma la conversación cuando llega la respuesta.

Cómo funciona en la práctica:

1. Un cliente pregunta algo que la IA no puede responder por su cuenta.
2. La IA escribe el correo ella misma, con sus propias palabras, y lo envía a la dirección que hayas indicado desde uno de tus buzones conectados. No hay plantilla.
3. Le dice al cliente que lo estáis comprobando, con el texto que hayas configurado.
4. La conversación pasa al estado Esperando respuesta (WAITING). No significa "necesita una persona", así que se mantiene fuera de la cola de trabajo de tu equipo, y el tiempo de espera se resta de la analítica de tiempo de resolución.
5. Cuando la otra parte responde, HelpStack vincula esa respuesta con la pregunta a la que pertenece y la IA le escribe al cliente lo que ha averiguado. La conversación vuelve a Abierta con una marca de no leída.

Mientras espera, la IA sigue atendiendo al cliente con normalidad. Si el cliente insiste, dice que sigue esperando en lugar de escribir al transportista por segunda vez.

Las consultas por correo están desactivadas por defecto para todas las organizaciones. Requieren el plan Growth como cualquier otra herramienta personalizada, y HelpStack tiene que activarte la función. Es deliberado: ninguna otra herramienta envía correo real desde tu propio dominio por iniciativa de la IA, y eso no debería llegar con una mejora de plan que nadie ha hablado contigo.

Qué configuras

Además del nombre, la descripción y el JSON Schema de parámetros habituales:

• A quién escribe la IA. La dirección a la que va la pregunta, por ejemplo el buzón de soporte de un transportista.
• Enviar desde. Uno de tus canales de correo activos. El mismo buzón envía la pregunta y recibe la respuesta, así que tiene que ser un buzón que HelpStack consulte.
• Cuánto esperar. Entre 1 y 720 horas.
• Si nadie responde a tiempo. Enviar un recordatorio, pasar la conversación a una persona, o decirle al cliente que todavía no hay respuesta.
• Qué le dice la IA al cliente mientras espera. Una instrucción corta, no un guion. Que sea breve y sin prometer plazos.
• Cómo se envía la pregunta. "Enviarla automáticamente" es la única opción que funciona hoy. "Prepararla para aprobación" aparece a su lado, deshabilitada a propósito: la cola de aprobación que necesitaría todavía no existe, así que una herramienta configurada así rechazaría cada llamada después de que la IA ya le hubiera dicho al cliente que lo estaba comprobando. Se muestra en lugar de ocultarse para que no busques un control que parece faltar.

La descripción de la herramienta es donde van tus reglas para esa otra parte. "Menciona solo el número de pedido, nunca el correo ni el teléfono del cliente" es justo la línea que la IA lee antes de escribir.

Dale a la herramienta un campo para el número de pedido o de seguimiento

Esto importa más de lo que parece.

Antes de que una consulta salga de tu buzón, HelpStack quita del asunto y del cuerpo lo que parece sensible: secuencias largas de dígitos, secretos etiquetados como una contraseña o un número de tarjeta, y direcciones de correo. Lo que la IA haya puesto en un parámetro con nombre de tu herramienta, trackingNumber u orderId, pasa intacto. Lo que haya escrito en el texto libre, no.

Así que una herramienta cuyos parámetros son solo asunto y cuerpo no puede preguntar por un paquete: el número de seguimiento sale censurado y el transportista no tiene con qué trabajar. Esa misma forma rompe otra cosa: HelpStack reconoce una pregunta repetida comparando los parámetros con nombre, de modo que sin ellos la siguiente pregunta, realmente distinta, se rechaza en esa conversación como duplicada.

El formulario de la herramienta te avisa debajo del editor de parámetros, y el aviso desaparece en cuanto el esquema tiene un campo propio para el identificador. El diálogo manual muestra el mismo aviso por la misma razón.

El filtro es una red de seguridad, no una garantía. Detecta errores evidentes. No es un sistema de prevención de fuga de datos y no pretende encontrarlo todo. Sé explícito en la descripción de la herramienta sobre qué puede y qué no puede mencionar la IA, y elige contrapartes a las que ya confiarías la pregunta.

Qué ves en la conversación

Bajo el hilo del cliente, cada pregunta que la IA ha enviado tiene su propia tarjeta. Al desplegarla ves la pregunta tal como salió de verdad (con una nota si se quitó algo por el camino) y todos los mensajes intercambiados con la otra parte desde entonces. Ese hilo paralelo no aparece en ningún otro sitio de tu bandeja, así que esta tarjeta es el único lugar donde leerlo.

Una tarjeta está en uno de estos estados: Esperando respuesta, Respondida, Necesita que la revises, Sin respuesta a tiempo, Cancelada o No se pudo enviar.

Necesita que la revises significa que llegó una respuesta y HelpStack no pudo saber si respondía a la pregunta. La conversación pasa a una persona y la tarjeta ofrece tres opciones, justo al lado del intercambio del que tratan:

• Esta es la respuesta. Cierra la pregunta con ese texto y deja que la IA le escriba al cliente. La conversación sale de tu cola.
• No es la respuesta, seguir esperando. Deja la pregunta abierta para que un mensaje posterior y más claro pueda cerrarla, y devuelve la conversación a Esperando respuesta.
• Cerrar la pregunta. Renuncia a esa pregunta. Al cliente no se le dice nada y la conversación se queda contigo.

Si hay dos preguntas abiertas a la vez en la misma conversación, ambas tarjetas muestran la marca. La marca pertenece a la conversación y no a una pregunta concreta, así que no puede decir qué respuesta la provocó. Justo por eso la tarjeta muestra el intercambio: léelas y verás qué contraparte escribió de verdad.

También puedes preguntar tú. Abre el menú ⋮ de la conversación, elige Preguntar a un tercero, escoge la herramienta, rellena sus campos y edita el asunto y el cuerpo. Sale por el mismo camino que usa la IA, con los mismos límites. Para decidir sobre una respuesta no hay atajo: esos tres botones se quedan dentro de la tarjeta, para que nadie acepte una respuesta que no ha leído.

Qué hace la IA con la respuesta

Cuando la respuesta se reconoce como tal, su texto se le da a la IA como contexto para el mensaje que le escribe a tu cliente. La IA tiene instrucciones de responder con tu tono y de no mencionar herramientas ni procesos internos, y se aplican las reglas de respuesta habituales. Aun así, la otra parte está escribiendo dentro de un prompt. Si eso importa para un buzón concreto, deja la aprobación activada en el canal para que una persona lea el borrador antes de que salga.

Trabajo asíncrono (CALLBACK_JOB)

Un trabajo asíncrono es el hermano de la consulta por correo, pero para trabajo en lugar de una pregunta y para una máquina en lugar de una persona. La IA entrega una tarea a uno de tus sistemas, la conversación espera, y se reanuda cuando ese sistema informa de que la tarea ha terminado.

Úsalo cuando el trabajo realmente dure más de lo que una respuesta puede esperar: una reconstrucción, una actualización masiva, un renderizado, cualquier cosa en cola detrás de tus propios workers. Si tu sistema puede responder mientras la petición sigue abierta, usa mejor una herramienta de servidor: la configuración es más simple y la respuesta llega en el mismo mensaje.

En qué se diferencia de una consulta por correo:

Configurarlo requiere a alguien técnico de tu lado: tu sistema debe aceptar la tarea y llamar de vuelta a HelpStack cuando termine. El contrato está descrito en Herramientas asíncronas (callback).

Disponibilidad. Los trabajos asíncronos están detrás de una feature flag. Pídenos que la activemos para tu organización; a partir de ahí creas y editas la herramienta tú mismo en Ajustes → Herramientas del agente, igual que una consulta por correo.

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.

Añadir una nota a una herramienta integrada

Las herramientas de Shopify, WooCommerce y Control no se pueden editar ni eliminar: las mantenemos nosotros, y cualquier mejora en su funcionamiento te llega automáticamente. Eso normalmente te dejaría sin forma de contarle a la IA algo específico de tu negocio, así que esas herramientas admiten una nota.

La nota se añade a la descripción de la herramienta en lugar de sustituirla, y eso es lo que permite que ambas cosas sean ciertas a la vez: nosotros seguimos mejorando el texto y tu instrucción sobrevive a cada actualización. Úsala para lo que solo tú sabes:

Los pedidos realizados después de las 14:00 se envían al siguiente día laborable.

No enviamos a apartados de correos. Pide una dirección postal antes de prometer una entrega.

Deja la nota vacía para eliminarla. Todo lo demás de la herramienta sigue siendo nuestro.

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.

Las herramientas de consulta por correo son solo a nivel de organización. Las creas y editas en Configuración → Herramientas del agente, nunca en la pestaña Herramientas de un canal; una herramienta de este tipo atada a un canal no aparecería en ningún sitio donde pudieras editarla o desactivarla. Aun así llegan a todos los canales, y el buzón desde el que envían forma parte de la propia herramienta.

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.
• Conversaciones y bandeja de entrada — el estado Esperando respuesta en el que queda una conversación mientras una consulta por correo está fuera.
• Canales — asigna o anula herramientas por canal en la pestaña Herramientas, y conecta el buzón desde el que envía una consulta por correo.
• 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.