Crear una herramienta manualmente
Crear una herramienta a mano es como conectar un cable atornillándolo uno a uno — más lento que dejar que lo haga la IA, pero cada decisión es tuya. Esta es la ruta correcta cuando ya conoces bien el servicio, cuando es un servicio privado o interno sobre el que la IA no puede leer en línea, o cuando quieres que cada campo sea deliberado.
Image: La página de configuración con campos de endpoint, método y parámetros
Antes de empezar
- Una idea clara de lo que debería hacer la herramienta — una acción por herramienta funciona mejor ("listar contactos", no "hacer todo lo de contactos").
- La dirección a la que la herramienta debe llamar y el tipo de solicitud — normalmente copiados de la página de documentación del servicio para esa acción.
- Una credencial guardada (los datos de inicio de sesión que Nirvai conserva para poder hablar con el servicio en tu nombre), si el servicio la necesita. Configura una primero en Credenciales si aún no lo has hecho.
- Un valor de ejemplo real para cada campo, para que puedas probar la herramienta con una llamada real antes de guardar.
Paso a paso
El constructor manual tiene dos páginas: primero Configuración, luego Pruebas.
1. Ponle nombre a la herramienta y elige un inicio de sesión
- Abre Herramientas Personalizadas y haz clic en Nueva herramienta.
- Dale a la herramienta un nombre corto y en lenguaje claro ("Obtener contactos de HubSpot"). El alias se completa solo en snake_case (
get_hubspot_contacts). - Escribe una descripción que diga exactamente lo que hace la herramienta. Tu agente la lee para decidir cuándo usarla, así que una descripción específica ("Busca contactos en HubSpot por email o nombre") es mejor que una vaga ("contactos de HubSpot").
- Escribe una nota de uso con un ejemplo de cuándo recurrir a esta herramienta ("Úsala cuando el usuario pregunte por leads, clientes o contactos").
- Elige un inicio de sesión guardado para el servicio. Déjalo vacío si el servicio no necesita uno.
2. Define la dirección y el tipo de solicitud
- Pega la URL completa — la dirección específica que hace una sola cosa, por ejemplo
https://api.hubapi.com/crm/v3/objects/contacts. - Elige el tipo de solicitud (GET, POST, PUT, PATCH o DELETE) — la página de documentación de la acción suele indicar cuál usar.
Si los tipos de solicitud te resultan nuevos, esta es la versión cotidiana:
| Tipo de solicitud | Qué hace | Analogía cotidiana |
|---|---|---|
| GET | Lee información sin cambiar nada. | Buscar a alguien en tu libreta de direcciones. |
| POST | Crea algo nuevo. | Agregar un contacto nuevo a tu libreta. |
| PUT / PATCH | Actualiza algo que ya existe. | Editar el teléfono de un contacto. |
| DELETE | Elimina algo. | Tachar un contacto. |
3. Agrega los campos que la herramienta envía
Las herramientas envían piezas de información con cada solicitud, llamadas parámetros. Hay cuatro lugares donde puede ir un campo, según lo que espere el servicio:
| Dónde va el campo | Cuándo elegir esto | Ejemplo |
|---|---|---|
| Path | El campo forma parte de la dirección misma, como /users/{user_id}. | user_id → 12345 |
| Query | El campo se agrega al final de la dirección después de un ?. | query → zapatos, limit → 10 |
| Header | El campo es información oculta adjunta a la solicitud — común para cosas como la versión de la API. | X-API-Version → 2.0 |
| Body | El campo se envía dentro del cuerpo de la solicitud, usado por POST / PUT / PATCH. | name → Juan, email → juan@example.com |
Para cada campo, completas:
| Configuración | Qué significa |
|---|---|
| Nombre | El nombre exacto del campo que espera el servicio. |
| Tipo | Si es texto, un número, un sí-o-no, una lista o un objeto. |
| Requerido | Si la solicitud falla sin este campo. |
| Quién lo completa | El agente lo completa = tu agente elige un valor a partir de la conversación. Siempre el mismo valor = tú fijas el valor una vez y la herramienta lo usa cada vez. |
| Descripción | Una nota breve que le dice al agente qué poner aquí (solo importa cuando lo completa el agente). |
Image: El panel de edición de parámetros con campos de nombre, tipo, requerido y descripción
Para los campos que completa el agente, escribe descripciones que le digan exactamente qué buscar. En lugar de "El ID", escribe "El número de pedido del cliente, normalmente mencionado como 'pedido #12345' o 'pedido 12345' en la conversación". Las descripciones específicas hacen que el agente elija el valor correcto con mucha más frecuencia.
Los campos del body deben agregarse como campos con nombre — una fila por campo, con un nombre y un tipo. No pegues un bloque entero de JSON dentro de un solo parámetro de body; la herramienta necesita conocer cada campo por separado para que el agente pueda completarlos correctamente.
4. Prueba la herramienta
- Avanza a la página de Pruebas.
- Completa un valor de ejemplo real para cada campo.
- Haz clic en Probar — Nirvai hace una llamada real al servicio usando tu inicio de sesión.
- Mira la respuesta. Si el servicio devolvió lo que esperabas, listo. Si no, vuelve a Configuración y ajusta.
- Cuando la prueba pase, haz clic en Guardar.
Image: La página de pruebas con campos de parámetros de prueba y la respuesta de la API
Para más detalles sobre cómo leer las respuestas de prueba y rastrear fallas, consulta Probar tus herramientas.
Atajo: pega un comando cURL
Si la documentación del servicio te da un comando cURL listo (o tienes uno de una herramienta como Postman), puedes saltarte la mayor parte de la escritura.
- En la página de Configuración, haz clic en Importar cURL.
- Pega el comando cURL completo.
- El constructor completa automáticamente la dirección, el tipo de solicitud, los headers y los campos del body.
- Revisa lo que completó, corrige lo que haga falta y continúa a Pruebas.
Esto ahorra mucho tiempo cuando ya tienes un ejemplo de llamada que funciona.
Solución de problemas
| Problema | Qué revisar |
|---|---|
| La prueba devuelve un error de "no autorizado" o "401" | El inicio de sesión es incorrecto, falta o está vencido. Abre la credencial en Credenciales y vuelve a ingresar el código privado. |
| La prueba devuelve un error de "no encontrado" o "404" | La dirección es incorrecta, o un valor que pusiste en un campo de path no existe. Vuelve a leer la página de documentación del servicio para esa acción y compara. |
| La prueba devuelve un error de "campo faltante" | Alguno de los campos que marcaste como requerido no se está enviando, o el nombre del campo no coincide exactamente con lo que espera el servicio (cuida mayúsculas y guiones bajos). |
| El agente nunca parece usar la herramienta | La descripción o la nota de uso no es lo suficientemente específica. Reescríbela mencionando las palabras exactas que dicen los usuarios ("número de pedido", "teléfono", "lead") para que el agente reconozca cuándo recurrir a ella. |
| El agente completa un campo con el valor equivocado | La descripción del campo no es clara. Reescríbela con ejemplos de cómo se ve el valor, o cambia el campo a "siempre el mismo valor" si el agente no debería estar eligiendo. |
| Quiero enviar un objeto JSON completo | Agrega cada campo de primer nivel del JSON como su propio parámetro de body — una fila por campo. El constructor los ensambla en JSON por ti. |
Qué sigue
Una vez que tu herramienta pase la prueba, continúa a Usar herramientas con agentes para entregar la nueva herramienta a los agentes que deberían poder usarla.