Jose Code

Demo didáctica de un agente de código construido desde cero con Gemini 3.5 Flash. Sin LangChain, sin LlamaIndex, sin frameworks: solo el SDK oficial google-genai y un bucle agéntico hecho a mano.

Pensado como material del curso de agentes para que los estudiantes vean cuáles son los componentes mínimos de un agente y cómo se conectan entre sí.

---

¿Qué hace?

Es un agente de terminal que conversa contigo en español y puede:

• Listar directorios
• Leer archivos
• Crear / sobrescribir archivos
• Ejecutar scripts de Python
• Instalar paquetes con pip
• Abrir HTML/JS en el navegador (Chromium nativo, con fallback a Chrome de Windows en WSL)

Tú escribes una petición y el modelo decide qué herramientas usar, las encadena, y al final te responde en texto plano.

---

Los 6 componentes de un agente

Cualquier agente que veas en el mundo real (Claude Code, Cursor, AutoGPT…) tiene estas mismas piezas. Aquí están una por archivo para que se vean claras:

#	Componente	Archivo	Qué es
1	Herramientas	tools.py	Funciones de Python que tocan el mundo (archivos, subprocesos, navegador).
2	Esquemas	schemas.py	JSON Schema que describe cada herramienta. Es lo único del agente que ve el LLM.
3	Registro	schemas.py	Mapa "nombre" → función Python.
4	System Prompt	agent.py	Instrucciones permanentes: personalidad, reglas, contexto.
5	Bucle agéntico	agent.py	El corazón: llama al LLM, ejecuta tools, retroalimenta, repite.
6	Memoria + REPL	jose_code.py	Historial de la conversación + interfaz de terminal.

jose_code.py    ← entry point: memoria + REPL
    │
    ├─ agent.py     ← [4] system prompt + [5] bucle agéntico
    │      │
    │      └─ schemas.py    ← [2] esquemas JSON + [3] registro
    │              │
    │              └─ tools.py    ← [1] funciones que tocan el mundo
    │
    └─ ui.py        ← colores, banner, /help

---

El bucle agéntico

Es lo que distingue a un agente de un chat normal. Cuando le mandas una petición:

   usuario escribe
         │
         ▼
   ┌────────────────┐
   │ append a       │
   │ history        │
   └────┬───────────┘
        ▼
   ┌────────────────────────────┐
   │ llamar al LLM con:         │  ◄─────┐
   │  · system_prompt           │        │
   │  · tool declarations       │        │  (volvemos aquí
   │  · TODO el history         │        │   después de
   └────┬───────────────────────┘        │   ejecutar tools)
        ▼                                │
   ¿el LLM pidió funciones?              │
     │           │                       │
     │ no        │ sí                    │
     ▼           ▼                       │
   return     ejecutar cada función      │
   texto      → guardar resultados ──────┘

El código está en run_agent() dentro de agent.py, bien comentado paso a paso.

---

Instalación

Necesitas Python 3.10+ y una API key de Google AI Studio.

# 1. Clona el repo
git clone https://github.com/joseIronMaker/jose-code.git
cd jose-code

# 2. Crea un venv (recomendado)
python3 -m venv .venv
source .venv/bin/activate  # en Windows: .venv\Scripts\activate

# 3. Instala las dependencias
pip install google-genai python-dotenv

# 4. Configura tu API key
cp .env.example .env
# edita .env y pega tu GEMINI_API_KEY

# 5. Corre el agente
python jose_code.py

---

Ejemplo de sesión

jose › instala cowsay y haz un script vaca.py que use cowsay para decir "hola jose"
  → pip_install({'packages': 'cowsay'})
    OK: cowsay instalado
  → edit_file({'path': 'vaca.py', 'content': '...'})
    OK: escritos 39 caracteres en vaca.py
  → run_python({'path': 'vaca.py'})
    (exit=0)
      _________
    | hola jose |
      =========
             \
              \
                ^__^
                (oo)\_______
                (__)\       )\/\
                    ||----w |
                    ||     ||

jose_code › Instalé cowsay, creé vaca.py y lo ejecuté.

El agente decidió solo que necesitaba instalar el paquete, escribir el script, y luego correrlo — tú nada más le dijiste el objetivo final.

---

Comandos del REPL

Comando	Qué hace
/help	muestra la ayuda
/clear	borra el historial de la conversación (amnesia voluntaria)
salir	termina (también Ctrl+C o Ctrl+D)

---

Stack

• Modelo: gemini-3.5-flash vía google-genai
• Configuración: python-dotenv para cargar .env
• Función calling: nativo de Gemini, sin abstraction layer

No hay LangChain, ni LangGraph, ni LlamaIndex, ni pydantic-ai, ni nada que esconda el flujo. La idea es ver el agente "desnudo".

---

Licencia

Material del curso de agentes. Úsalo, modifícalo, rómpelo y arréglalo.