22 junio 2026

Arquitectura multi-agente con Paperclip + LiteLLM

En rimamo.dev nos enfrentamos a un reto que ahora es común entre los CTOs fraccionales: orquestar decenas de agentes IA sin depender de un único proveedor de modelo que pueda agotarse o resultar costoso.

En este post describo la solución que implementé para gestionar 27 agentes usando Paperclip como framework de orquestación y LiteLLM como proxy unificado, combinando el NVIDIA NIM free tier (40 RPM) y un fallback automático a OpenRouter. El objetivo es que cualquier empresa pueda reproducir este stack, con bajo coste y alta disponibilidad.

El problema: un proveedor LLM sobrecargado

Cada agente necesita un modelo de LLM para generar su salida.
Con 27 agentes el consumo sube rápidamente (~300 RPM) y el plan gratuito de la mayoría de proveedores se agota.
Cambiar de modelo entre agentes rompe la consistencia del flujo y requiere reconfigurar cada agente.

Sin una capa de abstracción, cualquier caída del proveedor paraliza toda la arquitectura.

La solución: LiteLLM como router unificado

LiteLLM es una capa ligera que expone una API compatible con OpenAI. Actúa como router y rate-limiter para cualquier backend LLM. Todos los agentes apuntan al mismo endpoint interno; LiteLLM decide en tiempo real a qué proveedor enviar cada petición.

Configuración básica

# infra/litellm/config.yaml
model_list:
  - model_name: claude-code-big
    litellm_params:
      model: nvidia_nim/qwen/qwen3.5-397b-a17b
      api_key: os.environ/NVIDIA_API_KEY
      rpm: 18

  - model_name: claude-code-big
    litellm_params:
      model: openai/qwen3.5-plus
      api_base: https://opencode.ai/zen/go/v1
      api_key: os.environ/OPENCODE_API_KEY

  - model_name: claude-code-big
    litellm_params:
      model: openrouter/openai/gpt-oss-120b:free
      api_key: os.environ/OPENROUTER_API_KEY
      rpm: 12

router_settings:
  routing_strategy: least-busy
  num_retries: 1
  cooldown_time: 15
  retry_policy:
    RateLimitErrorRetries: 2

El routing_strategy: least-busy distribuye las peticiones entre los backends según carga. Cuando NVIDIA devuelve un 429, RateLimitErrorRetries: 2 garantiza que se reintenta con el siguiente proveedor antes de fallar.

Integración con Paperclip

Paperclip lanza cada agente con un adapter que apunta al endpoint de LiteLLM. El agente ni sabe qué proveedor responde — todo es transparente. La configuración por agente es mínima:

# agents/rimamo/leadership/ceo.md
---
name: CEO
role: ceo
model: claude-code-big       # nombre lógico — LiteLLM elige el backend
---

El adapter de Paperclip envía la petición a https://litellm.rimamo.dev con el modelo claude-code-big. LiteLLM resuelve a qué backend físico enviarlo en función de RPM disponibles y latencia.

Deploy en Docker con hot reload

LiteLLM se despliega como un servicio Docker en Dokploy. La configuración se monta como bind mount con hot_reload: true — cuando haces git push, Dokploy hace pull y LiteLLM recarga la config sin reiniciar el contenedor.

# docker/litellm/docker-compose.yml
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    volumes:
      - ../../infra/litellm/config.yaml:/app/config.yaml:ro
    environment:
      NVIDIA_API_KEY: ${NVIDIA_API_KEY}
      OPENCODE_API_KEY: ${OPENCODE_API_KEY}
      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY}

# En config.yaml:
general_settings:
  hot_reload: true

Beneficios para el CTO fraccional

Beneficio	Por qué importa
Resiliencia	Si NVIDIA se queda sin cuota, OpenRouter cubre sin interrupciones.
Coste bajo	La capa gratuita de NVIDIA cubre la mayor parte del tráfico; OpenRouter solo interviene como fallback.
Escalabilidad	Añadir más agentes solo requiere apuntarlos al mismo endpoint; el rate-limiting ya está centralizado.
Portabilidad	El config es un YAML versionado en git. Mover a otro servidor es copiar el repo.

Lo que aprendí de los errores

RateLimitErrorRetries: 0 mata el fallback. El valor por defecto hace que el primer 429 aborte sin intentar el siguiente backend. Ponlo a 2.
Los modelos thinking devuelven content: null. Kimi-k2 y DeepSeek en modo thinking solo producen reasoning_content. Para routing groups usa modelos que produzcan contenido real (qwen3.5-plus, gpt-oss).
hot_reload requiere bind mount. Con configs.content embedido en docker-compose, LiteLLM no detecta cambios. El bind mount es la solución.
El cheap model importa. Si un agente no tiene modelo barato explícito, Paperclip cae al proveedor de Anthropic directamente. 29 agentes sin cheap model = factura inesperada.

Próximos pasos

Monitoreo — exponer métricas de LiteLLM (requests, fallback ratio) a un dashboard.
Cache de prompts — evitar llamadas repetitivas dentro del mismo minuto.
Tiers de modelo — separar agentes por complejidad de tarea y asignar backends diferentes según coste/velocidad.

Si estás montando algo similar y quieres que le eche un ojo, escríbeme por LinkedIn.

— Ricardo Martínez
Barcelona, junio de 2026