Paperclip — Agencia AI en local

Qué es esto

El objetivo era concreto: probar si la orquestación multiagente puede simular una organización de marketing real. No una demo. Un sistema que recibe objetivos, los convierte en tareas, las delega, las ejecuta, y reporta — con roles diferenciados y sin intervención humana constante.

Las preguntas eran tres: ¿cumplen los objetivos? ¿Cómo se comportan sin supervisión? ¿Cuánto cuesta operarlo?

La respuesta corta es: sí funciona, pero solo si la arquitectura está diseñada con intención. Un sistema de agentes sin estructura no hace trabajo — inventa trabajo. Y eso, en tokens, sale caro.

Cómo llegamos a esta arquitectura

No empezamos acá. La arquitectura final es el resultado de tres iteraciones, cada una con su lección.

Fase 1 — Todo en cloud. Empezamos con Paperclip corriendo sobre Codex (modelo mediano) y después Claude Sonnet. Ambos funcionaron en términos de razonamiento, pero consumían tokens a una velocidad que agotaba el plan de suscripción antes de terminar una sesión de trabajo. Escalar a modelos más capaces (5x más caros) no tenía sentido — la prueba de concepto no lo justificaba.

Fase 2 — LM Studio local. Instalamos LM Studio en una Mac M-series para correr el modelo localmente. El primer intento fue con Qwen3, pero su ventana de contexto extendida (~56k tokens activos) tiraba abajo la máquina. Pasamos a Qwen2.5-14B con configuración ajustada: ventana de contexto reducida y GPU offload al máximo. Con eso la Mac aguantaba, aunque lento.

Fase 3 — Arquitectura híbrida. El problema de Qwen local solo es que no alcanza para los roles de coordinación. La solución fue separar por capa: los agentes operativos (análisis, propuestas) corren en local; el dispatcher usa un modelo mini pago; y el CEO usa Sonnet, que tiene el razonamiento para priorizar y delegar bien.

Las instrucciones son todo

Paperclip out-of-the-box tiene dos problemas serios. Primero: es demasiado generalista — sin un objetivo claro, los agentes empiezan a hacer cosas que no tienen nada que ver con lo que querés. Segundo: ejecuta sin preguntar — tocaba configuraciones de modelos y asignaba presupuesto sin consultar.

La solución fue en dos partes. Primero, usar Claude CLI como puppet master: en lugar de dejar que Paperclip tome decisiones libremente, Claude orquesta qué le pasa a cada agente y cuándo. Segundo, reescribir completamente las instrucciones de cada rol.

Cada agente ahora tiene tres capas de instrucciones:

• Contexto de empresa: misión, alcance, qué está explícitamente prohibido sin aprobación humana
• Prompt de rol: qué hace este agente, qué no hace, a quién delega — sin ambigüedad
• Formato de output fijo: toda respuesta operativa tiene que salir con este esquema exacto

RESUMEN:
ACCION:
RESULTADO:
RIESGO:
SIGUIENTE_PASO:
APROBACION_REQUERIDA:

Ese formato parece burocrático, pero es lo que hace que el sistema sea auditable y predecible. Un agente que no puede llenar esos seis campos no está listo para ejecutar. También se redujo la ventana de contexto y se activó el modo "pure" en algunos agentes para evitar que acumulen contexto innecesario entre ciclos.

Con esos cambios, el sistema empezó a crear roles, delegar tareas y producir outputs accionables.

Puntos fuertes

Costo operativo controlable. Los agentes que hacen el trabajo pesado (análisis, propuestas) corren en local sin costo por token. El gasto pago queda concentrado en CEO y Delivery Manager — los roles que necesitan mejor razonamiento pero se activan menos seguido.

Delegación con trazabilidad. Cada tarea tiene un parentId que registra quién delegó qué y por qué. Si algo falla o genera riesgo, hay un historial claro de las decisiones.

Budget por agente. Paperclip permite poner un techo mensual de gasto por agente. Si lo supera, se frena solo. Eso da tranquilidad para dejarlo correr sin supervisión constante.

La estructura escala sin infraestructura nueva. Agregar un agente es agregar un prompt y un schedule. No cambia nada en el runtime ni en el control plane.

Puntos débiles

Qwen2.5-14B no alcanza para producción. Para análisis de texto funciona. Para tool-calling complejo (llamadas a APIs externas con schemas elaborados), falla. La prueba de concepto está hecha, pero escalar a uso real necesita un modelo local más grande — lo que implica hardware dedicado más potente.

Paperclip es demasiado generalista out-of-the-box. Sin instrucciones muy específicas, los agentes se van por las ramas. No es un producto listo para usar — es un framework que requiere diseño intencional antes de encenderlo.

LM Studio es un punto único de fallo manual. El modelo hay que cargarlo a mano. Si la máquina se reinicia, el stack se cae. No hay failover, no hay auto-restart. Para un setup de producción, esto es un problema real.

Paperclip tiene un sesgo muy "Dev" en su mindset. Sin instrucciones claras sobre el negocio, los agentes tienden a crear roles técnicos por default — CTO, Engineer, QA. Era casi inevitable: si no le decís explícitamente que es una operación de marketing, el sistema asume que está armando un equipo de producto. Esto refuerza que el diseño de roles y el contexto de empresa tienen que estar escritos antes de encender nada.

Sin guardrails, delira rápido. Lo probamos: un agente sin formato de output fijo empieza a generar respuestas en prosa que el siguiente agente no puede parsear. El loop se rompe en minutos. La estructura no es opcional.

Los secrets terminan en los archivos de config. Cuando conectás un agente a servicios externos (CRM, APIs de ads, herramientas), los tokens de acceso quedan escritos en los archivos de configuración de OpenCode. Si esos archivos van a un repo compartido o público, estás exponiendo credenciales reales. Hay que redactarlos antes de compartir o usar variables de entorno.

Cómo replicarlo

Lo técnico es accesible. Lo difícil es el diseño operativo previo — antes de instalar nada, definí la estructura de tus agentes: qué rol tiene cada uno, a quién delega, qué output produce.

1. Verificar prerequisitos Necesitás node v20+, jq y lms (LM Studio CLI). El repo incluye un script que chequea todo: bash scripts/check-prereqs.sh
2. Instalar LM Studio y cargar el modelo Descargar de lmstudio.ai. Cargar Qwen/Qwen2.5-14B-Instruct. Configurar: Context 8192 (no más — voltea la máquina), GPU Offload máximo. Activar Developer Server en puerto 1234. O usar el script: LMSTUDIO_MODEL="qwen/qwen2.5-14b" bash scripts/start-lmstudio.sh
3. Renderizar la configuración de OpenCode OpenCode es el runtime que conecta Paperclip con el modelo local. El script genera el config automáticamente: bash scripts/render-opencode-config.sh
4. Clonar el repo y arrancar Paperclip git clone https://github.com/augustolj/paperclip → bash scripts/bootstrap-paperclip.sh → abrir http://127.0.0.1:3100. O todo en una pasada: bash scripts/orchestrate-local-stack.sh
5. Smoke test Verificar que el stack completo responde: bash scripts/smoke-test-local-stack.sh. Si pasa, los agentes están listos para recibir tareas.
6. Usar Claude CLI o Codex CLI como puppet master No dejés que Paperclip tome decisiones solo al principio. Claude CLI puede orquestar tareas desde afuera, dándote control total sobre qué ejecuta cada agente y cuándo.

El patrón de session handover

Una práctica que salió de este proyecto: documentar el estado del stack en un archivo de handover antes de cerrar una sesión de trabajo. El archivo registra qué está corriendo, qué IDs tienen los agentes, qué tareas están en progreso y cómo retomar.

Cuando volvés a trabajar — vos o una herramienta AI — ese archivo permite retomar sin perder contexto. Claude CLI o Codex lo leen al inicio de sesión y saben exactamente dónde estaban. Sin él, cada sesión empieza de cero.

# session-handover.md
## Dónde estamos
Stack corriendo en http://127.0.0.1:3100
CEO → Delivery Manager → Performance Analyst

## Estado de tareas
- WHI-7: métricas Google Ads — pendiente de play manual

## Para retomar
1. Abrir LM Studio → cargar modelo → activar server
2. bash scripts/bootstrap-paperclip.sh
3. Dar play a WHI-7

El repo incluye una plantilla en docs/session-handover.md.

Próximos pasos

La prueba de concepto está hecha: los agentes se coordinan, delegan tareas y producen outputs estructurados. El loop CEO → Delivery Manager → agentes operativos funciona. Lo que limita ir a producción real es el hardware.

• Hardware dedicado más potente: Qwen2.5-14B en una Mac M-series es un prototipo. Para una operación real necesitás un modelo de 32B+ o un servidor dedicado con más VRAM. El stack de software no cambia — solo el hierro debajo.
• Modelo local más capaz: Qwen3-32B o similar permitiría que los agentes operativos hagan tool-calling a APIs externas directamente, sin depender del modelo cloud para eso. Eso bajaría el costo operativo a casi cero.
• Automatizar el setup de LM Studio: El único paso manual que queda es cargar el modelo. Si se puede scripting, el stack entero arranca solo al encender la máquina.
• Más clientes: La arquitectura es replicable. Cada cliente tiene su propio set de agentes con su propio contexto. El caso piloto es la prueba de que funciona.

La pregunta de fondo: ¿a qué punto una célula de agentes se vuelve más cara en overhead operativo que en tokens? Todavía no llegamos a ese punto. El juego es crecer sin cruzarlo.

¿Cuánto cuesta escalar?

El stack local tiene sentido en prototipo. La pregunta real es: ¿a qué escala conviene seguir en local versus pagar por API? ¿Qué ganás con un modelo más nuevo? ¿Cuántos agentes podés correr en paralelo y con qué hierro?

Qwen3 vs Qwen2.5: qué cambia

Qwen2.5-14B (lo que corre en este proyecto) es sólido para outputs estructurados. Qwen3-14B, lanzado en 2025, mejora específicamente lo que más importa acá: tool-calling multi-turno, modo pensamiento activable por prompt, y rendimiento equivalente a Qwen2.5-32B con la mitad de memoria. El salto más interesante es Qwen3-30B-A3B, un modelo MoE que tiene 30B parámetros totales pero solo activa 3B por inferencia — cabe en 15-18 GB de VRAM y responde casi igual de rápido que un 7B.

En términos prácticos: con Qwen3-14B podés poner a los agentes operativos (Performance Analyst, Media Buyer) completamente en local y que hagan tool-calling a APIs externas sin pasar por un modelo cloud. Eso baja el costo operativo a casi cero una vez que tenés el hardware.

Cuántos agentes en paralelo

LM Studio soporta hasta 4 predicciones concurrentes por configuración (ajustable). El límite real es la VRAM disponible. Qwen3-14B requiere ~8 GB en Q4:

Alquilar el hardware en la nube

Si no querés comprar, el equivalente cloud. Precios por hora (2025, on-demand):

Una RTX 4090 en spot (Vast.ai) corre 2–3 agentes Qwen3-14B a ~$0.30/hr. Para 8 horas de trabajo al día: menos de $3. El M2 Ultra propio sigue siendo más barato amortizado, pero no tenés que poner USD 5.500 adelante.

Comparación con APIs (Claude / Codex / Gemini)

Referencia de precios por millón de tokens (2025), input/output:

Prompt para replicarlo con tu LLM

Si querés armar este stack, el camino más directo es pasarle a tu LLM de preferencia el contexto completo de lo que querés hacer. El prompt de abajo condensa la arquitectura, los prerequisitos y los objetivos. Recomendamos activar Plan Mode antes de pegarlo — así el modelo planifica antes de tocar nada.

Copiá el prompt, reemplazá los campos marcados con [corchetes] y pegalo en Claude Code, Cursor, Codex o el CLI de tu preferencia:

Quiero montar un stack de agentes AI en mi máquina local usando Paperclip como orquestador y LM Studio como servidor de modelo local. El objetivo es tener una "agencia AI" que coordine tareas de marketing/operaciones sin depender exclusivamente de tokens pagos.

## Fase 0: investigar antes de tocar nada

Antes de instalar cualquier cosa, necesito que hagas lo siguiente:

1. Consultá los requisitos actuales de paperclipai (https://www.npmjs.com/package/paperclipai):
   - Versión mínima de Node.js requerida
   - Si tiene dependencia de PostgreSQL embebido (y qué versión)
   - Ventana de contexto mínima recomendada para que los agentes operen bien

2. Consultá los requisitos de opencode-ai de la misma forma.

3. Con esa info, evaluá si el modelo que tengo disponible puede funcionar:
   - Modelo disponible en mi LM Studio: [Qwen3-14B / otro — si no tenés ninguno, recomendame cuál bajar desde la pestaña Discover de LM Studio]
   - ¿Tiene ventana de contexto suficiente? ¿Soporta tool-calling / function calling?
   - Si no cumple, recomendá la alternativa más liviana que sí cumpla

4. Reportá el resultado antes de proceder: qué falta, qué cumple, qué riesgo hay.

## Arquitectura objetivo

Paperclip (orquestador) → OpenCode (runtime local) → LM Studio → modelo local

Para el CEO, usaré [Claude Sonnet / Gemini Flash / otro modelo cloud] vía API.
Para agentes operativos (analistas, compradores de medios), usaré el modelo local.

## Prerequisitos en mi máquina

- OS: [macOS / Linux / Windows]
- Node.js: [versión instalada, o "no instalado"]
- LM Studio: [instalado / no instalado]
- Modelo cargado en LM Studio: [nombre del modelo, o "ninguno"]
- opencode-ai (`npm i -g opencode-ai`): [instalado / no]
- paperclipai (`npm i -g paperclipai`): [instalado / no]

## Agentes que quiero (set mínimo)

1. CEO — orquesta, prioriza, aprueba decisiones
2. Delivery Manager — distribuye tareas, hace seguimiento
3. Performance Analyst — analiza métricas de campañas
4. Media Buyer — ejecuta en plataformas de ads

## Instrucciones de ejemplo (usá estas como base para cada agente)

Contexto de empresa (va al inicio del system prompt de cada agente):
---
Sos parte de una célula de agentes AI que opera como agencia de marketing digital. La empresa tiene clientes de pequeñas y medianas empresas. Trabajás en equipo con otros agentes: CEO, Delivery Manager, Performance Analyst, Media Buyer. No actuás de forma autónoma en plataformas externas sin aprobación explícita. Cuando no sabés algo, lo decís. Cuando necesitás aprobación, la pedís.
---

Instrucción de rol para el CEO:
---
Sos el CEO. Tu trabajo es recibir objetivos de negocio, traducirlos en tareas concretas y delegarlas al Delivery Manager. No ejecutás tareas operativas. Tomás decisiones de prioridad. Aprobás o rechazás acciones de alto impacto. Siempre operás con información completa antes de decidir.
---

Formato de output obligatorio para TODOS los agentes:
---
RESUMEN: [qué evaluaste o hiciste]
ACCION: [qué ejecutaste concretamente, si algo — o "ninguna" si solo analizaste]
RESULTADO: [qué obtuviste o concluiste]
RIESGO: [qué puede salir mal, o "ninguno identificado"]
SIGUIENTE_PASO: [qué debería pasar ahora y quién lo hace]
APROBACION_REQUERIDA: [sí/no — si sí, describí qué necesita aprobación humana]
---

Este formato es no-negociable. Si un agente responde sin él, es un error de configuración.

## Restricciones para todos los agentes

- No ejecutar acciones en plataformas externas (Meta Ads, Google Ads, CRM, email) sin aprobación explícita del operador humano
- No crear nuevos agentes ni modificar roles sin aprobación
- No escalar el scope de una tarea sin reportarlo primero
- Reportar estimación de tokens antes de tareas que involucren contextos largos

## Tests que quiero correr después del setup

1. Smoke test básico: el CEO recibe "Analizá el rendimiento de la semana" y lo delega al Delivery Manager en formato correcto
2. Test de guardrail: pedirle al Media Buyer que "publique un ad en Meta" — debería negarse y pedir aprobación (APROBACION_REQUERIDA: sí)
3. Test de contexto: verificar que el modelo local maneja 4K tokens de contexto sin degradar el formato de output

## Lo que necesito que hagas, en orden

1. Ejecutá la Fase 0 (investigar requisitos y evaluar modelo)
2. Verificá prerequisitos en mi máquina e instalá lo que falte
3. Creá los archivos de configuración de cada agente
4. Configurá OpenCode para que apunte a LM Studio en http://127.0.0.1:1234
5. Arrancá Paperclip y confirmá health check (GET http://127.0.0.1:3100/health)
6. Corré los 3 tests de arriba y reportá resultados

Antes de empezar a tocar archivos, entrá en Plan Mode y mostrame el plan completo para que lo apruebe.

El repo base con archivos de config, prompts de agentes y scripts de bootstrap está en github.com/augustolj/paperclip. Podés clonar y adaptar en lugar de empezar desde cero.