Agente de Código Autónomo con Sandbox Seguro en Docker

Sistema autónomo de generación y auto-corrección de código (Self-Healing Agent) impulsado por LangGraph, Google Gemini y un Sandbox Docker ultraseguro y hermético. Diseñado con estándares de ingeniería de software de nivel Big Tech para mitigar riesgos de inyección y ejecución de código no confiable.

---

Tabla de Contenidos

1. Arquitectura del Sistema
2. Matriz de Seguridad del Sandbox
3. Estructura del Proyecto
4. Instalación y Configuración
5. Construcción de la Imagen Sandbox
6. Uso de la API REST y Streaming
7. Suite de Pruebas Automatizadas
8. Buenas Prácticas de Producción

---

Arquitectura del Sistema

El agente implementa un grafo cíclico de cuatro nodos orquestado con LangGraph. Ante un fallo en los tests dentro del sandbox, el error es capturado y retroalimentado al modelo para su auto-corrección automática hasta un máximo de iteraciones configurables.

flowchart TD
    Start([Inicio: Tarea del Usuario]) --> PlannerNode[ Nodo 1: Planificador TDD]
    PlannerNode --> GeneratorNode[Nodo 2: Generador de Código & Tests]
    GeneratorNode --> SandboxNode[Nodo 3: Sandbox Aislado Docker]
    SandboxNode --> EvaluatorNode[Nodo 4: Evaluador de Resultados]
    
    EvaluatorNode --> CondCheck{¿Tests Pasaron?}
    CondCheck -- "Sí (Exit Code == 0)" --> Success([Fin: Código Verificado])
    CondCheck -- "No (Exit Code != 0)" --> RetryCheck{¿Intentos < Max (3)?}
    
    RetryCheck -- "Reintentar (Feedback de Error)" --> GeneratorNode
    RetryCheck -- "Límite Alcanzado" --> Failure([Fin: Máximo de Reintentos])

    subgraph SandboxSeguro [Entorno Aislado del Sandbox]
        TempDir["Directorio Efímero (tempfile)"]
        WriteCode["Escritura de Archivos (.py)"]
        DockerRun["Docker Container (network=none, user=1000, mem=128m, timeout=10s)"]
        Cleanup["try / finally (container.kill & rm -f)"]
        
        TempDir --> WriteCode --> DockerRun --> Cleanup
    end

    SandboxNode -.-> SandboxSeguro

Loading

---

Matriz de Seguridad del Sandbox

El aislamiento de seguridad es la máxima prioridad. Los contenedores de ejecución aplican el principio de mínimo privilegio (Least Privilege) y mitigación exhaustiva de vectores de ataque:

Control de Seguridad	Configuración Técnica	Vector de Ataque Mitigado
Aislamiento de Red	network_mode="none"	Bloquea exfiltración de credenciales, descargas maliciosas, ataques SSRF y conexiones C2.
Límite de Memoria	mem_limit="128m", memswap_limit="128m"	Previene ataques de denegación de servicio (DoS) por agotamiento de RAM o Swap (OOM).
Cuota de CPU	cpu_quota=50000 (50% de 1 núcleo)	Impide que algoritmos de complejidad polinomial/exponencial o scripts de minería congelen el host.
Límite de Procesos	pids_limit=64	Inmunidad total frente a ataques fork-bomb (:(){ :|:& };:).
No Nuevos Privilegios	security_opt=["no-new-privileges:true"]	Bloquea la escalada de privilegios a través de binarios setuid / setgid.
Reducción de Capacidades	cap_drop=["ALL"]	Elimina todas las capacidades avanzadas del kernel Linux (CAP_NET_RAW, CAP_SYS_ADMIN, etc.).
Usuario No Privilegiado	user="1000:1000" (sandboxuser)	Previene la ejecución como usuario root dentro y fuera del contenedor.
Timeout Determinista	10 segundos con container.kill() forzado	Protege el servidor contra bloqueos por bucles infinitos (while True).
Sistema de Archivos Volátil	Montaje efímero vía tempfile.TemporaryDirectory()	Garantiza la eliminación total de archivos tras la ejecución; cero persistencia de basura.

---

Estructura del Proyecto

Agente de Código con Sandbox/
├── .env.example                  # Plantilla de variables de entorno
├── .gitignore                    # Exclusiones de control de versiones
├── Dockerfile.sandbox            # Definición del contenedor de ejecución aislado
├── Makefile                      # Comandos estándar para automatización
├── pyproject.toml                # Metadatos del paquete y configuración de herramientas
├── requirements.txt              # Dependencias fijadas del proyecto
├── README.md                     # Documentación técnica
│
├── app/
│   ├── __init__.py
│   ├── main.py                   # FastAPI REST API y streaming SSE
│   ├── core/
│   │   ├── config.py             # Configuración con pydantic-settings
│   │   └── logging.py            # Logger estructurado unificado
│   ├── schemas/
│   │   ├── request.py            # Esquemas de entrada
│   │   └── response.py           # Esquemas de salida
│   ├── sandbox/
│   │   ├── docker_manager.py     # Gestor de imágenes y daemon Docker
│   │   ├── runner.py             # Ejecutor seguro en contenedor efímero
│   │   └── exceptions.py         # Excepciones tipadas del sandbox
│   └── agent/
│       ├── state.py              # Estado tipado AgentState (LangGraph)
│       ├── prompts.py            # Prompts para Planner, Generator y Corrector
│       ├── llm.py                # Cliente de LangChain Google GenAI
│       ├── graph.py              # Ensamblado del StateGraph con reintentos
│       └── nodes/
│           ├── planner.py        # Nodo 1: Planificador TDD
│           ├── generator.py      # Nodo 2: Generador de Código y Tests
│           ├── sandbox_node.py   # Nodo 3: Ejecutor en Sandbox
│           └── evaluator.py      # Nodo 4: Evaluador y Auto-Corrección
│
└── tests/
    ├── conftest.py               # Fixtures y mocks reutilizables
    ├── test_docker_runner.py     # Pruebas del motor Docker
    ├── test_agent_nodes.py       # Pruebas de nodos y grafo LangGraph
    └── test_api.py               # Pruebas de endpoints FastAPI

---

Instalación y Configuración

1. Clonar el Repositorio e Instalar Dependencias

# Crear y activar entorno virtual
python -m venv venv
# En Windows:
venv\Scripts\activate
# En Linux/macOS:
source venv/bin/activate

# Instalar dependencias
pip install -r requirements.txt

2. Configurar Variables de Entorno

Copia el archivo de ejemplo y agrega tu clave de Gemini:

cp .env.example .env

Edita .env con tu clave de API:

GEMINI_API_KEY=tu_api_key_aqui
GEMINI_MODEL=gemini-2.5-flash

---

Construcción de la Imagen Sandbox

Para construir la imagen Docker aislada:

docker build -f Dockerfile.sandbox -t agent-sandbox:latest .

Nota: Si no la construyes manualmente, el DockerManager del agente la construirá automáticamente en su primera ejecución.

---

Uso de la API REST y Streaming

Iniciar el Servidor

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

La documentación interactiva Swagger UI estará disponible en: http://localhost:8000/docs.

1. Healthcheck

GET /api/v1/health

Respuesta:

{
  "status": "healthy",
  "docker_available": true,
  "gemini_configured": true,
  "version": "0.1.0"
}

2. Generación y Validación de Código

POST /api/v1/generate
Content-Type: application/json

{
  "task": "Implementa una clase LRUCache con métodos get(key) y put(key, value) respetando una capacidad máxima.",
  "max_iterations": 3
}

Respuesta Exitosa:

{
  "task": "Implementa una clase LRUCache...",
  "status": "SUCCESS",
  "iterations": 1,
  "plan": "# Plan Técnico...\n",
  "files": {
    "solution.py": "class LRUCache:\n    ...",
    "test_solution.py": "import pytest\nfrom solution import LRUCache\n..."
  },
  "execution_result": {
    "exit_code": 0,
    "stdout": "================ 5 passed in 0.08s ================",
    "stderr": "",
    "duration_seconds": 0.42,
    "timed_out": false,
    "success": true
  },
  "error_history": [],
  "final_response": "Código y suite de pruebas generados y validados exitosamente en el sandbox."
}

3. Streaming de Progreso en Tiempo Real (SSE)

POST /api/v1/stream
Content-Type: application/json

{
  "task": "Implementa el algoritmo QuickSort con pivote aleatorio y tests exhaustivos."
}

---

Suite de Pruebas Automatizadas

Ejecutar todas las pruebas unitarias y de integración:

pytest -v --tb=short

---

Buenas Prácticas de Producción

1. Gestión de Secretos: Nunca expongas la clave GEMINI_API_KEY en el control de versiones. Emplea un gestor de secretos como AWS Secrets Manager, Google Secret Manager o HashiCorp Vault.
2. GVisor / Firecracker: En entornos de producción de alta concurrencia o multitenant, considera configurar Docker con el runtime runsc (gVisor) para proporcionar aislamiento de kernel adicional.
3. Monitoreo y Métricas: Integra Prometheus y OpenTelemetry para supervisar tiempos de ejecución y consumo de recursos de los contenedores efímeros.