Herramientas Personalizadas — Referencia Técnica
Esta página describe cómo funcionan las herramientas personalizadas por debajo de la interfaz, en términos técnicos, para desarrolladores y usuarios con perfil técnico. Se centra en el modelo y en el comportamiento observable, no en detalles de implementación.
Modelo de arquitectura
Una herramienta personalizada es una única llamada REST con nombre que el agente puede invocar a demanda. Lleva todo lo necesario para hacer la llamada y todo lo que el agente necesita para decidir cuándo hacerla:
| Campo | Propósito |
|---|---|
| Nombre + alias | Nombre legible y un identificador estable que el agente usa para llamarla |
| Descripción | Resumen de un párrafo — qué hace la herramienta, en lenguaje claro |
| Notas de uso | Guía más extensa que el agente lee para saber cuándo usarla (y las advertencias) |
| Método | El tipo de solicitud (GET / POST / PUT / PATCH / DELETE) |
| URL | La dirección específica a la que va la solicitud |
| Parámetros | Campos de ruta / consulta / encabezado / cuerpo, cada uno tipado y marcado como visible para la IA o fijo |
| Credencial | Opcional — el inicio de sesión guardado que la herramienta usa para autenticarse |
| Etiquetas | Se usan para agrupar herramientas por proveedor al mostrarlas |
Cada parámetro es visible para la IA (el agente decide el valor en el momento de la llamada, según la conversación) o fijo (siempre el mismo valor, incorporado a la definición).
Los parámetros del cuerpo deben contener campos con nombre, no un único bloque. Cada campo tiene su propio tipo, su marca de obligatorio y su marca de visible-para-la-IA / fijo — igual que los parámetros de ruta, consulta y encabezado. Esto permite que el agente complete los campos individualmente sin tener que construir un objeto JSON completo.
El flujo de creación guiado por IA
El asistente de IA construye herramientas en lotes, un kit a la vez. Un kit es el conjunto de herramientas creadas juntas para un par proveedor + credencial (p. ej., "Contactos de HubSpot" o "Clientes de Stripe").
El flujo está agrupado por fases — las operaciones se agrupan por tipo entre todas las herramientas del kit, en lugar de procesar cada herramienta de extremo a extremo. Para un kit de 3 herramientas, esto son unos 6 pasos en lugar de unos 18.
Comportamientos clave:
- Investigar primero, configurar después — la IA nunca adivina los nombres de los parámetros a partir del nombre de la herramienta. Lee la documentación oficial del proveedor (una búsqueda rápida más la extracción de cada página de endpoint) antes de escribir la forma de la solicitud.
- Llamadas reales de prueba — cada herramienta se prueba con una llamada real a la URL configurada antes de marcarla como validada. Una prueba aprobada produce una vista previa compacta junto a la herramienta; la respuesta completa se guarda aparte para revisión.
- Salidas de muestra — cuando la prueba de una herramienta produce un resultado útil (imagen, PDF, documento, datos estructurados), la IA lo adjunta al registro de la herramienta para que la Guía del kit lo pueda mostrar como vista previa.
- Advertencias — las limitaciones no evidentes (paginación, comportamiento asincrónico, acceso solo de pruebas, alternativas obsoletas) se adjuntan a la herramienta como notas
info/warning/critical. Aparecen como banderas en la Guía del kit y se agregan a las notas de uso de la herramienta para que el agente que la consume las vea en tiempo de ejecución. - Endpoints asincrónicos / de cola — si la operación "haz el trabajo" del proveedor es solo asincrónica, la IA prefiere una variante sincrónica, o divide el trabajo en un par
submit_*+get_*_result, o marca la herramienta con una advertencia crítica. Las herramientas asincrónicas nunca se publican sin una advertencia.
La sesión es de larga duración: el usuario puede volver más tarde y agregar más kits a la misma conversación, finalizar cada uno por separado o reiniciar desde el inicio si quiere empezar de cero.
Ciclo de vida del borrador
Dentro de una sesión, cada herramienta atraviesa una máquina de estados:
| Estado | Significado |
|---|---|
| draft | Plantilla en blanco, sin endpoint todavía |
| configured | Método, URL y parámetros completados (aquí se pueden adjuntar advertencias) |
| tested | Se ejecutó una llamada real; la vista previa compacta queda junto al borrador |
| validated | La prueba pasó; aquí se pueden adjuntar vistas previas de salida |
| created | El usuario pulsó Crear; la herramienta existe en su cuenta y puede asignarse a agentes |
Una prueba fallida devuelve la herramienta al estado configured para que la IA (o el usuario) corrija los parámetros y vuelva a probar.
Cómo un agente usa una herramienta personalizada en tiempo de ejecución
Cuando un agente decide llamar a una herramienta personalizada, la plataforma:
- Lee la definición guardada de la herramienta y la credencial que referencia (si la hay).
- Para cada parámetro, toma los visibles para la IA desde la intención del agente y usa los fijos tal cual.
- Sustituye la credencial en el lugar correcto según su familia de autenticación (encabezado, parámetro de consulta o token firmado — ver Credenciales — Referencia Técnica).
- Envía la solicitud a la URL configurada.
- Devuelve la respuesta al agente.
- Si la respuesta es grande, el agente ve una vista previa compacta y una referencia al contenido completo, en lugar de volcar todo el contenido en su contexto.
El agente nunca ve el secreto de la credencial en su contexto — solo sabe que la llamada fue autenticada.
Kits y agrupación de herramientas
Las herramientas creadas juntas mediante el flujo con IA quedan bajo una clave de kit (proveedor + credencial). El kit es la unidad que se muestra en la Guía del kit; al finalizarlo, cada herramienta se crea por separado como una herramienta con nombre en la cuenta del usuario.
Después de finalizar:
- Las herramientas son independientes — no dependen del kit del que provienen.
- Una herramienta puede asignarse a cualquier agente del usuario.
- Una herramienta puede editarse más tarde mediante el constructor manual.
- Las advertencias adjuntadas al crear pasan a formar parte de las notas de uso de la herramienta y viajan con ella.
Asignación y límite compartido de 25 herramientas
Una herramienta personalizada solo se ejecuta como parte de un agente. Cada agente tiene un presupuesto compartido de 25 herramientas entre las herramientas personalizadas y las conexiones de base de datos:
| Espacio | Cuenta como |
|---|---|
| Herramienta personalizada | 1 |
| Conexión de base de datos (lectura) | 2 |
| Conexión de base de datos (escritura) | 5 |
| Conexión de base de datos (completa) | 7 |
El límite se aplica al asignar una herramienta o al cambiar el permiso de una base de datos; intentar pasar de 25 falla con un mensaje claro. El catálogo de herramientas en sí puede contener muchas más; el límite solo afecta a lo que un agente tiene conectado a la vez.
Plantillas
Las plantillas son definiciones de herramientas preconfiguradas para servicios comunes — el método, la URL y la forma de los parámetros ya vienen completados. Instalar una plantilla la copia a la cuenta del usuario; el usuario sigue agregando su propia credencial y puede editar cualquier campo. Las plantillas aceleran la vía manual; no tienen comportamiento especial en tiempo de ejecución una vez instaladas.
Límites y garantías
- Una herramienta es una sola llamada REST — la orquestación de varios pasos corresponde a un agente o a una automatización.
- Los parámetros del cuerpo deben ser campos con nombre, no un único bloque.
- Cada herramienta se prueba con una llamada real antes de marcarse como validada.
- Las advertencias adjuntadas al crear son visibles para el agente que la consume en tiempo de ejecución, como parte de las notas de uso.
- Las vistas previas de salida de muestra viven con la guía del kit para revisión y no afectan el comportamiento en tiempo de ejecución.
- Cada agente tiene un presupuesto compartido de 25 herramientas entre personalizadas y conexiones de base de datos.
- El agente nunca ve el valor secreto de una credencial — solo el ID de la credencial que debe usar.
Qué sigue
- Crear con IA — el flujo guiado de creación
- Crear manualmente — el constructor manual
- Credenciales — Referencia Técnica — cómo funciona el lado de las credenciales