Capitulo 0: Introduccion

Bienvenida

Bienvenido a "Construyendo un Agente Autonomo de IA desde Cero". A lo largo de este libro vas a construir, linea por linea, un sistema completo de agente autonomo de inteligencia artificial. No vamos a usar ningun framework magico ni una libreria monolitica que esconda la complejidad: vas a entender cada decision, cada abstraccion y cada linea de codigo.

El resultado final sera nanobot, un framework ultra-ligero de agente autonomo escrito en Python. Con aproximadamente 4,000 lineas de codigo central, nanobot es capaz de:

• Mantener conversaciones con usuarios a traves de multiples canales (Telegram, Discord, Slack, WhatsApp, email y mas).
• Usar herramientas para leer y escribir archivos, ejecutar comandos de shell, buscar en la web y mucho mas.
• Recordar informacion entre sesiones usando un sistema de memoria persistente.
• Ejecutar tareas programadas de forma autonoma, incluso cuando nadie esta hablando con el.
• Delegar trabajo a sub-agentes que operan en segundo plano.
• Extender sus capacidades mediante un sistema de habilidades basado en archivos Markdown.
• Integrarse con servidores MCP (Model Context Protocol) para acceder a herramientas externas.

Lo mas importante: vas a construir todo esto de forma incremental. Cada capitulo agrega un componente nuevo sobre los anteriores, y al final tendras un sistema completo y funcional que puedes personalizar, extender y desplegar.

---

Que es nanobot

nanobot es un framework de agente autonomo de IA ultra-ligero, escrito en Python puro. Esta inspirado en los agentes de codigo mas grandes del mercado (como Claude Code, que tiene mas de 400,000 lineas de codigo), pero logra entregar la funcionalidad central en solo ~4,000 lineas.

Esto no es un juguete. nanobot puede:

• Actuar como un asistente personal conectado a tus chats favoritos.
• Escribir y ejecutar codigo.
• Buscar informacion en la web.
• Gestionar archivos y proyectos.
• Ejecutar tareas recurrentes de forma autonoma.
• Delegar tareas complejas a sub-agentes especializados.

La filosofia detras de nanobot es clara: codigo legible, arquitectura limpia y minima complejidad. Cada modulo tiene una responsabilidad bien definida, y el flujo de datos es facil de seguir.

---

Arquitectura General

Antes de escribir una sola linea de codigo, veamos el mapa completo del sistema que vamos a construir. Este diagrama muestra todos los componentes y como se conectan entre si:

                         +---------------------+
                         |   CLI / Channels    |
                         | (Telegram, Discord, |
                         |  Slack, WhatsApp,   |
                         |  Email, Feishu...)  |
                         +----------+----------+
                                    |
                                    | InboundMessage / OutboundMessage
                                    v
                         +----------+----------+
                         |    Message Bus      |
                         |  (async queues)     |
                         +----------+----------+
                                    |
                                    v
+-------------------+   +----------+----------+   +-------------------+
|  Context Builder  |-->|     Agent Loop       |<--| Session Manager   |
| (system prompt    |   | (think-act-observe)  |   | (JSONL persist.)  |
|  assembly)        |   +----+-----+-----+----+   +-------------------+
+-------------------+        |     |     |
                             |     |     |
              +--------------+     |     +--------------+
              |                    |                    |
              v                    v                    v
   +----------+------+  +---------+--------+  +--------+---------+
   |  LLM Provider   |  |  Tool Registry   |  | Subagent Manager |
   | (Anthropic,     |  | (read_file,      |  | (background      |
   |  OpenAI,        |  |  write_file,     |  |  workers)        |
   |  DeepSeek,      |  |  exec, web_      |  +------------------+
   |  OpenRouter...) |  |  search, cron..) |
   +-----------------+  +------------------+
                             |
              +--------------+--------------+
              |              |              |
              v              v              v
   +----------+--+  +-------+------+  +----+-----------+
   | Memory Store|  | Skills System|  | MCP Integration|
   | (MEMORY.md +|  | (markdown-   |  | (Model Context |
   |  HISTORY.md)|  |  based caps) |  |  Protocol)     |
   +-------------+  +--------------+  +----------------+

   +---------------------------------------------------+
   |        Cron Service + Heartbeat                    |
   |  (autonomous scheduled execution every 30 min)    |
   +---------------------------------------------------+

Veamos brevemente que hace cada componente:

CLI / Channels: El punto de entrada. Los usuarios interactuan con nanobot a traves de la linea de comandos o de plataformas de mensajeria. Cada canal traduce los mensajes de su formato nativo a un formato comun (InboundMessage) y envia las respuestas del agente de vuelta al usuario (OutboundMessage).

Message Bus: Un sistema de colas asincronas que desacopla los canales del nucleo del agente. Los canales publican mensajes entrantes, el agente los consume, los procesa, y publica respuestas que los canales recogen.

Agent Loop: El corazon del sistema. Implementa el ciclo clasico de un agente autonomo: pensar (consultar al LLM), actuar (ejecutar herramientas si el LLM lo solicita), y observar (enviar los resultados de las herramientas de vuelta al LLM). Este ciclo se repite hasta que el LLM produce una respuesta final sin llamadas a herramientas.

LLM Provider: Una abstraccion sobre multiples proveedores de modelos de lenguaje. Gracias a la libreria litellm, nanobot puede hablar con Anthropic (Claude), OpenAI (GPT), DeepSeek, Google (Gemini), y docenas de proveedores mas usando una interfaz unificada.

Tool Registry: Un registro dinamico de herramientas que el agente puede usar. Cada herramienta tiene un nombre, una descripcion, un esquema de parametros (JSON Schema) y un metodo execute. El registro las expone al LLM en formato OpenAI function-calling.

Context Builder: Se encarga de ensamblar el prompt del sistema. Combina la identidad del agente, archivos de configuracion del workspace, la memoria de largo plazo, las habilidades activas y un resumen de habilidades disponibles en un unico system prompt coherente.

Session Manager: Gestiona las sesiones de conversacion. Cada sesion almacena el historial de mensajes en formato JSONL (un objeto JSON por linea), lo que permite persistencia eficiente y facil inspeccion.

Memory Store: El sistema de memoria persistente del agente, dividido en dos capas. MEMORY.md almacena hechos de largo plazo (el LLM los ve en cada turno). HISTORY.md es un log de eventos buscable con grep, ideal para recordar detalles de conversaciones pasadas.

Skills System: Un sistema de habilidades extensibles basado en archivos Markdown. Cada habilidad es un directorio con un archivo SKILL.md que describe al agente como realizar una tarea especifica. Las habilidades se cargan progresivamente: primero un resumen, y el agente lee el contenido completo bajo demanda.

Cron Service + Heartbeat: Los componentes que hacen a nanobot autonomo. El servicio Cron permite programar tareas con expresiones cron o intervalos. El Heartbeat despierta al agente cada 30 minutos para revisar un archivo de tareas pendientes y ejecutarlas proactivamente.

Subagent Manager: Permite al agente principal delegar tareas a sub-agentes que corren en segundo plano. Cada sub-agente tiene su propio conjunto de herramientas y contexto aislado, pero comparte el mismo proveedor LLM.

MCP Integration: Soporte para el Model Context Protocol, un estandar abierto para conectar herramientas externas. nanobot puede comunicarse con servidores MCP tanto locales (via stdio) como remotos (via HTTP).

---

Prerrequisitos

Para seguir este libro necesitas:

1. Python 3.11 o superior. Usamos caracteristicas modernas del lenguaje como type hints con X | None, match statements, y asyncio con sintaxis moderna. Puedes verificar tu version con:

python3 --version
# Python 3.11.x o superior

2. Una API key de un proveedor de LLM. Necesitas acceso a al menos un modelo de lenguaje. Las opciones mas comunes son:

   • OpenRouter (recomendado para empezar, da acceso a todos los modelos): openrouter.ai/keys
   • Anthropic (Claude directo): console.anthropic.com
   • OpenAI (GPT directo): platform.openai.com
   • DeepSeek (muy economico): platform.deepseek.com

3. Conocimiento basico de Python. Deberias estar comodo con clases, funciones async/await, decoradores, y manejo basico de archivos. No necesitas ser un experto, pero si un principiante absoluto, te recomiendo completar un tutorial de Python antes.

4. Familiaridad basica con la terminal. Vamos a ejecutar comandos, configurar variables de entorno y navegar directorios.

---

Configuracion del Entorno

Vamos a preparar el entorno de desarrollo. Empezamos creando el directorio del proyecto y un entorno virtual:

# Crear el directorio del proyecto
mkdir nanobot
cd nanobot

# Crear un entorno virtual
python3 -m venv .venv
source .venv/bin/activate  # En Windows: .venv\Scripts\activate

# Instalar las dependencias base
pip install litellm pydantic pydantic-settings

Estas tres dependencias son la base sobre la que construiremos todo:

• litellm: Interfaz unificada para mas de 100 proveedores de LLM. Nos permite cambiar entre Anthropic, OpenAI, DeepSeek y muchos otros sin cambiar nuestro codigo.
• pydantic: Validacion de datos y esquemas con type hints de Python. Lo usaremos para definir la configuracion del sistema y validar parametros de herramientas.
• pydantic-settings: Extension de Pydantic para cargar configuracion desde archivos JSON y variables de entorno.

Tambien necesitaras crear la estructura basica de directorios:

mkdir -p nanobot
touch nanobot/__init__.py
touch nanobot/main.py

---

Mapa de Capitulos

Este libro esta organizado en 18 capitulos que construyen el sistema de forma incremental. Aqui tienes un resumen de cada uno:

Capitulo 0 -- Introduccion (este capitulo) Vision general del proyecto, arquitectura, prerrequisitos y configuracion del entorno.

Capitulo 1 -- Primera Llamada al LLM Hacemos nuestra primera llamada a un modelo de lenguaje usando litellm. Construimos un chatbot minimo de 30 lineas que puede mantener una conversacion basica.

Capitulo 2 -- Abstraccion del Proveedor LLM Creamos la interfaz LLMProvider y la implementacion LiteLLMProvider. Separamos la logica del proveedor del resto del sistema para poder cambiar de modelo sin tocar el codigo del agente.

Capitulo 3 -- El Registro de Herramientas Definimos la clase base Tool y construimos el ToolRegistry. Implementamos nuestra primera herramienta: exec para ejecutar comandos de shell.

Capitulo 4 -- Herramientas de Archivos Implementamos las herramientas del sistema de archivos: read_file, write_file, edit_file y list_dir. El agente ahora puede leer, escribir y navegar el disco.

Capitulo 5 -- El Bucle del Agente Construimos el AgentLoop, el corazon del sistema. Implementamos el ciclo pensar-actuar-observar que permite al LLM usar herramientas de forma iterativa hasta resolver una tarea.

Capitulo 6 -- El Message Bus Creamos el bus de mensajes asincrono que desacopla los canales de comunicacion del nucleo del agente. Definimos los eventos InboundMessage y OutboundMessage.

Capitulo 7 -- Gestion de Sesiones Implementamos el SessionManager con persistencia en formato JSONL. Cada conversacion ahora se guarda en disco y se puede retomar.

Capitulo 8 -- El Context Builder Construimos el ensamblador de prompts del sistema. Integramos los archivos de bootstrap, la memoria y las habilidades en un system prompt coherente.

Capitulo 9 -- Sistema de Memoria Implementamos el MemoryStore con sus dos capas: MEMORY.md para hechos de largo plazo y HISTORY.md para un log de eventos buscable. Incluimos la consolidacion automatica via LLM.

Capitulo 10 -- Herramientas Web Agregamos web_search (busqueda con la API de Brave) y web_fetch (descarga y extraccion de texto de paginas web). El agente ahora puede buscar informacion en internet.

Capitulo 11 -- El Sistema de Habilidades Creamos el SkillsLoader y el formato de habilidades basado en Markdown. Las habilidades ensenan al agente nuevas capacidades sin modificar el codigo.

Capitulo 12 -- Configuracion con Pydantic Definimos el esquema completo de configuracion usando Pydantic: proveedores, canales, herramientas, agente. Todo se carga desde un archivo JSON con soporte para variables de entorno.

Capitulo 13 -- La Interfaz CLI Construimos la interfaz de linea de comandos: onboard, agent, gateway, status. La primera forma real de interactuar con nanobot.

Capitulo 14 -- Canales de Comunicacion Implementamos la clase base Channel y el primer canal concreto: Telegram. Vemos como traducir mensajes del formato nativo de cada plataforma al formato comun del bus.

Capitulo 15 -- Tareas Programadas (Cron) Creamos el CronService para programar tareas con expresiones cron o intervalos. El agente ahora puede ejecutar acciones de forma autonoma en momentos programados.

Capitulo 16 -- Heartbeat y Autonomia Implementamos el HeartbeatService que despierta al agente periodicamente para revisar tareas pendientes. Este es el componente que hace a nanobot verdaderamente autonomo.

Capitulo 17 -- Sub-agentes Construimos el SubagentManager que permite al agente principal delegar tareas a agentes secundarios que corren en segundo plano con contexto aislado.

Capitulo 18 -- Integracion MCP Agregamos soporte para el Model Context Protocol, permitiendo a nanobot conectarse con servidores de herramientas externos tanto locales como remotos.

---

Grafo de Dependencias

No todos los capitulos son lineales. Algunos dependen de conceptos de capitulos anteriores, mientras que otros pueden leerse de forma relativamente independiente. Aqui esta el grafo de dependencias:

Cap 0: Introduccion
  |
  v
Cap 1: Primera Llamada LLM
  |
  v
Cap 2: Abstraccion del Proveedor
  |
  +---------------------------+
  |                           |
  v                           v
Cap 3: Registro de          Cap 6: Message Bus
  Herramientas                |
  |                           v
  v                         Cap 7: Gestion de Sesiones
Cap 4: Herramientas           |
  de Archivos                 v
  |                         Cap 8: Context Builder
  v                           |
Cap 5: Bucle del Agente <-----+
  |
  +--------+--------+--------+--------+--------+
  |        |        |        |        |        |
  v        v        v        v        v        v
Cap 9   Cap 10   Cap 11   Cap 12   Cap 13   Cap 14
Memoria  Web     Skills   Config   CLI     Canales
                                     |
                    +----------------+--------+
                    |                |        |
                    v                v        v
                  Cap 15          Cap 16   Cap 17
                  Cron           Heartbeat Subagentes
                                             |
                                             v
                                           Cap 18
                                           MCP

Los capitulos 1-5 forman el nucleo critico: sin ellos, nada funciona. Los capitulos 6-8 construyen la infraestructura de comunicacion y contexto. A partir del capitulo 9, los componentes son mas modulares y puedes profundizar en los que mas te interesen.

---

Convenciones del Libro

A lo largo de este libro seguiremos estas convenciones:

• El codigo y la interfaz de usuario estan en ingles. Los nombres de variables, funciones, clases, strings de UI, nombres de archivos y comentarios en el codigo estan en ingles, siguiendo las convenciones de la industria.
• La prosa explicativa esta en espanol. Todas las explicaciones, notas y descripciones estan en espanol.
• Los bloques de codigo son completos. Cuando mostramos un archivo, lo mostramos completo. No hay fragmentos sueltos que tengas que adivinar donde pegar.
• Cada capitulo produce codigo funcional. Al final de cada capitulo, el sistema funciona con las capacidades acumuladas hasta ese punto.

---

Siguiente Paso

En el proximo capitulo vamos a hacer nuestra primera llamada a un modelo de lenguaje. Con solo 30 lineas de Python tendras un chatbot funcionando en tu terminal. Sera extremadamente simple --sin memoria, sin herramientas, sin estructura-- pero sera la semilla a partir de la cual crecera todo el sistema.

Adelante.