# 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**.

![Imagen que describe la arquitectura de nanobot](https://cdn.hashnode.com/uploads/covers/60e4a9cde9aeb8301a6a6d39/07025eaa-3509-469f-b805-b81f484ce554.png align="center")

## 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.
    

![Diagrama de secuencia](https://cdn.hashnode.com/uploads/covers/60e4a9cde9aeb8301a6a6d39/5214a339-e8c9-4da5-afd7-389ab0bd363d.svg align="center")

### 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.
    

![Diagrama de estado](https://cdn.hashnode.com/uploads/covers/60e4a9cde9aeb8301a6a6d39/371b4d75-b576-4652-9154-58f566628bd9.svg align="center")

## 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](https://github.com/HKUDS/nanobot)

[Documentación técnica nanobot](https://www.mintlify.com/HKUDS/nanobot/introduction)

[Documentación femtobot](https://rafnixg.github.io/femtobot/femtobot.html)