Herramientas y conexiones
Piensa en una llave y la máquina que abre. La llave sola no hace nada; la máquina sola no
arranca. Una conexión (credentials) es la llave — el acceso que demuestra que puedes entrar a
Stripe, a HubSpot, a tu propia API. Una herramienta (tools) es la máquina — una acción concreta
que gira esa llave y hace algo: crear un contacto, traer una factura, publicar una actualización.
Esa división es toda esta página. Tu asistente ejecuta máquinas. Nunca tiene las llaves.
Los verbos
Dos áreas, y siempre funcionan en el mismo orden: encontrar (o preparar) la conexión, y después construir o ejecutar la herramienta que la usa.
tools — la acción
| Verbo | Permiso | Qué hace |
|---|---|---|
tools.use | run | Ejecuta una herramienta guardada en la nube de Nirvai. Necesita una sesión. |
tools.<alias> | run | La misma ejecución, dirigida directamente — cada herramienta guardada se puede llamar por su propio alias. |
tools.describe_schema | read | La gramática para escribir una herramienta. Pura documentación, sin efectos. |
tools.propose | create | Redacta una o varias herramientas en una página de revisión. No crea nada. |
tools.create | create | Crea las herramientas de verdad, cada una ligada a una conexión que ya existe. |
tools.edit | write | Cambia una herramienta que ya tienes — su dirección, sus parámetros o qué conexión usa. |
Dónde lo terminas tú — la página de la herramienta
tools.propose redacta; tú creas. El enlace abre /external/tools/… dentro de Nirvai, donde puedes
ejecutar la herramienta una vez para ver qué devuelve antes de que exista siquiera.
- Pruébala antes de crearla. Una herramienta que devuelve lo equivocado se nota mucho antes aquí que después de una semana de que un agente la use.
- Tienes que haber iniciado sesión, y solo tú puedes abrirla. Un enlace de propuesta no se comparte.
- No se puede hacer clic dos veces — al volver a abrirla verás Creado ✓, y tu asistente lee la herramienta nueva desde el feed en lugar de proponer otra vez.
credentials — el acceso
| Verbo | Permiso | Qué hace |
|---|---|---|
credentials.list | read | Todas tus conexiones, cada una con un id estable y si está autorizada. |
credentials.search | read | La misma lista, filtrada por una búsqueda. |
credentials.describe | read | El estado en vivo de una conexión — tipo, nombre y si ya está autorizada. |
credentials.describe_schema | read | Qué campos necesita cada tipo de conexión, y cuáles de ellos son secretos. |
credentials.propose | create | Escribe una guía paso a paso en una página que abres y completas tú. |
credentials.create | create | Crea una conexión directamente — solo cuando tú mismo le pasaste el valor. |
credentials.edit | write | Cambia la configuración no secreta de una conexión, como su nombre. |
Listar e inspeccionar tus herramientas pasa por las herramientas maestras:
nirvai_list_resources(kind="tools") para el catálogo y nirvai_describe(kind="tools", ref=…) para
los parámetros en vivo de una. Siempre describe antes de ejecutar: los parámetros que tu asistente
puede completar salen de esa respuesta, nunca de la memoria. Las conexiones se direccionan por su
id y las herramientas por su alias o id — nunca por el nombre visible, porque los nombres se repiten.
Dónde lo terminas tú — la página de la conexión
credentials.propose envía solo los nombres de los campos, nunca un valor. El enlace abre
/external/credentials/… dentro de Nirvai, y el secreto lo escribes ahí, en la propia página de
Nirvai.
- El secreto es solo tuyo. Nunca entra al contexto de tu asistente, ni a su resultado, ni al feed.
- El login de un proveedor se termina en tu navegador. La acción puede volver como
needs_authcon un enlace; tú completas el inicio de sesión del proveedor y después tu asistente vuelve a listar tus conexiones para ver si quedó. No hay ninguna señal que pueda esperar. - Tienes que haber iniciado sesión, y solo tú puedes abrirla. Un enlace de propuesta no se comparte, y al volver a abrir una ya completada verás Conectado ✓ en vez de una segunda conexión.
- ¿Algo no cuadra en la página? Devuélvele su bloque para copiar y pegar y tu asistente vuelve a proponer — ver la referencia de MCP.
La regla del secreto
Tu asistente no puede completar una conexión. Propone los nombres de los campos — "aquí va una clave secreta", "este es el nombre del encabezado" — y te pasa un enlace. Tú escribes el secreto en la propia página de Nirvai. El valor nunca entra al contexto de tu asistente, nunca aparece en el resultado que recibe y nunca llega al Feed de Actividad. Un valor secreto puesto dentro de una propuesta se rechaza de plano. (La única excepción es un valor que tú decidas entregarle para enviarlo una sola vez — una propuesta nunca lleva uno.)
Las conexiones que usan el login del proveedor no se pueden terminar sin ti: la ventana de autorización del proveedor tiene que abrirse en tu pantalla. Cuando lo hace, tu asistente se entera igual que lo harías tú — releyendo la lista y viendo si la conexión quedó autorizada. No hay ninguna señal de finalización que pueda esperar, así que verifica en lugar de estar consultando.
Cuando una herramienta se ejecuta, la llave se gira del lado de Nirvai: tools.use resuelve y
descifra la conexión ligada en la nube, ejecuta la herramienta ahí y devuelve una vista previa
acotada. El secreto no vuelve con el resultado.
Los canales no son conexiones
WhatsApp · Instagram · Messenger · Meta Ads · Telegram · Slack · Discord · Microsoft Teams · chat
web no son conexiones ni herramientas. Se configuran en la app de Nirvai y después se conectan a
un agente. credentials.propose los rechaza activamente y responde con adónde ir en su lugar —
porque una conexión con ese nombre nunca podría existir, y te enterarías recién después de
aprobarla. Si tu asistente se ofrece a "conectar WhatsApp por vos", está equivocado; pídele que te
indique la página.
Ejemplos reales
Preparar una conexión nueva y después usarla. El ciclo completo, en el orden en que pasa:
# 1. Mira primero — puede que la conexión ya exista.
nirvai_execute(alias="credentials.list", args={},
description="Check whether Stripe is already connected")
# 2. No había nada. Propone una — solo NOMBRES de campos, ningún valor.
nirvai_execute(alias="credentials.propose",
args={ items: [{ type: "apikey", label: "Stripe (live)", provider: "stripe",
steps: [ …una guía: dónde conseguir la clave y dónde escribirla… ] }] },
session="stripe-setup",
description="Propose a Stripe connection for the user to complete")
# → un enlace a una página de revisión. Tú la abres, escribes la clave y haces clic en Conectar.
# 3. Verifica que quedó creada y toma su id.
nirvai_execute(alias="credentials.list", args={},
description="Read back the new connection's id")
Ejecutar una herramienta guardada. Una vez que existe, se llama por su propio alias:
nirvai_execute(
alias = "tools.hubspot_create_contact",
args = { body: { properties: { email: "ada@acme.com", firstname: "Ada" } } },
description = "Add Ada to the CRM after today's call",
session = "crm-cleanup"
)
Solo se envían los parámetros marcados como completables. Los valores fijos se aplican en la nube, y el acceso se resuelve ahí — tu asistente nunca pasa ninguno de los dos.
Límites y garantías
- Nada se crea en silencio.
proposedeja un borrador y devuelve una página de revisión; la creación real ocurre cuando haces clic. Una vez hecho, el borrador queda marcado y no se puede crear dos veces. - No se borra. No existe ningún verbo para eliminar una herramienta o una conexión por esta vía, con ningún permiso.
- Las ejecuciones tienen tope.
tools.usebloquea y tiene límite de tiempo, y no hay un proceso en segundo plano que termine lo que se pasó. El trabajo largo va en una automatización o una skill. - Los resultados se previsualizan, no se pegan. Los resultados grandes vuelven como un resumen más una referencia que tu asistente puede descargar — mira Qué vuelve.
- Un acceso vencido lo dice. Si vence a mitad de una ejecución, devuelve un estado
needs_authcon un enlace para reconectar, en vez de fallar en silencio. Tu asistente debe frenar y pasarte el enlace. - Las ediciones son completas, no parciales. Reenviar los parámetros de una herramienta reemplaza ese conjunto entero, así que tu asistente manda la forma completa y vuelve a leer la herramienta para confirmar.