Saltar al contenido principal

Agentes

Agentes de IA — Referencia Técnica

Una mirada técnica a cómo los agentes de Nirvai razonan, ejecutan herramientas, gestionan memoria y conocimiento, ejecutan habilidades y operan en distintos canales.

Esta página describe cómo funcionan los agentes de Nirvai por debajo de la interfaz de chat, en términos técnicos, para desarrolladores y usuarios con perfil técnico. Se centra en el comportamiento observable y en el modelo que siguen los agentes, no en detalles de implementación.

Modelo de arquitectura​

Un agente es una configuración sobre un entorno de ejecución compartido: su identidad e instrucciones, las herramientas que puede llamar, sus proyectos conectados, sus habilidades y las tablas de base de datos conectadas.

  • Los agentes son streaming-first — la salida se envía al cliente a medida que se produce, token por token.
  • Cada conversación se ejecuta en una sesión aislada con su propio directorio de trabajo, memoria y entorno de ejecución de código. Las sesiones nunca comparten estado.

Cómo actúa un agente — el bucle de ejecución​

Un agente no elige una sola función y se detiene. Razona y luego actúa ejecutando un programa corto que llama a sus herramientas, observa el resultado y repite hasta terminar la tarea. (Este enfoque de ejecución de código a veces se llama CodeAct.)

  • Cada turno ejecuta un número acotado de pasos (un límite de seguridad) antes de detenerse.
  • El entorno de código se reinicia en cada turno — nada de lo que quede en variables del programa persiste entre turnos. Llevar información hacia adelante se hace a través del estado de sesión (más abajo).
  • Ejecutar código, en lugar de una sola llamada a función por vez, permite encadenar varias llamadas a herramientas, usar bucles y condicionales y procesar datos dentro de un mismo paso.

Herramientas​

Las herramientas se presentan al agente como funciones invocables. Vienen en varias categorías:

CategoríaQué es
NativasCapacidades integradas: búsqueda web, lectura de documentos, visión/generación de imágenes, almacenamiento de archivos, fechas
PersonalizadasIntegraciones creadas por el usuario con APIs REST de terceros
De conectorIntegraciones prediseñadas (calendario, correo, hojas de cálculo, apps de chat y más)
De base de datosAcciones por tabla sobre las tablas conectadas (limitadas por permiso)
De proyectosRecordar, buscar y registrar hechos y documentos en los proyectos conectados del agente (búsqueda en grafo)
De conocimiento (heredado)Buscar y leer los archivos de conocimiento de agentes creados antes de Proyectos
De habilidadProcesos reutilizables que el agente carga y ejecuta (ver abajo)
De canalAcciones de envío específicas del canal donde corre el agente
  • Niveles de salida de herramientas: los resultados pequeños se devuelven en línea; los grandes se resumen en una tarjeta de datos compacta (forma + muestra) y se exponen como variable; los muy grandes además se guardan en un archivo. Así las salidas grandes no desbordan el contexto de trabajo.
  • Sin tope de herramientas: un agente puede tener cualquier cantidad de herramientas personalizadas y de base de datos. Las herramientas de base de datos son genéricas y se comparten entre todas las tablas conectadas (el agente apunta a una tabla por referencia), así que su costo es la unión de las operaciones habilitadas — como máximo 6 — no la suma por tabla: lectura aporta 1, escritura 5, completa 6. Cada herramienta personalizada cuenta como 1.

Estado de sesión​

Distinto de los Proyectos, que persisten entre conversaciones y se comparten entre agentes. El estado de sesión es espacio de trabajo acotado a una conversación y se descarta con ella.

Como el entorno de código se reinicia en cada turno, el estado de sesión es la única forma de llevar información hacia adelante dentro de una conversación. Tiene tres ranuras tipadas, todas mostradas al agente al inicio de cada turno:

RanuraQué guarda
planEl plan de la sesión — objetivo, enfoque y progreso
contextUna lista de lectura — rutas de archivos a releer el próximo turno (no contenido en caché)
stateVariables del flujo — IDs, nombres, elecciones, el paso actual
  • Cada ranura guarda un solo valor que se sobrescribe al actualizar.
  • El historial de conversación se mantiene en una ventana reciente; los turnos más antiguos se descartan.
  • El estado de sesión es para notas compactas — no para datos grandes ni contenido de archivos, que se vuelven a obtener cada turno.
  • Todo lo que deba sobrevivir a la conversación va en un proyecto, no aquí.

Conocimiento​

  • El conocimiento (archivos y URLs) se procesa al momento de crear el agente: se extrae el texto, se resume y se le asignan palabras clave, y se guarda un índice.
  • En tiempo de ejecución el agente busca en ese índice por palabra clave y lee las fuentes que coinciden, según haga falta.
  • Los agentes simples usan búsqueda por palabra clave; los de conocimiento profundo usan una búsqueda basada en grafos para una recuperación más conectada.
  • El conocimiento es para recuperación — material que el agente busca al responder. La documentación de procesos paso a paso que el agente debe seguir va en una habilidad.

Habilidades​

Una habilidad es una carpeta: un documento de interfaz SKILL.md más, opcionalmente, scripts de Python, documentos de referencia y archivos de datos.

  • Las habilidades se cargan bajo demanda y se ejecutan dentro del mismo entorno de código; SKILL.md documenta exactamente cómo usarlos.
  • Los scripts usan librerías preinstaladas (sin instalaciones en tiempo de ejecución), devuelven resultados serializables en JSON y guardan archivos con rutas relativas.
  • Las habilidades vienen de tres lugares: habilidades integradas de la plataforma, plantillas oficiales de la comunidad que puedes instalar, y habilidades que creas tú mismo.

Canales y plataformas​

La misma lógica del agente corre en la app web y en canales externos (WhatsApp, Instagram, Messenger, Telegram, Slack, Discord, Teams). Las reglas de salida y las acciones de envío específicas de cada canal se intercambian por canal.

En los canales externos, la interfaz no puede bloquear la entrada mientras el agente trabaja. Para no corromper una conversación, la ejecución se serializa por sesión: un mensaje corre a la vez, y los mensajes que llegan durante una ejecución se encolan y se procesan cuando termina la ejecución en curso.

Tipos de agente​

  • Todos los agentes nuevos usan el mismo tipo; lo que pueden hacer depende solo de lo que conectes (herramientas, proyectos, bases de datos, habilidades, capacidades nativas). Los agentes antiguos con archivos de conocimiento los conservan, en solo lectura.
  • Un agente es Borrador hasta que tiene un perfil e instrucciones; entonces pasa a Listo. Los agentes propuestos por MCP siguen en Borrador hasta que el propietario los acepta.
  • El entorno de ejecución también impulsa variantes internas especializadas (asistentes de investigación, de flujos de trabajo, de documentos y más), pero esas no forman parte del flujo de creación estándar.

Límites y garantías​

  • Cada turno está limitado a un número acotado de pasos.
  • La salida de herramienta demasiado grande se recorta a una vista previa y se guarda en un archivo que el agente puede abrir.
  • Cada conversación está aislada — un canal nunca ve la sesión de otro canal.
  • El uso se mide como créditos por ejecución.

Qué sigue​