Saltar al contenido principal

Agentes de IA — Referencia Técnica

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, su base de conocimiento, sus skills 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 de la memoria (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 conocimientoBuscar y leer en la base de conocimiento del agente
De skillProcesos 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.
  • Límite compartido de 25 herramientas: las herramientas personalizadas y las de base de datos de un agente comparten un único presupuesto de 25. Una conexión de base de datos de lectura cuenta como 2 herramientas, de escritura como 5, completa como 7; cada herramienta personalizada cuenta como 1.

Memoria​

Como el entorno de código se reinicia en cada turno, la memoria persistente es la única forma de llevar información hacia adelante. 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.
  • La memoria es para notas compactas — no para datos grandes ni contenido de archivos, que se vuelven a obtener cada turno.

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 un skill.

Skills​

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

  • Los skills 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.
  • Los skills vienen de tres lugares: skills integrados de la plataforma, plantillas oficiales de la comunidad que puedes instalar, y skills 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​

  • Los agentes nuevos se crean como uno de dos tipos: Simple (instrucciones + conocimiento general) o Simple con Conocimiento (agrega una base de conocimiento que se puede buscar). El tipo se establece automáticamente según si agregas conocimiento.
  • 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​