Nanobot: Arquitectura y Funcionamiento del Agente IA Ultra-ligero

Introducción

nanobot es una plataforma de asistente personal de IA diseñada para ejecutarse en tu propia infraestructura, ya sea una laptop, un servidor pequeño o un contenedor en la nube (VPS). A diferencia de otros frameworks que se centran únicamente en el "prompt engineering", nanobot siguiendo la filosofía de OpenClaw, trata al agente de IA como un problema de infraestructura, construyendo un entorno de ejecución estructurado que gestiona sesiones, memoria, sandboxing de herramientas y enrutamiento de mensajes. Los LLM solo proveen inteligencia y razonamiento, nanobot prepara el terreno para que el agente pueda tomar control del sistema donde es instalado y ejecutar las herramientas.

Inspirado en OpenClaw, su propuesta radical es ofrecer funcionalidad completa de agente con un 99% menos de líneas de código. Mientras que los frameworks tradicionales suelen ser "cajas negras" complejas, nanobot mantiene un núcleo de aproximadamente 4,000 líneas, facilitando que desarrolladores e investigadores entiendan, modifiquen y extiendan el sistema.

Como Funciona nanobot: Visión general

Nanobot no es solo una interfaz para un API de modelos de lenguaje o un chatbot conectado a un LLM, es un entorno de ejecución que sigue una arquitectura limpia orientado a eventos. El sistema actúa como un puente entre múltiples interfaces de entrada (Telegram, Discord, Slack, etc.) y un núcleo de inteligencia centralizado.

El corazón del sistema es el Message Bus, que actúa como plano de control, desacoplando la capa de comunicación de la lógica del agente. Esto permite que una única instancia del agente sea accesible simultáneamente a través de diversos canales, manteniendo la coherencia del estado de la conversación y el acceso a herramientas en hardware local.

Componentes principales

1. Canales

Cada plataforma de mensajería utiliza un adaptador dedicado que implementa la clase BaseChannel. Estos adaptadores normalizan la entrada y salida de datos:

• Autenticación y Conexión: Utiliza diversos métodos según la plataforma, como polling para Telegram, WebSockets para Discord y Feishu, o un bridge de Node.js para WhatsApp.

• Normalización: Los canales extraen texto y manejan archivos multimedia (imágenes, voz) para convertirlos en un objeto estándar de entrada InboundMessage.

• Control de Acceso: Implementan listas de permitidos allowFrom para restringir quién puede interactuar con el bot a nivel de plataforma.

2. Interfaz de Control

Nanobot ofrece múltiples formas de interacción:

• CLI (Línea de Comandos): Es la interfaz principal para la administración. Permite iniciar el asistente en modo interactivo nanobot agent, gestionar configuraciones onboard y autenticar canales channels login.

• Modo Gateway: Permite que el sistema funcione en segundo plano conectando todos los canales de chat configurados simultáneamente.

3. Gateway

El Gateway es el punto central que coordina el estado del sistema. Sus responsabilidades incluyen:

• Gestión de Conexiones: Inicia y mantiene los hilos o tareas asíncronas para cada canal de chat activo.

• Servicios Proactivos: Aloja el servicio de Cron para tareas programadas y el sistema de Heartbeat, que despierta al agente cada 30 minutos para ejecutar tareas autónomas definidas en el archivo HEARTBEAT.md.

4. Entorno de Ejecución del Agente (Agent Runtime)

Representado por la clase AgentLoop, es donde ocurre el procesamiento de la IA. El runtime sigue un ciclo de cuatro pasos:

1. Resolución de Sesión: Identifica el historial de conversación específico para cada usuario o hilo de chat.

2. Construcción de Contexto: Ensambla el prompt del sistema combinando la identidad del agente, las habilidades skills, la memoria persistente y el historial de la sesión.

3. Invocación del Modelo: Interactúa con proveedores (OpenAI, Anthropic, Ollama, etc.) mediante una capa de abstracción que normaliza las APIs.

4. Ejecución de Herramientas: Intercepta las solicitudes de llamadas a herramientas del LLM para ejecutar comandos de sistema, búsquedas web o manipulación de archivos.

Iteración y Coordinación

La arquitectura de nanobot permite una coordinación fluida entre componentes:

• Message Bus: Utiliza colas asíncronas para mensajes entrantes y salientes, asegurando que el sistema sea responsivo incluso durante procesos intensivos del LLM.

• Sistema de Habilidades (Skills): Permite inyectar capacidades específicas (como gestión de GitHub o clima) mediante archivos Markdown en la capeta ~/.nanobot/skills/, que el agente carga dinámicamente según la necesidad.

• Herramientas Externas (MCP): Soporta el Model Context Protocol, lo que permite conectar servidores de herramientas externas y usarlos como si fueran capacidades nativas.

Flujo de mensaje de extremo a extremo

El flujo de un mensaje desde que el usuario lo envía hasta que recibe la respuesta sigue estos pasos técnicos:

• Ingesta: El ChannelLayer recibe el input y publica un InboundMessage en el bus. Un ejemplo podría ser recibir un mensaje de Telegram.

• Carga de Sesión: El AgentLoop extrae el mensaje y recupera el historial desde el SessionManager, ubicado en ~/.nanobot/sessions/ .

• Ensamblaje: El ContextBuilder construye el prompt del sistema incluyendo contexto, la memoria usando como base el MEMORY.md y herramientas.

• Bucle de Iteración:

  • Llama al LLM a través de un Provider (OpenRouter, Anthropic, OpenAI, etc.).

  • Si el modelo solicita herramientas (shell, filesystem, web, etc.), estas se ejecutan y los resultados se reinyecta en el contexto.

• Finalización: Una vez generada la respuesta de texto, se publica un OutboundMessage en el bus y el canal lo entrega al usuario.

Gestión de datos y estado

Nanobot almacena su estado de forma sencilla y transparente ~/.nanobot:

• Configuración: Un único archivo ~/.nanobot/config.json centraliza las claves de API y ajustes de canales.

• Memoria a largo plazo: Utiliza un archivo MEMORY.md en formato Markdown dentro del workspace. Esto permite que la memoria sea legible para humanos y fácil de editar manualmente.

• Historial de Sesión: Almacenado en archivos JSON individuales por usuario, permitiendo persistencia total entre reinicios.

Arquitectura de Seguridad

La seguridad se implementa en múltiples capas:

• Aislamiento del Workspace: Si se activa restrictToWorkspace, todas las operaciones de archivos y comandos de shell se confinan estrictamente al directorio ~/.nanobot/workspace/, bloqueando ataques de salto de directorio (path traversal).

• Control de Acceso: Las listas de permitidos allowFrom aseguran que solo usuarios autorizados puedan interactuar con el agente.

• Gestión de Claves: Las API keys se cargan como variables de entorno por solicitud y nunca se registran en los logs del sistema. Además las claves se almacenan con permisos restringidos (600).

Arquitecturas de despliegue

Nanobot soporta tres patrones principales:

1. Local/CLI: Ejecución directa mediante el binario para pruebas rápidas y desarrollo de herramientas simples o scripts.

2. Servicio de Linux (Systemd): Permite que el gateway se ejecute permanentemente en segundo plano, reiniciándose automáticamente tras fallos o reinicios del servidor y manteniendo el contexto por sesión.

3. Contenedor de Docker: Ideal para despliegues aislados, persistiendo la configuración y el workspace mediante volúmenes montados.

Conclusión

Nanobot demuestra que es posible construir una infraestructura de IA potente bajo una filosofía de simplicidad radical que hacen que su código no solo sea eficiente sino legible. Al separar las interfaces del runtime y mantener una base de código plana y modular, ofrece un sistema que es a la vez una herramienta de productividad diaria y una plataforma ideal para la investigación con agentes de IA.

Es, en esencia, la arquitectura mínima necesaria para un asistente que no solo responde, sino que actúa. No tiene el nivel de complejidad y funcionalidades que posee OpenClaw pero tampoco lo necesita, cumple con los objetivos que buscas en algo más que un agente, si OpenClaw se define como un sistema operativo para los Agentes, nanobot entonces sería un mini sistema operativo para agentes.

Ejemplo de implementación de la arquitectura

femtobot es un agente creado para demostrar una pequeña implementación de la arquitectura bajo la cual nanobot funciona, es una buena base de inspiración y estudio para este tipo de sistema de agentes.

https://github.com/rafnixg/femtobot

Referencias

Github oficial nanobot

Documentación técnica nanobot

Documentación femtobot