Cómo construir un agente de código personalizado con LLMs open-source

Los agentes de código han pasado de ser una curiosidad de laboratorio a una herramienta práctica en el día a día del desarrollo. Pero no todos los equipos pueden —o quieren— pagar suscripciones de $20+/mes por asistentes propietarios, y mucho menos exponer su código base a APIs de terceros.

La alternativa es clara: construir tu propio agente de código usando LLMs open-source. Modelos como CodeLlama 70B, DeepSeek Coder V2 o Qwen2.5-Coder han alcanzado un nivel de competencia que rivaliza con soluciones cerradas, y corren localmente o en tu propia infraestructura.

En este artículo recorreremos el proceso completo: qué necesitas, cómo diseñar la arquitectura, cómo implementar el loop agente-herramientas y cómo desplegarlo sin morir en el intento.

Requisitos: hardware y software mínimo

Antes de escribir una línea de código, hay que entender el cuello de botella: la inferencia del modelo. Un agente de código requiere generar texto con baja latencia —nadie quiere esperar 30 segundos por una sugerencia de autocompletado.

Hardware recomendado

Configuración	Modelo recomendado	VRAM necesaria
Mínima	Qwen2.5-Coder 7B (cuantizado Q4)	6-8 GB
Recomendada	DeepSeek Coder V2 Lite (cuantizado)	16-24 GB
Ideal	CodeLlama 70B / DeepSeek Coder V2 (cuantizado 4-bit)	40-48 GB

Si no tienes GPU local, servicios como RunPod, Vast.ai o Lambda ofrecen instancias A100/H100 desde ~$0.79/hora. Un agente open-source corriendo 24/7 en una GPU alquilada puede costar menos de $50/mes, muy por debajo de las suscripciones empresariales.

Software necesario

Python 3.11+ con transformers, vllm o llama.cpp para inferencia
LangChain o SmolAgents (de Hugging Face) para el loop agente-herramientas
Docker para empaquetar y desplegar
Ollama o vLLM como servidor de inferencia ligero

“La brecha entre los modelos propietarios y los open-source se está cerrando más rápido de lo que la mayoría anticipa. En code generation, DeepSeek Coder V2 empata o supera a GPT-4 en múltiples benchmarks.”

Arquitectura del agente: el patrón “loop de razonamiento-acción”

La arquitectura de un agente de código personalizado sigue un patrón bien conocido: el loop ReAct (Reasoning + Acting). El modelo no solo genera código: piensa, decide una acción, la ejecuta, observa el resultado y ajusta su plan.

Entrada (prompt/issue) → [Razonamiento] → [Selección de herramienta]
    → [Ejecución] → [Observación] → [Razonamiento] → ... → Salida final

Componentes clave

Orquestador (el loop principal): Un script que mantiene el contexto, administra el historial de mensajes y decide cuándo terminar.
Modelo de lenguaje (el cerebro): El LLM open-source que genera razonamientos y comandos estructurados.
Toolset (las manos): Funciones que el agente puede invocar — leer archivos, escribir código, ejecutar tests, hacer búsquedas.
Memoria: Almacenamiento del contexto de la conversación y artefactos generados.

El formato de herramienta

Para que el LLM pueda usar herramientas de forma confiable, necesitas un formato estructurado. Un approach probado es el formato JSON de herramientas:

HERRAMIENTA: read_file
ARGUMENTOS: {"path": "src/main.py"}

O usando el estándar de OpenAI (compatible con la mayoría de LLMs modernos):

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Lee el contenido de un archivo",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string"}
                },
                "required": ["path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "run_tests",
            "description": "Ejecuta tests unitarios",
            "parameters": {
                "type": "object",
                "properties": {
                    "directory": {"type": "string"}
                },
                "required": ["directory"]
            }
        }
    }
]

Implementación paso a paso

Paso 1: Levantar el servidor de inferencia

Usando vLLM (el más rápido para producción):

# Instalar vLLM
pip install vllm

# Iniciar servidor con DeepSeek Coder V2 Lite
python -m vllm.entrypoints.openai.api_server \
    --model deepseek-ai/DeepSeek-Coder-V2-Lite-Instruct \
    --tensor-parallel-size 2 \
    --dtype bfloat16 \
    --max-model-len 8192

Esto expone una API compatible con OpenAI en http://localhost:8000/v1. Puedes usar el SDK de OpenAI para conectar tu agente:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

Paso 2: Construir el bucle agente-herramientas

import json
from openai import OpenAI

class CodeAgent:
    def __init__(self, model="deepseek-ai/DeepSeek-Coder-V2-Lite-Instruct"):
        self.client = OpenAI(base_url="http://localhost:8000/v1", api_key="none")
        self.model = model
        self.messages = []
        self.tools = self._register_tools()
        self.max_iterations = 10

    def _register_tools(self):
        return [{
            "type": "function",
            "function": {
                "name": "write_file",
                "description": "Escribe código a un archivo",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "path": {"type": "string"},
                        "content": {"type": "string"}
                    },
                    "required": ["path", "content"]
                }
            }
        }]

    def run(self, task: str) -> str:
        self.messages.append({"role": "user", "content": task})
        for _ in range(self.max_iterations):
            response = self.client.chat.completions.create(
                model=self.model,
                messages=self.messages,
                tools=self.tools,
                tool_choice="auto"
            )
            msg = response.choices[0].message
            self.messages.append(msg)

            if not msg.tool_calls:
                return msg.content

            for tc in msg.tool_calls:
                result = self._execute_tool(tc)
                self.messages.append({
                    "role": "tool",
                    "tool_call_id": tc.id,
                    "content": json.dumps(result)
                })
        return "Max iterations reached"

    def _execute_tool(self, tc):
        args = json.loads(tc.function.arguments)
        if tc.function.name == "write_file":
            with open(args["path"], "w") as f:
                f.write(args["content"])
            return {"status": "ok", "path": args["path"]}

Paso 3: Agregar herramientas de ingeniería reales

Un agente de código útil necesita más que leer y escribir archivos. Las herramientas más impactantes son:

run_command: Ejecuta comandos de terminal (lint, build, test)
search_code: Búsqueda semántica en el código base usando embeddings
git_diff: Revisa cambios pendientes y sugiere commits
read_directory: Explora la estructura del proyecto

def run_command(self, command: str, timeout: int = 30) -> dict:
    import subprocess
    try:
        result = subprocess.run(
            command, shell=True, capture_output=True,
            text=True, timeout=timeout
        )
        return {
            "stdout": result.stdout[-2000:],
            "stderr": result.stderr[-1000:],
            "exit_code": result.returncode
        }
    except subprocess.TimeoutExpired:
        return {"error": "Command timed out"}

“El verdadero poder de un agente de código no está en el modelo, sino en las herramientas que le das. Un modelo mediano con excelentes herramientas supera a un modelo excelente sin herramientas.”

Deploy: llevando tu agente a producción

Opción 1: Contenedor Docker con API REST

FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime

RUN pip install vllm openai fastapi uvicorn

COPY agent/ /app/agent/
WORKDIR /app

CMD ["uvicorn", "agent.api:app", "--host", "0.0.0.0", "--port", "8080"]

Opción 2: Integración como GitHub Action

Puedes hacer que tu agente revise PRs automáticamente:

name: Code Agent Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run agent review
        run: |
          curl -X POST http://tu-agente:8080/review \
            -H "Content-Type: application/json" \
            -d '{"repo": "${{ github.repository }}", "pr": ${{ github.event.number }}}'

Opción 3: CLI local para el día a día

Un wrapper simple en bash que canaliza tus requests al agente:

#!/bin/bash
# ~/bin/code-agent
curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d "$(cat)" | jq -r '.choices[0].message.content'

Uso: echo "Refactoriza esta función para usar async/await" | code-agent

CTA: El futuro del desarrollo es aumentado

Construir tu propio agente de código con LLMs open-source no es solo una cuestión de ahorro: es una decisión estratégica. Controlas tus datos, personalizas el comportamiento y escalas sin límites de suscripción. La infraestructura ya está madura —vLLM, Ollama, Llama.cpp— y los modelos compiten cabeza a cabeza con las alternativas cerradas.

En el blog de DojoFullStack exploramos semanalmente cómo la inteligencia artificial y la automatización están transformando la ingeniería de software. Sigue explorando estos temas en el blog de DojoFullStack y únete a una comunidad de desarrolladores que no solo consumen tecnología, sino que la construyen.

¿Ya tienes tu agente de código open-source corriendo? Cuéntanos tu experiencia — y si aún no lo has hecho, este artículo es tu punto de partida. El código, los modelos y las herramientas están ahí. Solo falta que le des el primer paso.