Agentes
Hay dos formas de sacar trabajo de un colega. Puedes contratarlo — escribir la descripción del puesto, decidir a qué va a tener acceso y dejar que alguien lo apruebe. O puedes darle una consigna — pasarle una tarea, dejar que la haga y después leer lo que devolvió.
El área agents hace las dos cosas, y las mantiene bien separadas. Contratar pasa por una página de
revisión que aprueba una persona. Dar una consigna ejecuta de verdad el agente que ya tienes, del
lado de Nirvai.
Los verbos
| Verbo | Permiso | Qué hace |
|---|---|---|
agents.run | run | Le da la consigna al agente. Lo ejecuta en la nube de Nirvai y devuelve su respuesta más una conversación real que puedes abrir. |
agents.get_run | read | Lee esa conversación completa, mensaje por mensaje. |
agents.simulate | run | Solo referencia. Descarga la definición del agente para que tu asistente razone como él. No ejecuta nada por su cuenta. |
agents.describe_schema | — | La gramática para escribir un agente. Solo documentación; no cambia nada. |
agents.propose | create | Redacta uno o varios agentes en una página de revisión. No crea nada hasta que confirmas. |
agents.create | create | Crea el agente directamente, sin página de revisión. |
agents.edit | create | Cambia un agente que ya existe — fusionando, nunca sobrescribiendo. |
agents.attach_database | create | Le da al agente una tabla para leer o escribir. |
agents.attach_knowledge | create | Agrega documentos o páginas desde las que el agente puede responder. |
agents.attach_memory | create | Conecta una memoria de largo plazo. |
agents.attach_skill | create | Agrega una skill reutilizable que el agente puede ejecutar. |
Listar tus agentes es nirvai_list_resources(kind="agents"). Leer uno es
nirvai_describe(kind="agents", ref=<uuid>) — el manifiesto del agente: sus instrucciones, las
herramientas que puede llamar con la forma de sus argumentos, y las referencias a las tablas,
memorias, conocimiento y skills que tiene conectados. Todo lo demás arranca ahí, y los agentes se
direccionan por ese uuid, nunca por el nombre.
El manifiesto nombra lo que tiene un agente; no lo incluye. Los archivos de conocimiento, los scripts de las skills y las filas de las tablas se quedan donde están y se traen solo cuando algo realmente los necesita — así, leer un agente sigue siendo barato por mucho que sepa.
Dónde lo terminas tú
agents.propose te entrega un enlace a /external/agents/…, y esa página no es un formulario
simple. Es la vista real del constructor de agentes que ya conoces de Nirvai: tarjetas de
capacidades que puedes abrir una por una, y un botón bien visible de Crear agente.
- Tienes que estar conectado, y solo tú puedes abrir la página — un enlace de propuesta no se comparte. Una vez que hiciste clic, volver a abrirla muestra Creado ✓ y se niega a crear una segunda copia.
- Los canales no se configuran ahí. WhatsApp, Slack, Instagram y los demás se conectan al agente dentro de Nirvai después de que existe.
- Para cambiar algo, copia el bloque que te da la página y pégalo de vuelta en tu chat — la página no tiene forma de escribirle a tu asistente. Mira la referencia MCP.
agents.runno usa ninguna página de revisión. Devuelve un enlace a una conversación real que puedes abrir y seguir leyendo.
Ejecutar frente a simular
Se parecen y no son en absoluto lo mismo.
agents.run | agents.simulate | |
|---|---|---|
| Dónde piensa | En la nube de Nirvai, el ciclo real del agente | En tu asistente, localmente |
| Usa las herramientas y la memoria del agente | Sí, de verdad | Solo llamando de vuelta a Nirvai para cada paso concreto |
| Deja rastro | Una conversación real que puedes abrir | No ejecuta nada y no consume nada |
| Sirve para | Hacer el trabajo | Entender o ensayar cómo se comportaría el agente |
run bloquea, con un tope de unos dos minutos. Si el agente termina dentro de ese tope recibes
la respuesta y un id de conversación. Si no, recibes un estado running y el id de conversación
igual — para que get_run pueda leer lo que sí alcanzó a completarse. No hay ningún proceso en
segundo plano que termine lo que se pasó, así que conviene que cada consigna sea lo bastante chica
como para entrar.
simulate no ejecuta código propio. Le entrega a tu asistente la definición del agente y sus
referencias resueltas, y tu asistente hace el papel: adopta las instrucciones y, para cada paso
concreto — llamar una herramienta, leer una tabla, recuperar una memoria, correr el script de una
skill — vuelve a llamar a Nirvai. Es la forma honesta de responder "¿qué haría este agente?" sin
gastar una ejecución.
Ejemplos reales
Leer un agente, darle la consigna y leer la respuesta. El ciclo de todos los días:
# 1. ¿Qué es exactamente este agente? Nunca trabajes de memoria.
nirvai_describe(kind="agents", ref="a1b2-…")
# → instrucciones, herramientas llamables y sus argumentos, tablas conectadas, memoria, skills
# 2. Dale la consigna. Bloquea, con tope de ~2 minutos.
nirvai_execute(alias="agents.run",
args={ agent: "a1b2-…", prompt: "Summarize this week's leads and draft 3 follow-ups" },
description="Ask SalesBot for the weekly lead summary")
# → { status: "completed", answer: "…", conversation_uuid: "c9f3-…", session_url: "…" }
# 3. Lee la conversación completa — o la parcial, si se llegó al tope.
nirvai_execute(alias="agents.get_run",
args={ conversation: "c9f3-…", agent: "a1b2-…" },
description="Read back what SalesBot actually said")
Pasa el mismo conversation de vuelta a agents.run para continuar ese chat; omítelo para empezar
uno nuevo.
Cambiar un agente sin romperlo. Las ediciones se fusionan, así que esto suma en vez de reemplazar:
nirvai_execute(
alias = "agents.edit",
args = { agent: "a1b2-…",
instructions: "Always cite the source document when answering from the docs.",
tools: ["tools.hubspot_create_contact"] },
description = "Teach SalesBot to cite sources and give it the CRM tool"
)
La instrucción nueva se agrega a lo que ya había, y la herramienta se suma al conjunto existente. Para reemplazar cualquiera de las dos de verdad, tu asistente tiene que decirlo explícitamente.
Límites y garantías
- Las ediciones nunca borran en silencio. Las instrucciones se agregan, y los iniciadores y las herramientas se unen con lo que el agente ya tenía. El nombre, la descripción y el comportamiento se dejan tal cual si no se envían. Una edición reintentada no se aplica dos veces.
- Lo que se conecta es aditivo y repetible. Conectar una tabla, una memoria, una fuente de conocimiento o una skill que ya estaba se omite, no se duplica.
- Los canales no se conectan acá. Dónde vive un agente — WhatsApp, Slack, Telegram, Teams, chat web — se configura en la app de Nirvai después de que el agente existe, y no hay ningún verbo para eso. Mira Herramientas y conexiones.
- La creación la confirma una persona.
agents.proposedeja los borradores y devuelve una página de revisión que muestra exactamente qué herramientas, tablas, conocimiento y skills va a recibir el agente. Una vez que confirmas, el borrador queda marcado y no se puede crear dos veces. - No se borra. No existe ningún verbo para eliminar un agente por esta vía, con ningún permiso.
- Los resultados son acotados. Una ejecución devuelve su respuesta más enlaces; lo que sea grande vuelve como una referencia que tu asistente puede descargar — mira Qué vuelve.