nanobot: el framework ultra-ligero de agentes IA que puedes alojar tú mismo

Qué es nanobot

nanobot es un framework de agentes de inteligencia artificial escrito en Python, diseñado para ser ultra-ligero, auto-alojable y extensible. Lo desarrolla HKUDS, un laboratorio de investigación de la Universidad de Hong Kong, y en septiembre de 2026 acumula más de 47.000 estrellas en GitHub bajo licencia MIT.

La premisa es directa: un agente personal que puedes instalar con un solo comando, que funciona desde una WebUI integrada, desde la terminal o directamente desde tus apps de mensajería (Telegram, Discord, Slack, WeChat, Email, Mattermost). Sin infraestructura compleja, sin capas de abstracción innecesarias.

Lo que distingue a nanobot de otros frameworks es lo que decide no incluir, no lo que añade. Mientras la industria empuja hacia plataformas cada vez más pesadas, nanobot apuesta por un loop de agente minimalista donde el LLM decide qué herramientas necesita, la memoria se gestiona de forma inteligente y el desarrollador puede leer el código fuente completo en una tarde.

Repositorio oficial: github.com/HKUDS/nanobot

Por qué importa un framework ligero de agentes

Si has intentado construir un agente de IA en los últimos meses, probablemente hayas pasado por la misma progresión: empiezas con un script de 50 líneas, lo intentas con LangChain, te mudas a LangGraph para tener control de estado, consideras CrewAI para multi-agente, evalúas Dify para tener una interfaz visual, y al final tienes una pila de abstracciones donde ya no sabes exactamente qué hace cada capa.

No estoy criticando esos proyectos. Cada uno resuelve problemas reales. Pero existe una tensión fundamental: cuantas más abstracciones, más difícil es depurar, más frágil es el sistema y más dependes de la documentación del framework en lugar de entender tu propio código.

nanobot se posiciona en el otro extremo del espectro. Su apuesta es que la mayoría de casos de uso de agentes personales no necesitan una plataforma empresarial. Necesitan:

• Un loop donde el LLM recibe un mensaje, decide si necesita herramientas, las ejecuta y responde.
• Memoria que persista entre sesiones sin explotar el contexto.
• La capacidad de conectar herramientas externas (MCP) sin escribir wrappers.
• Una forma de desplegar el agente y que siga vivo sin supervisión.

En la práctica, esto se traduce en que nanobot no tiene un DSL propio para definir grafos, no tiene un builder visual, no necesita un servidor de base de datos separado (usa SQLite) y no requiere compilar un frontend (viene empaquetado en el wheel de Python). Es un agente que hace cosas, no una plataforma para gestionar agentes.

Arquitectura: el loop de agente minimalista

La arquitectura de nanobot se entiende en un solo diagrama. No hay capas ocultas ni servicios distribuidos. El flujo es lineal y predecible:

Lo más relevante de esta arquitectura es lo que no tiene: no hay un orquestador separado, no hay colas de mensajes, no hay un servicio de estado externo. Todo vive en un proceso Python con persistencia en SQLite. El gateway se encarga de mantener el proceso vivo en segundo plano.

Esto es una decisión de diseño deliberada. Para un agente personal o un equipo pequeño, esta simplicidad es una ventaja. Para un sistema empresarial con 200 agentes concurrentes, necesitarías algo más robusto. nanobot conoce su nicho y no intenta ser lo que no es.

Instalación: de pip install a agente funcionando en 2 minutos

La instalación de nanobot es probablemente lo más rápido que he visto en un framework de agentes. Hay tres formas, y las tres funcionan sin sorpresas.

Opción 1: pip (recomendada)

Opción 2: uv (más rápido)

Opción 3: instalador de una línea

Después de instalar, la configuración mínima es un archivo YAML donde defines tu proveedor de LLM y las herramientas que quieres habilitar. Con la configuración por defecto, nanobot arranca con GPT-4o (si tienes clave de OpenAI) y todas las herramientas integradas habilitadas.

llm:
  provider: openai
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}

tools:
  - files
  - shell
  - web_search
  - web_fetch
  - cron
  - image_gen

memory:
  dream: true

Para arrancar el agente en modo terminal:

Para arrancar con la WebUI:

Y ya. No hay paso de compilación de frontend, no hay Docker obligatorio, no hay migraciones de base de datos. El wheel de Python incluye todo lo necesario.

WebUI integrada: viene dentro del wheel

Una de las decisiones de diseño más inteligentes de nanobot es empaquetar la WebUI directamente dentro del paquete de Python. Cuando ejecutas nanobot serve, obtienes una interfaz web funcional sin necesidad de:

• Clonar un repositorio de frontend separado
• Instalar Node.js o Bun
• Ejecutar npm install y npm run build
• Configurar un proxy inverso entre frontend y backend

La WebUI se comunica con el agente vía WebSocket, lo que permite streaming de respuestas en tiempo real. La interfaz es limpia y funcional: conversaciones, historial de sesiones, visualización de tool calls y gestión de memoria.

Para desarrollo, si quieres modificar la interfaz, el frontend usa Bun y puedes compilarlo desde el código fuente. Pero para la gran mayoría de usuarios, la versión empaquetada es más que suficiente.

Este enfoque elimina una de las barreras más comunes en frameworks de agentes: la fricción del setup del frontend. En Dify, por ejemplo, necesitas levantar el frontend React con Node.js aparte del backend Python. En nanobot, un solo proceso Python sirve todo.

Herramientas disponibles

nanobot viene con un conjunto de herramientas integradas que cubren los casos de uso más comunes de un agente personal. Cada herramienta se habilita en la configuración y el LLM decide cuándo invocarla.

Lo que me gusta de este enfoque es que cada herramienta es un módulo independiente. No hay dependencias cruzadas. Si no necesitas generación de imágenes, no la habilitas y no carga código innecesario. Si necesitas una herramienta que no existe, puedes crear la tuya con el SDK de Python y registrarla en la configuración.

MCP: conectando herramientas externas

El soporte de MCP (Model Context Protocol) en nanobot es una de sus características más potentes. MCP se ha convertido en el estándar de facto para conectar herramientas externas a agentes de IA, y nanobot lo soporta de forma nativa.

¿Qué significa esto en la práctica? Que puedes conectar cualquier servidor MCP existente a tu agente de nanobot y usarlo como si fuera una herramienta integrada. Los servidores MCP disponibles incluyen:

• Bases de datos: PostgreSQL, Supabase, SQLite
• Servicios cloud: GitHub, Slack, Notion, Google Drive
• Herramientas de desarrollo: filesystem, Docker, terminales
• APIs especializadas: búsqueda, scraping, análisis de datos

La configuración es sencilla. Añades el servidor MCP a tu archivo de configuración:

mcp_servers:
  - name: github
    command: npx @modelcontextprotocol/server-github
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
  - name: filesystem
    command: npx @modelcontextprotocol/server-filesystem
    args:
      - /home/user/projects

Una vez configurado, el agente puede invocar las herramientas de esos servidores MCP como si fueran nativas. No necesitas escribir código wrapper ni adaptar interfaces. El protocolo MCP se encarga de la comunicación.

Esto convierte a nanobot en un hub donde convergen herramientas de distintos orígenes. Tu agente personal puede, en una sola conversación, leer un archivo local (tool nativa), crear un issue en GitHub (MCP) y enviarte un resumen por Telegram (integración de chat).

Dream: memoria a largo plazo

El sistema Dream es probablemente la innovación más interesante de nanobot, y la que más lo diferencia de otros frameworks ligeros.

El problema que resuelve es conocido: los agentes de IA pierden contexto entre sesiones. Puedes tener una conversación brillante con tu agente, cerrar la terminal y al día siguiente empieza desde cero. La solución obvia (guardar todo el historial y meterlo en el contexto) no escala porque el contexto del LLM tiene límites y el coste por tokens se dispara.

Dream funciona de forma diferente. En lugar de acumular contexto sin fin, consolida las interacciones en memorias comprimidas. El proceso:

1. Captura: durante las conversaciones, el sistema identifica información que vale la pena recordar: preferencias del usuario, decisiones, hechos relevantes, patrones de uso.
2. Consolidación: periódicamente (o al cerrar sesión), Dream procesa las interacciones recientes y las destila en memorias compactas. No guarda la conversación literal, sino la esencia.
3. Recuperación: cuando llega un nuevo mensaje, el sistema busca memorias relevantes por similitud semántica y las inyecta en el contexto. Solo las que son relevantes para la conversación actual.
4. Olvido inteligente: las memorias que no se acceden durante un período configurable pierden prioridad, evitando la acumulación indefinida.

Si vienes del mundo de agentes, reconocerás este patrón: es lo que la investigación llama "memory consolidation" o "memory compaction", similar conceptualmente al sistema de sueño humano donde el cerebro reorganiza y consolida lo aprendido durante el día. De ahí el nombre.

En la práctica, el resultado es un agente que "te conoce" sin necesitar gigabytes de historial. Le dices una vez que prefieres Python sobre JavaScript, que tu proyecto se despliega en Hetzner, que tu base de datos es PostgreSQL, y lo recuerda en sesiones futuras. Sin que tú tengas que repetirlo.

Multi-agente: delegación a subagentes

nanobot soporta multi-agente, pero con una filosofía muy diferente a CrewAI o AutoGen. No hay roles predefinidos, no hay "crew" ni "society of agents". Lo que hay es un mecanismo simple de delegación.

El agente principal puede crear subagentes especializados para tareas específicas. Cada subagente:

• Tiene su propio contexto y herramientas
• Puede usar un modelo de LLM diferente (un modelo barato para tareas simples, uno potente para las complejas)
• Devuelve su resultado al agente principal cuando termina
• No comparte memoria con otros subagentes (aislamiento deliberado)

Un ejemplo concreto: tu agente principal recibe la tarea "analiza los últimos commits del repositorio X y genera un resumen ejecutivo". Puede delegar la extracción de commits a un subagente con acceso a la herramienta de shell (git log), la categorización a otro subagente con un modelo barato, y quedarse con la síntesis final usando el modelo más capaz.

La clave es que esta delegación es transparente y trazable. El historial de sesión muestra exactamente qué subagente hizo qué, con qué herramientas y qué resultado devolvió. No hay magia negra ni decisiones ocultas.

¿Es esto suficiente para reemplazar un orquestador LangGraph complejo con estados, transiciones y paralelismo? No. Pero cubre el 80% de los casos donde simplemente quieres dividir una tarea grande en subtareas y ejecutarlas con diferentes modelos o herramientas.

Model routing y fallbacks

nanobot no te ata a un proveedor de LLM. Su sistema de model routing permite configurar múltiples modelos con fallbacks automáticos, lo que es fundamental para un agente que quieres que esté disponible 24/7.

La configuración es declarativa:

llm:
  primary:
    provider: openai
    model: gpt-4o
    api_key: ${OPENAI_API_KEY}
  fallbacks:
    - provider: ollama
      model: qwen2.5:32b
      base_url: http://localhost:11434
    - provider: deepseek
      model: deepseek-chat
      api_key: ${DEEPSEEK_API_KEY}

Si el modelo primario falla (rate limit, error 500, timeout), nanobot pasa automáticamente al siguiente en la lista. Esto es especialmente útil cuando combinas un modelo cloud (rápido pero con límites) con un modelo local (más lento pero sin restricciones).

Todos los proveedores deben ser compatibles con la API de OpenAI, que a estas alturas es un estándar de facto. Esto incluye:

• APIs comerciales: OpenAI, DeepSeek, Groq, Together, Fireworks
• Modelos locales: Ollama, vLLM, llama.cpp con servidor OpenAI
• Proxies: LiteLLM (para usar Claude, Gemini y otros via interfaz OpenAI)

Para quienes trabajamos con requisitos de soberanía de datos, esta flexibilidad es crítica. Puedes configurar tu agente para que use modelos locales (Qwen, Phi, Llama) en un servidor propio y que solo recurra a APIs externas como fallback con datos no sensibles.

Chat apps: Telegram, Discord, Slack como interfaz del agente

Una de las formas más naturales de interactuar con un agente IA es a través de las apps de mensajería que ya usas. nanobot incluye integraciones nativas con seis plataformas:

• Telegram: probablemente la integración más popular. Tu agente se convierte en un bot de Telegram al que puedes escribir desde el móvil.
• Discord: ideal para equipos o comunidades. El agente vive en un canal y responde a menciones o mensajes directos.
• Slack: integración para entornos corporativos. El agente puede vivir en un canal de equipo o responder via DM.
• WeChat: relevante para el mercado chino y para equipos distribuidos entre Asia y occidente.
• Email: el agente puede recibir y responder emails. Útil para automatizaciones asíncronas donde no necesitas respuesta inmediata.
• Mattermost: la alternativa open source a Slack. Coherente con la filosofía self-hosted de nanobot.

La arquitectura es elegante: cada integración de chat app es un "transport" que traduce mensajes de la plataforma al formato interno de nanobot y viceversa. El agent loop no sabe ni le importa si el mensaje vino de Telegram o de la terminal. Procesa lo mismo de la misma forma.

En la práctica, esto significa que puedes tener un agente con acceso a tus archivos, tus repositorios de GitHub (via MCP), tus automatizaciones cron, y controlarlo todo desde Telegram mientras estás en el autobús. No es ciencia ficción: es un bot de Telegram con esteroides.

Gateway persistente: el agente que no muere

Uno de los problemas prácticos de los agentes que corren en terminal es que mueren cuando cierras la terminal. El gateway de nanobot resuelve esto ejecutando el agente como un proceso en segundo plano que sobrevive al cierre de sesión.

El gateway mantiene:

• Las conexiones WebSocket con la WebUI y las chat apps
• Las tareas cron programadas
• El historial de sesiones activas
• La memoria Dream en SQLite

Cuando combinas el gateway con las tareas cron, obtienes un agente que actúa proactivamente. Puedes configurar tu agente para que, cada mañana a las 8:00, revise tus repositorios de GitHub, busque noticias relevantes sobre tus temas de interés y te envíe un resumen por Telegram. Todo sin que tú hagas nada.

Esto es lo que nanobot llama "long-horizon goals": objetivos que se extienden más allá de una sola conversación y que el agente persigue de forma autónoma en segundo plano. Es un agente que trabaja mientras tú duermes, no un agente que espera a que le hables.

API compatible con OpenAI

nanobot expone una API REST compatible con el formato de OpenAI (/v1/chat/completions), lo que significa que puedes integrarlo en cualquier aplicación o workflow que ya consuma la API de OpenAI. Simplemente cambias la URL base.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="nanobot"  # token local
)

response = client.chat.completions.create(
    model="nanobot",
    messages=[
        {"role": "user", "content": "Resume los PRs abiertos de mi repo"}
    ]
)
print(response.choices[0].message.content)

Esto abre posibilidades interesantes. Puedes usar nanobot como backend de:

• Aplicaciones web existentes que ya usan el SDK de OpenAI
• Scripts de automatización que necesitan un agente con herramientas
• Otros agentes que pueden invocar a nanobot como un sub-servicio
• Notebooks de Jupyter para análisis interactivo con herramientas

La diferencia con llamar directamente a la API de OpenAI es que detrás de la API de nanobot hay un agente completo con memoria, herramientas y MCP. No solo obtienes una respuesta del LLM: obtienes la respuesta de un agente que puede buscar en internet, leer archivos, ejecutar código y recordar conversaciones pasadas.

Despliegue: Docker, Linux service, Render one-click

nanobot ofrece varias opciones de despliegue para ir desde un prototipo local hasta un servicio en producción.

Docker

docker run -d \
  --name nanobot \
  -p 8080:8080 \
  -v ./config.yaml:/app/config.yaml \
  -v ./data:/app/data \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  hkuds/nanobot:latest

Docker Compose

Para despliegues más completos con volúmenes persistentes y variables de entorno gestionadas:

version: '3.8'
services:
  nanobot:
    image: hkuds/nanobot:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/app/config.yaml
      - nanobot-data:/app/data
    env_file: .env
    restart: unless-stopped

volumes:
  nanobot-data:

Linux systemd service

Para servidores Linux donde quieres que nanobot arranque automáticamente con el sistema:

[Unit]
Description=nanobot AI agent
After=network.target

[Service]
Type=simple
User=nanobot
ExecStart=/usr/local/bin/nanobot serve
Restart=always
EnvironmentFile=/etc/nanobot/env

[Install]
WantedBy=multi-user.target

macOS LaunchAgent

Para usuarios de macOS que quieren el agente corriendo como servicio del sistema, nanobot incluye un plist para launchd.

Render one-click

Para quienes no quieren gestionar infraestructura, nanobot ofrece despliegue con un clic en Render. Útil para probar el framework sin comprometerte con un servidor. Empieza gratis con los 3 primeros módulos.

En todos los casos, los datos (sesiones, memoria Dream, configuración) persisten en volúmenes o en el directorio data/. SQLite se encarga de todo sin necesidad de PostgreSQL, MySQL ni Redis.

Comparativa: nanobot vs Dify vs CrewAI vs LangGraph

Comparar frameworks de agentes es complicado porque cada uno tiene un enfoque diferente. Esta tabla intenta ser honesta sobre las fortalezas y limitaciones de cada opción.

La conclusión: ninguno es "mejor" que el otro, resuelven problemas diferentes:

• nanobot si quieres un agente personal rápido de desplegar, auto-alojado, con herramientas y memoria. Prioriza simplicidad y control.
• Dify si necesitas una plataforma visual para que personas no técnicas creen workflows con IA. Prioriza accesibilidad.
• CrewAI si tu problema requiere múltiples agentes con roles diferenciados trabajando en un proceso definido. Prioriza coordinación multi-agente.
• LangGraph si necesitas control granular sobre el flujo de ejecución con estados, transiciones y paralelismo. Prioriza robustez en producción.

¿Para quién es nanobot?

Después de analizar la arquitectura, las herramientas y las limitaciones, estos son los perfiles que más se benefician de nanobot:

Desarrolladores que quieren un asistente personal con esteroides. Si ya usas la terminal intensivamente y quieres un agente que recuerde tus proyectos, ejecute scripts, busque información y te la envíe por Telegram, nanobot es exactamente eso. Sin la complejidad de montar una plataforma.

Equipos pequeños que necesitan automatización inteligente. Un agente compartido que monitoriza repositorios, genera reportes diarios, responde preguntas en Slack y recuerda el contexto del equipo. Todo en un solo proceso que corre en un VPS de 10 euros al mes.

Quienes priorizan soberanía de datos. Si no puedes (o no quieres) enviar datos a APIs externas, nanobot con Ollama o vLLM local te da un agente completamente auto-alojado. Los datos nunca salen de tu infraestructura.

Makers y builders que prefieren entender su stack. Si eres de los que les gusta leer el código fuente de sus dependencias, nanobot tiene un core lo suficientemente pequeño para que lo entiendas completo. No hay magia. Cada decisión de diseño es trazable.

Quién debería mirar otro framework:

• Si necesitas orquestación empresarial con grafos de estado complejos: LangGraph.
• Si tu equipo no es técnico y necesita un builder visual: Dify o n8n con nodos de IA.
• Si tu caso de uso es multi-agente con 10 o más agentes coordinados: CrewAI o AutoGen.
• Si necesitas garantías de producción a escala empresarial con SLAs: necesitas una solución más madura.

Preguntas frecuentes

¿Qué es nanobot y para qué sirve?

nanobot es un framework open source ultra-ligero en Python para crear agentes de IA personales. Permite ejecutar un agente con herramientas (archivos, shell, web, MCP), memoria a largo plazo mediante el sistema Dream, automatizaciones programadas con cron y delegación multi-agente. Todo auto-alojado en tu propia infraestructura. Se instala con pip install nanobot-ai y en dos minutos tienes un agente funcional.

¿Es nanobot gratuito?

Si. nanobot es 100% open source bajo licencia MIT. Puedes usarlo, modificarlo y desplegarlo sin coste de licencia. El único coste variable es el del proveedor de LLM que uses. Si usas modelos locales con Ollama o vLLM, el coste de LLM es cero (solo hardware).

¿Qué modelos de lenguaje soporta nanobot?

Cualquier modelo compatible con la API de OpenAI. Esto incluye GPT-4o, GPT-4o-mini, modelos locales via Ollama (Qwen, Llama, Phi, Gemma), DeepSeek, Groq, Together, Fireworks, y Claude o Gemini via proxies como LiteLLM. El sistema de model routing permite configurar fallbacks automáticos entre proveedores.

¿Cómo se compara nanobot con LangGraph o CrewAI?

nanobot es significativamente más ligero y con un enfoque diferente. LangGraph está diseñado para flujos complejos con grafos de estado y transiciones explícitas. CrewAI modela equipos de agentes con roles y procesos. nanobot usa un loop de agente minimalista donde el LLM decide qué herramientas necesita por mensaje. Ideal para agentes personales, no para orquestación empresarial compleja.

¿Puedo usar nanobot desde Telegram o Discord?

Si. nanobot incluye integraciones nativas con Telegram, Discord, Slack, WeChat, Email y Mattermost. Configuras las credenciales del bot en tu archivo YAML, arrancas el gateway, y tu agente responde directamente desde la plataforma de mensajería.

¿Qué es el sistema Dream de nanobot?

Dream es el sistema de memoria a largo plazo. En lugar de acumular todo el historial en el contexto (costoso e ineficiente), Dream consolida las interacciones en memorias compactas que el agente recupera por relevancia semántica. Funciona de forma similar a como el cerebro humano consolida recuerdos durante el sueño: captura, compresión, recuperación selectiva y olvido inteligente.

¿Necesito experiencia en programación para usar nanobot?

Se necesita conocimiento básico de terminal y Python. La instalación es un solo comando y la configuración inicial es un archivo YAML. Para personalización avanzada (crear herramientas propias, modificar el comportamiento del agente, integrar APIs), si se requiere programación en Python. La WebUI integrada reduce la barrera de uso para interacciones del día a día.

¿Puedo conectar herramientas externas vía MCP?

Si. nanobot soporta MCP (Model Context Protocol) de forma nativa. Cualquier servidor MCP existente (GitHub, filesystem, bases de datos, Slack, Notion) se puede conectar añadiendo unas líneas a la configuración YAML. El agente puede invocar las herramientas MCP como si fueran nativas, sin escribir código wrapper.

Conclusiones

nanobot representa una corriente necesaria en el ecosistema de agentes de IA: la simplificación radical. En un momento donde cada semana aparece un nuevo framework con más capas de abstracción, más servicios dependientes y más complejidad, nanobot demuestra que un agente funcional y potente puede vivir en un solo proceso de Python con SQLite.

Las 47.000 estrellas en GitHub no son casualidad. Responden a una demanda real de desarrolladores que quieren agentes que puedan entender, modificar y desplegar sin convertirse en expertos en orquestación distribuida. La combinación de herramientas integradas, MCP, memoria Dream, multi-agente y chat apps cubre un rango sorprendente de casos de uso con una fracción de la complejidad de alternativas más pesadas.

Si me preguntas cuál es la tesis de fondo: el mejor agente es el que entiendes completamente. Cuando algo falla (y algo siempre falla), la diferencia entre depurar un loop de 200 líneas y depurar un orquestador distribuido con colas, workers y base de datos de estado es la diferencia entre 5 minutos y 5 horas. nanobot apuesta por los 5 minutos.

Eso no lo hace la solución correcta para todos los problemas. Pero para el desarrollador individual, el equipo pequeño o quien simplemente quiere un agente personal que le haga la vida más fácil sin pedirle un doctorado en infraestructura, nanobot es una de las mejores opciones disponibles hoy.

Mi recomendación: instálalo, configura Telegram como interfaz, habilita Dream y el cron, y dale una semana. Si después de una semana no te imaginas volver a trabajar sin él, habrás encontrado tu framework de agentes.