Multi-Agente Local con vLLM y Claude Code en Linux

vLLM sirve modelos open-weight con API compatible Anthropic. Combinado con Agent Teams de Claude Code, puedes orquestar varios agentes en paralelo sobre tu codebase con inferencia 100% local. Esta guía cubre el setup completo en Linux: Docker, configuración, modelos recomendados y consideraciones de producción.

Por qué montar agentes locales en paralelo

Cuatro agentes trabajando en paralelo sobre tu codebase. Cada uno con su contexto de 128K tokens, ejecutándose en tu propia máquina. Sin llamadas a la nube, sin latencia de red, sin coste por token. Eso es lo que permite combinar vLLM con Agent Teams de Claude Code en Linux.

El problema de los setups cloud es triple. Primero, cada iteración agéntica consume tokens: tool calls, lecturas de archivo, razonamiento. Con cuatro agentes trabajando a la vez, la factura escala rápido. Segundo, el código de tu proyecto viaja a servidores externos en cada petición. Para proyectos con código propietario, eso es un problema. Tercero, dependes de la disponibilidad y los rate limits del proveedor.

La alternativa: levantar un servidor de inferencia local con vLLM en Docker, apuntar Claude Code a ese endpoint y activar Agent Teams para que múltiples instancias colaboren en paralelo. El resultado es un sistema multi-agente que funciona sin conexión a internet para la inferencia, con coste fijo tras la inversión en hardware.

Si ya conoces los mejores LLMs para coding agéntico local, este artículo es el siguiente paso: cómo orquestarlos como un equipo.

¿Qué es vLLM?

vLLM es un motor de inferencia de alto rendimiento para LLMs, desarrollado en UC Berkeley. Su innovación principal es PagedAttention, que gestiona la caché KV como páginas de memoria virtual, reduciendo la fragmentación y permitiendo servir más peticiones concurrentes con la misma VRAM. Soporta continuous batching: nuevas peticiones se incorporan al lote en curso sin esperar a que termine el actual.

Lo relevante para este setup: vLLM implementa la API de Anthropic Messages de forma nativa. Claude Code puede conectarse directamente a un servidor vLLM sin proxies ni capas de traducción intermedias. Cualquier modelo servido por vLLM con soporte de tool calling funciona como reemplazo directo de los modelos Claude.

¿Qué son los Agent Teams de Claude Code?

Agent Teams es una funcionalidad experimental de Claude Code (v2.1.32+) que permite orquestar equipos de sesiones trabajando en paralelo sobre un proyecto compartido. Una sesión actúa como team lead: coordina tareas, las asigna y sintetiza resultados. Los teammates trabajan de forma independiente, cada uno con su propio context window.

La diferencia con los subagentes clásicos es la comunicación. Los subagentes solo reportan al agente principal y no pueden coordinarse entre sí. En Agent Teams, los teammates se envían mensajes directos, reclaman tareas de una lista compartida con tracking de dependencias y resuelven problemas de forma colaborativa. Si quieres entender mejor qué diferencia a un agente de un prompt, conviene revisar esos fundamentos antes de montar el setup.

Hardware necesario

La VRAM es el factor limitante. El modelo se carga en GPU, y todos los agentes comparten el mismo servidor vLLM. Añadir agentes no consume VRAM adicional. Lo que importa es qué modelo puedes servir con tu hardware.

Nivel	GPU	VRAM	Modelo recomendado	Contexto máx.
Entrada	RTX 4090	24 GB	Qwen3-Coder-30B-A3B (Q4)	32K
Prosumer	2x RTX 4090 / A6000	48 GB	Qwen3-Coder-Next (FP8)	128K
Enterprise	H100 / MI300X	80 GB	GPT-OSS-120B (MXFP4)	128K

Requisitos mínimos del sistema: Linux con kernel 5.4+, Docker Engine 23.0+, driver NVIDIA 525+ con CUDA 12.1+. La mayoría de setups en marzo de 2026 usan CUDA 12.4 con driver 550+. Verifica tu versión con nvidia-smi antes de empezar.

Paso 1: Levantar vLLM en Docker

El servidor de inferencia se ejecuta como contenedor Docker. Este comando sirve Qwen3-Coder-Next con tool calling habilitado:

docker run --rm -d --gpus all --ipc=host \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --name vllm-server \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen3-Coder-Next-FP8 \
  --served-model-name qwen3-coder \
  --port 8000 \
  --max-model-len 131072 \
  --gpu-memory-utilization 0.90 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder

Desglose de los flags clave:

• --ipc=host: comparte memoria del host, necesario para tensor parallelism y operaciones concurrentes
• --enable-auto-tool-choice: activa tool calling, imprescindible para uso agéntico con Claude Code
• --tool-call-parser qwen3_coder: parser específico para el formato de tool calls de Qwen3-Coder
• --gpu-memory-utilization 0.90: usa el 90% de la VRAM, dejando margen para overhead de CUDA
• -v ~/.cache/huggingface: monta la caché local de modelos para evitar re-descargas entre reinicios

Para verificar que el servidor responde:

curl http://localhost:8000/v1/models
# Respuesta esperada: JSON con "qwen3-coder" en la lista

Si prefieres GPT-OSS-120B, cambia el modelo y el parser. GPT-OSS es el primer modelo open-weight de OpenAI desde GPT-2: 117B parámetros totales, 5.1B activos por inferencia gracias a su arquitectura Mixture of Experts (MoE), bajo licencia Apache 2.0. Necesita una GPU de 80 GB mínimo con cuantización MXFP4.

Paso 2: Conectar Claude Code al endpoint local

Claude Code usa la variable ANTHROPIC_BASE_URL para decidir a qué servidor enviar las peticiones. Apúntala a tu servidor vLLM:

export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_API_KEY=local
export ANTHROPIC_MODEL=qwen3-coder
claude

Para una configuración permanente, añade las variables en ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8000",
    "ANTHROPIC_API_KEY": "local",
    "ANTHROPIC_MODEL": "qwen3-coder"
  }
}

Desde este momento, todas las peticiones de Claude Code van a tu servidor local. El código de tu proyecto nunca sale de tu red. Nota importante: Claude Code CLI necesita una cuenta de Anthropic para funcionar, pero la inferencia se ejecuta contra tu endpoint local.

Paso 3: Activar Agent Teams

Agent Teams está desactivado por defecto. Añade la variable experimental en el mismo settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8000",
    "ANTHROPIC_API_KEY": "local",
    "ANTHROPIC_MODEL": "qwen3-coder",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Dos modos de visualización disponibles: in-process (todos los teammates en tu terminal) o split panes (cada teammate en su propio panel). Para proyectos con más de dos agentes, split panes permite monitorizar cada uno por separado.

Paso 4: Lanzar el equipo de agentes

Con el servidor activo y Agent Teams habilitado, Claude Code puede descomponer tareas y asignarlas a teammates. Un ejemplo práctico con un refactor de módulo:

> Refactoriza el módulo auth/ separando la lógica
  de JWT, OAuth y permisos en servicios independientes.
  Añade tests unitarios para cada servicio.
  Usa Agent Teams para paralelizar el trabajo.

Claude Code crea un team lead que analiza la estructura, define tareas con dependencias y asigna cada pieza a un teammate. Un agente trabaja en el servicio JWT, otro en OAuth, otro en permisos y un cuarto escribe los tests conforme los servicios se completan. Las tareas pueden declarar dependencias: "escribir tests de integración" se bloquea hasta que "implementar servicio JWT" y "implementar servicio OAuth" terminen.

La clave de una buena descomposición: cada agente debe trabajar sobre archivos diferentes. Si dos agentes tocan los mismos ficheros, habrá conflictos de merge. Las tareas ideales para Agent Teams tienen límites claros, ficheros disjuntos y dependencias explícitas.

Modelos recomendados para multi-agente local

No todos los modelos open-weight funcionan bien con Claude Code. El modelo necesita soporte de tool calling, capacidad de planificación multi-paso y recuperación ante errores de ejecución. Estos son los más probados a marzo de 2026:

Modelo	Params (total / activos)	VRAM mín.	SWE-Bench	Licencia	Mejor para
Qwen3-Coder-Next	80B / 3B	46 GB	70%+ Verified	Apache 2.0	Tareas agénticas largas
GPT-OSS-120B	117B / 5.1B	80 GB	Supera o3-mini	Apache 2.0	Razonamiento complejo
Qwen3-Coder-30B-A3B	30B / 3B	16 GB (Q4)	Competitivo	Apache 2.0	GPU limitada, respuesta rápida

Qwen3-Coder-Next destaca porque fue entrenado específicamente para workflows agénticos: tool calling nativo, planificación multi-paso y recuperación ante fallos. No genera bloques <think>, lo que simplifica la integración con Claude Code. GPT-OSS-120B ofrece razonamiento configurable (low, medium, high) pero necesita hardware enterprise. Para una comparativa más amplia del ecosistema, puedes consultar la guía de Claude Code vs Cursor vs Copilot en 2026.

En Producción

El tutorial funciona para una sesión de desarrollo. En un entorno de equipo o uso continuado, hay consideraciones que cambian.

Rendimiento y prefix caching

vLLM cachea prefijos comunes entre peticiones. En workflows agénticos con Claude Code, las tasas de cache hit llegan al 91% porque el system prompt y el contexto del proyecto se repiten entre iteraciones. Sin embargo, Claude Code inyecta un hash por petición en el system prompt que puede romper el caching. Si usas vLLM anterior a 0.17.1, desactívalo añadiendo "CLAUDE_CODE_ATTRIBUTION_HEADER": "0" en el bloque env de tu settings.json.

Costes reales

El coste de inferencia local se reduce a electricidad y amortización de hardware. Una RTX 4090 consume unos 350W bajo carga. Con tarifas europeas (~0,25 €/kWh), una sesión intensiva de 4 horas cuesta aproximadamente 0,35 € en electricidad. Compara eso con el equivalente en tokens de API para cuatro agentes trabajando en paralelo durante ese tiempo. La inversión en hardware se amortiza en semanas de uso intensivo.

Escalabilidad y límites

Cada agente adicional añade latencia porque comparte el mismo servidor de inferencia. Con continuous batching de vLLM, la degradación es gradual. En la práctica, 4-6 agentes en paralelo funcionan bien con una sola GPU potente. Para más concurrencia, usa tensor parallelism con múltiples GPUs añadiendo --tensor-parallel-size 2 (o más) al comando de Docker.

Lo que cambia del tutorial a producción

En producción necesitas health checks para detectar caídas del servidor vLLM, política de restart: unless-stopped en Docker Compose, un start_period generoso (300 segundos mínimo, los modelos grandes tardan minutos en cargar) y monitorización de VRAM para prevenir OOM. También conviene separar el almacenamiento de modelos en un volumen dedicado y versionar la imagen de vLLM en lugar de usar :latest.

Errores comunes y depuración

Error: CUDA out of memory al iniciar vLLM.
Causa: el modelo no cabe en la VRAM disponible con la configuración actual.
Solución: reduce --max-model-len (menos contexto, menos memoria) o baja --gpu-memory-utilization a 0.85. Si persiste, usa una variante cuantizada del modelo (FP8 o Q4).

Error: Claude Code no genera tool calls, solo devuelve texto plano.
Causa: tool calling no está habilitado en el servidor vLLM.
Solución: verifica que usas --enable-auto-tool-choice y el --tool-call-parser correcto para tu modelo. Cada familia de modelos tiene su parser específico.

Error: latencia alta entre iteraciones agénticas, el agente tarda segundos en responder.
Causa: prefix caching roto por el hash de atribución de Claude Code.
Solución: actualiza vLLM a 0.17.1+ o añade "CLAUDE_CODE_ATTRIBUTION_HEADER": "0" en el bloque env de settings.json.

Error: served-model-name no coincide y Claude Code devuelve error de modelo no encontrado.
Causa: el nombre del modelo en vLLM contiene barras (/) o no coincide con ANTHROPIC_MODEL.
Solución: usa --served-model-name con un alias simple sin caracteres especiales y asegúrate de que coincide exactamente con la variable de entorno.

Para diagnosticar problemas de forma sistemática en este tipo de setups, las técnicas de debugging en apps LLM aplican directamente.

Preguntas frecuentes

¿Necesito una GPU NVIDIA para usar vLLM?

Sí para inferencia acelerada. vLLM soporta GPUs NVIDIA con CUDA 12.1+ y GPUs AMD con ROCm 7 en tarjetas Instinct MI300X/MI325X/MI350X. No soporta inferencia en GPU en macOS. En CPU funciona, pero a 1-3 tokens por segundo con modelos de 7B, lo que no es viable para uso agéntico.

¿Puedo combinar agentes locales con la API de Anthropic?

Sí, y es un patrón práctico. Usa el modelo local para tareas repetitivas como tests, refactors y generación de boilerplate, y reserva la API de Anthropic con Opus 4.6 para decisiones arquitectónicas complejas. LiteLLM permite routing inteligente entre endpoints según el tipo de tarea.

¿Cuánta VRAM necesito para un setup multi-agente?

La VRAM la determina el modelo, no el número de agentes. Todos los agentes comparten el mismo servidor vLLM. Con 24 GB sirves Qwen3-Coder-30B-A3B. Con 48 GB, Qwen3-Coder-Next cuantizado. Con 80 GB, GPT-OSS-120B a precisión nativa MXFP4.

Hemos visto cómo vLLM y Agent Teams convierten una máquina Linux con GPU en una estación de desarrollo multi-agente sin dependencia del cloud. La clave está en elegir el modelo adecuado para tu hardware, configurar tool calling correctamente y descomponer las tareas para que cada agente trabaje sobre ficheros disjuntos. Si ya tienes experiencia con agentes IA en producción, este setup es la extensión natural hacia la independencia de proveedores.

¿Has probado a ejecutar agentes locales con vLLM? Cuéntame tu experiencia en Twitter @sergiomarquezp_. En próximos posts exploraremos cómo añadir routing inteligente entre modelos locales y APIs cloud para optimizar coste y calidad según el tipo de tarea.