Módulo 12: Arquitectura de sistemas

Arquitectura de sistemas con IA: de prototipo a producción

La diferencia entre un script con IA y un sistema con IA es enorme. Existen tres niveles claramente diferenciados:

• Script: 1 prompt, stdin/stdout. Funciona en tu terminal, se rompe en manos de otro.
• Aplicación: prompt + UI + base de datos + autenticación. Ya tiene usuarios, pero un fallo en el LLM tumba todo.
• Sistema: multi-agente + orquestación + observabilidad + resiliencia. Preparado para producción real.

Patrón Coordinator + Workers

El anti-pattern más común es el MONOLITHIC AGENT: un agente que hace todo. Recibe la tarea, la analiza, planifica, ejecuta, revisa y responde. Funciona en demos, colapsa en producción.

La solución es separar responsabilidades. El Coordinator decide y delega. Los Workers ejecutan tareas acotadas. Se comunican a través de un scratchpad compartido, nunca pasando datos por el contexto del LLM (que es caro y limitado).

graph TD
    A[Task] --> B[Coordinator]
    B --> C[Worker: Analizar]
    B --> D[Worker: Planificar]
    B --> E[Worker: Ejecutar]
    B --> F[Worker: Revisar]
    C --> G[Scratchpad]
    D --> G
    E --> G
    F --> G
    G --> B
    B --> H{Resultado OK?}
    H -->|Si| I[Output]
    H -->|No| J{Circuit Breaker}
    J -->|Retry menor 3| B
    J -->|Max retries| K[Fallback + Alert]

class Coordinator:
    def process(self, task):
        analysis = self.worker_analyze.run(task)
        plan = self.worker_plan.run(analysis)
        result = self.worker_execute.run(plan)
        return self.worker_review.run(result)

Otro anti-pattern relacionado: el LAZY COORDINATOR. Dice "Based on your findings..." sin haber leído los findings reales. Un buen Coordinator siempre lee y especifica exactamente qué necesita de cada Worker.

Circuit breakers y resiliencia

Un loop de retry infinito es peligroso: genera costes descontrolados, timeouts en cascada y cascading failures que tumban sistemas dependientes. La solución es el circuit breaker: max_retries + fallback + alerta.

@circuit_breaker(max_retries=3, fallback=cached_response, alert=notify_slack)
def call_llm(prompt):
    return client.messages.create(...)

Cada tool call debe tener un timeout configurado. Graceful degradation: si el LLM falla, sirve una respuesta cacheada o escala a un humano. Nunca dejes que un fallo se propague sin control.

Un sistema sin circuit breakers es un sistema que te despertará a las 3 AM.

Contexto y memoria en sistemas multi-agente

La context window es finita. Incluso con 1M tokens, se agota en sesiones largas con muchas tool calls. La compresión automática de contexto es obligatoria para sesiones de trabajo extendidas.

Anti-pattern INLINE LARGE RESULTS: si un tool result supera 1MB, no lo metas en el contexto. Persiste a disco y referencia la ruta. El contexto LLM es memoria cara.

Static/Dynamic prompt split: separa la parte estática del prompt (instrucciones, reglas) de la parte dinámica (datos de la sesión). Esto permite usar cache de API y ahorrar hasta un 90% en tokens repetidos.

La memoria tiene dos capas:

• Short-term: la sesión actual, scratchpad entre agentes. Volátil.
• Long-term: base de datos, vectores en Qdrant, knowledge graph. Persistente.

Anti-pattern ACCUMULATIVE MEMORY: solo acumular sin consolidar. La memoria crece sin límite, el retrieval se degrada y los costes se disparan. La solución es consolidación periódica: resumir, deduplicar, priorizar.

Self-hosted vs API: cuándo migrar

No hay una respuesta universal. Depende de tu volumen, tus requisitos regulatorios y tu capacidad técnica.

• API (OpenAI, Anthropic, etc.): setup rápido, $3-15 por millón de tokens, datos salen de tu infraestructura.
• Self-hosted (vLLM + Qwen/Llama/Phi): setup complejo, ~$0.05 por millón de tokens amortizado, control total de datos.

El break-even típico está en torno a 500 calls/día. Por debajo, la API es más económica. Por encima, self-hosted gana.

Stack self-hosted recomendado: vLLM como servidor de inferencia, modelos como Qwen, Llama o Phi, ejecutado en GPU dedicada (por ejemplo, Hetzner GEX44).

Cuándo vale la pena migrar: volumen alto sostenido O datos regulados (ENS Alto, RGPD, NIS2, DORA). Si manejas datos de clientes europeos en sectores regulados, self-hosted no es opcional.

Self-hosted no es más barato desde el día 1. Es más barato a escala. Calcula tu break-even antes de invertir.

Checklist de producción

15 puntos que debes verificar antes de cada deploy de un sistema con IA:

• ☐ Coordinator no delega sin leer findings reales
• ☐ Workers con scope acotado y scratchpad independiente
• ☐ Circuit breakers en todos los loops de retry
• ☐ Trazas OpenTelemetry en tool calls
• ☐ Eval dataset con CI gate (accuracy >= threshold)
• ☐ Prompts versionados en docs/prompts/
• ☐ HITL para acciones destructivas
• ☐ Rate limiting configurado
• ☐ Error handling con fallback definido
• ☐ Logs solo en EU (cumplimiento RGPD)
• ☐ Secrets en vault/Docker secrets (nunca .env en prod)
• ☐ RLS habilitado en tablas multi-tenant
• ☐ Backup y recovery probado
• ☐ Monitorización de costes con alertas
• ☐ Documentación de arquitectura actualizada