DOMINICODE

Category: Blog

Your blog category

  • Cómo los microtasks afectan la renderización del navegador en aplicaciones

    Cómo los microtasks afectan la renderización del navegador en aplicaciones

    Cómo afectan los microtasks a la renderización del browser

    Tiempo estimado de lectura: 4 min

    • Los microtasks se ejecutan después de cada macrotask y antes de cualquier repintado, por lo que encadenarlos o hacerlos pesados puede bloquear la renderización.
    • Si la microtask queue no se vacía, el navegador pospone Style → Layout → Paint y la UI puede quedarse congelada.
    • Estrategias prácticas: troceado (chunking), requestAnimationFrame, Web Workers, APIs de scheduling y medición/ profiling.
    • Reglas de equipo: no procesar >10ms en microtasks sin justificar; mover tareas >16ms a chunking o workers.

    ¿Sabes por qué una cadena de Promise.then() puede dejar tu UI congelada? Porque los microtasks afectan la renderización del browser bloqueándola hasta que su cola se vacíe. Esta no es teoría académica: es la raíz de muchos problemas de jank y malas métricas (INP, LCP) en aplicaciones reales.

    En las primeras líneas: cómo afectan los microtasks a la renderización del browser es simple y crítico: los microtasks se ejecutan después de cada macrotask y antes de cualquier repintado, así que si acumulas o encadenas microtasks pesadas, el navegador no tiene oportunidad de renderizar.

    Resumen rápido (lectores con prisa)

    Qué es: Los microtasks son callbacks que se ejecutan entre macrotasks y antes del siguiente paint.

    Cuándo usarlo: Para consistencia inmediata de estado y batching corto.

    Por qué importa: Microtasks largos o recursivos bloquean la fase de render y causan jank y malas métricas.

    Cómo mitigarlo: Chunking, requestAnimationFrame, Web Workers y scheduling.

    Cómo funciona: Event Loop, macrotasks y microtasks

    El Event Loop tiene iteraciones claras. En cada iteración:

    • Ejecuta un macrotask (ej.: callback de evento, setTimeout, postMessage).
    • Vacía la microtask queue por completo (Promise.then, queueMicrotask, MutationObserver).
    • Ejecuta las fases de render (Style → Layout → Paint) si procede.

    Iteración del Event Loop

    Fuente formal: WHATWG Event Loops. Referencia práctica: MDN Event Loop.

    Regla que bloquea la renderización

    La regla que mata interfaces es evidente: el navegador no entra en la fase 3 hasta que la microtask queue está vacía. Si esa cola se repuebla constantemente, la renderización se pospone indefinidamente.

    ¿Qué problemas verás en producción?

    • Jank visible: cualquier bloque que supere ~16ms arruina 60fps. Si tus microtasks suman más de eso, las animaciones y scroll saltan.
    • INP y Core Web Vitals: interacción que no despliega un siguiente paint rápidamente penaliza la UX y el SEO. Verifica en web.dev: INP y web.dev: Vitals.
    • “Starvation”: microtasks programando microtasks (recursividad) congelan la pestaña hasta el crash.

    Ejemplo mínimo que congela

    function loop() {
  queueMicrotask(loop);
}
loop();

    No hay render hasta que esto pare.

    Cuándo usar microtasks (y cuándo no)

    Microtasks son útiles y necesarias. No son el enemigo. Úsalas cuando:

    • Necesitas consistencia inmediata del estado antes del siguiente repintado.
    • Quieres agrupar cambios lógicos antes de un único render (batching de estado).
    • Manejas limpieza inmediata tras una operación asíncrona.

    Pero evita microtasks para trabajo CPU-intenso o bucles largos. Para esos casos, usa macrotasks o APIs de scheduling.

    Estrategias para evitar bloquear el render

    Resumen de tácticas prácticas para no secuestrar la renderización.

    1. Chunking (troceado)

    • Divide trabajo pesado en trozos pequeños y programa cada trozo con macrotasks (setTimeout(..., 0)) o postMessage.
    • Ejemplo: procesar arrays grandes en lotes de 100-500 elementos.

    2. requestAnimationFrame para código vinculado a la visual

    Si actualizas animaciones o layout, sincroniza con requestAnimationFrame para respetar vsync.

    3. Web Workers

    Mueve cálculo intensivo fuera del hilo principal. Comunicación vía postMessage (macrotask).

    Guía: Using web workers

    4. APIs de scheduling modernas

    • Evita hacks como setTimeout(fn, 0) a ciegas; usa APIs diseñadas para ceder control: scheduler.yield() y Task Scheduler (aún en evolución).
    • Artículo de referencia: Scheduler (Chrome).
    • requestIdleCallback también ayuda para tareas de baja prioridad (con sus limitaciones).

    5. Medición y profiling

    Usa Chrome DevTools Performance y Lighthouse para identificar long tasks y microtask spikes. El panel de Performance muestra frames dropped y long tasks.

    Casos reales: batching vs starvation

    Frameworks aplican microtasks con criterio. React 18 usa batching y concurrencia para agrupar commits y evitar renders intermedios (React 18 upgrade guide).

    Eso es distinto de encadenar miles de promesas manualmente. Batching intencional reduce trabajo de render; microtasks descontrolados lo empeoran.

    Regla práctica para equipos técnicos

    • Política en code reviews: no procesar >10ms en microtasks sin justificar.
    • Si una operación puede bloquear >16ms, debe ser chunked o movida a worker.
    • Documenta dónde y por qué se usa queueMicrotask o promesas críticas; busca alternativas de scheduling.

    Conclusión

    Los microtasks son herramientas de precisión: mantienen orden y coherencia, pero son capaces de secuestrar el hilo de renderizado si se usan mal. Entender que “microtasks bloquean render hasta vaciar la cola” es suficiente para empezar a evitar errores graves de UX. Mide, trocea y delega: esa tríada separa interfaces fluidas de las que frustran usuarios.

    Lecturas y referencias

    FAQ

    ¿Qué es exactamente una microtask?

    Una microtask es un callback que se encola para ejecutarse inmediatamente después de la ejecución de la macrotask actual y antes del siguiente repintado. Ejemplos: Promise.then, queueMicrotask, MutationObserver.

    ¿Por qué las microtasks se ejecutan antes del paint?

    Por diseño del Event Loop: tras ejecutar una macrotask el navegador vacía la microtask queue para garantizar coherencia de estado antes de recomponer estilos y layout.

    ¿Cómo puedo detectar si mis microtasks bloquean el render?

    Usa Chrome DevTools Performance y Lighthouse. Busca long tasks y picos en la cola de microtasks; si ves trabajos que suman más de ~16ms entre frames, probablemente estés causando jank.

    ¿Es mejor usar setTimeout o queueMicrotask para trocear trabajo?

    Para troceado y ceder control al navegador, las macrotasks (setTimeout, postMessage) son preferibles. queueMicrotask mantiene prioridad y puede seguir bloqueando el render si se abusúa.

    ¿Cuándo usar Web Workers en vez de chunking?

    Usa Web Workers cuando la tarea es CPU-intensiva y no interactúa directamente con el DOM. Chunking es útil para tareas grandes con dependencia de estado en hilo principal.

    ¿Qué herramientas debo usar para medir microtask spikes?

    Chrome DevTools Performance, Lighthouse y panel de Performance para identificar frames dropped, long tasks y microtask activity.

    ¿Qué políticas de equipo son recomendables sobre microtasks?

    Reglas prácticas: no procesar >10ms en microtasks sin justificar; mover operaciones >16ms a chunking o workers; documentar el uso de queueMicrotask y promesas críticas.

  • Dominar Event Loop y Microtasks para evitar problemas de rendimiento

    Dominar Event Loop y Microtasks para evitar problemas de rendimiento

    Event Loop, Microtasks y Concurrencia Interna

    Tiempo estimado de lectura: 4 min

    • Microtasks tienen prioridad sobre macrotasks y render.
    • Una cola de microtasks que se auto‑agenda puede provocar starvation.
    • En Node hay matices: process.nextTick y setImmediate afectan el orden.
    • Chunking o workers son la forma segura de manejar trabajo pesado.

    Introducción

    Event Loop, Microtasks y Concurrencia Interna: dominar esto no es solo saber usar async/await. En las primeras líneas: si no entiendes Call Stack, Web/Node APIs, Task Queue y Microtask Queue —y la prioridad que tienen— seguirás viendo servidores congelados y frontends con “jank”.

    Resumen rápido (lectores con prisa)

    El motor ejecuta macrotasks una por iteración y vacía la cola de microtasks tras cada macrotask. Las microtasks se ejecutan antes que render y macrotasks, y pueden provocar starvation si se auto‑agendan. En Node hay colas adicionales como process.nextTick y diferencias entre setImmediate y setTimeout.

    Event Loop, Microtasks y Concurrencia Interna: qué debes dominar

    • Call Stack: donde corre el código síncrono. Si algo ocupa la pila mucho tiempo, todo se bloquea.
    • Web APIs / Node APIs: el entorno (browser, libuv) ejecuta I/O, timers y los devuelve como callbacks.
    • Task Queue (Macrotasks): setTimeout, I/O, eventos; se procesa una macrotask por iteración.
    • Microtask Queue: Promise.then, queueMicrotask, MutationObserver (y en Node process.nextTick con sus matices); se vacía completamente tras cada macrotask.
    • Prioridad: microtasks > macrotasks > render (en browsers).
    • Starvation: microtasks recursivas pueden impedir que el loop avance.
    • Node specifics: setImmediate vs setTimeout, process.nextTick vs Promise.resolve.

    Cómo funciona en la práctica (y por qué te importa)

    Cada iteración del loop suele seguir este patrón:

    1. Ejecuta la macrotask en curso.
    2. Vacía la microtask queue completamente.
    3. (Browsers) Renderiza si es necesario.
    4. Coge la siguiente macrotask.

    Consecuencia directa: si una microtask agenda otra microtask sin parar, el motor se queda en el paso 2 y nunca llega al render ni a otras macrotasks. Resultado: UI congelada o servidor que no responde.

    Ejemplo de starvation (no lo hagas en producción):

    function starve() {
  Promise.resolve().then(starve);
}
starve();

    Node.js: matices que importan

    Node tiene fases internas; aquí las diferencias que debes aplicar:

    • process.nextTick vs Promise.resolve

      process.nextTick tiene su propia cola y se procesa antes que la cola de Promises. Úsalo para cleanup urgente, pero evita recursividad: un nextTick recursivo bloquea I/O.

    • setImmediate vs setTimeout(…, 0)

      Dentro de un callback de I/O, setImmediate se ejecuta antes que timers. En el script principal el orden puede ser no determinista. Para tareas post‑I/O preferimos setImmediate.

    Ejemplo ilustrativo:

    fs.readFile(__filename, () => {
  setTimeout(() => console.log('timeout-in-io'), 0);
  setImmediate(() => console.log('immediate-in-io'));
});
// Salida consistente: immediate-in-io → timeout-in-io

    Fuente: Node docs.

    Reglas prácticas y patrones seguros

    1. Microtasks para consistencia, macrotasks para ceder control

      Usa microtasks (queueMicrotask, Promise.then) para garantizar orden lógico inmediato, no para procesar grandes volúmenes.

    2. Chunking: divide trabajo pesado

      Para arrays grandes o computación pesada, trocea la ejecución y programa cada chunk con macrotasks (setTimeout / setImmediate) o usa Web Workers / Worker Threads para off‑main.

    3. Evita process.nextTick sin pensar

      Es potente pero peligroso; documenta su uso y limita su alcance.

    4. Usa herramientas de profiling

      Chrome DevTools Performance para front; clinic.js, --inspect para Node. Busca long tasks y spikes en microtasks.

    5. Prefiere APIs modernas cuando estén disponibles

      scheduler.yield() o requestIdleCallback/requestAnimationFrame son mejores opciones en escenarios específicos (revisar compatibilidad).

    Chunking ejemplo:

    function processLarge(items, chunk = 200) {
  let i = 0;
  function next() {
    const end = Math.min(i + chunk, items.length);
    for (; i < end; i++) heavy(items[i]);
    if (i < items.length) setTimeout(next, 0); // cede el hilo
  }
  next();
}

    Criterio técnico resumido (para tu equipo)

    • Define en code reviews: microtasks solo para cosas <10ms y que requieran orden inmediato.
    • Chunking obligatorio para loops que procesen >1k elementos.
    • Mueve CPU‑bound a workers.
    • En Node: setImmediate post‑I/O, nextTick solo para cleanup crítico.

    Conclusión

    Dominar Event Loop, Microtasks y Concurrencia Interna no es trivia: es diseño de sistemas. Entender quién tiene prioridad (microtasks) y cómo evitar starvation cambia aplicaciones que “funcionan” por aplicaciones que escalan y no frustran usuarios. Si quieres que tu equipo deje de parchear problemas de rendimiento, empieza por aquí.

    FAQ

    Respuesta:

    Las microtasks (ej. Promise.then) se ejecutan inmediatamente después de la macrotask en curso y antes del render; la cola se vacía por completo. Las macrotasks (ej. setTimeout, I/O) se procesan una por iteración del loop.

    Respuesta:

    Porque la cola de microtasks se vacía completamente tras cada macrotask: si una microtask agenda otra microtask recurrentemente, el loop nunca avanza a render ni a nuevas macrotasks, congelando la UI o bloqueando I/O.

    Respuesta:

    process.nextTick se usa para cleanup urgente que debe ejecutarse antes de otras promesas. Evítalo para trabajo repetitivo o no crítico, ya que su cola se procesa antes que la cola de Promises y puede bloquear I/O si se abusa.

    Respuesta:

    Usar chunking con macrotasks (setTimeout, setImmediate) o delegar a Web Workers / Worker Threads para mover CPU‑bound fuera del hilo principal.

    Respuesta:

    En frontend, Chrome DevTools → Performance para identificar long tasks. En Node, usar clinic.js y --inspect para perf profiles; buscar spikes y colas saturadas de microtasks.

    Respuesta:

    Trocea procesamiento grande en chunks (ej. 200–1000 items) y programa la ejecución de cada chunk con macrotasks para ceder el hilo entre ellos. Chunking obligatorio para loops >1k según criterio técnico.

    Referencias

  • Cómo integrar Python con n8n para evitar duplicación de lógica

    Cómo integrar Python con n8n para evitar duplicación de lógica

    Cómo combinar Python + n8n sin duplicar trabajo

    Tiempo estimado de lectura: 4 min

    • Separación clara de responsabilidades: n8n orquesta estado y flujos; Python ejecuta procesamiento y lógica compleja.
    • Patrones de integración: nodo Code para tareas pequeñas; microservicio HTTP (FastAPI) para lógica reutilizable y testeable.
    • Contratos y versionado: usar Pydantic y endpoints versionados para evitar duplicación y errores.
    • Procesos largos y archivos grandes: usar encolado (job_id / callback) y almacenamiento externo (S3/GCS).
    • Observabilidad y despliegue: logging estructurado, dockerización y healthchecks.

    Introducción

    Cómo combinar Python + n8n sin duplicar trabajo empieza por una decisión simple: n8n orquesta, Python procesa. Si lo inviertes, acabarás con canvas ilegible o con scripts monolíticos imposibles de testear. Aquí tienes la guía práctica para separar responsabilidades, comunicar ambos mundos sin fricción y evitar los errores que consumen tiempo.

    Resumen rápido (lectores con prisa)

    Qué es: Integración entre n8n (orquestación) y Python (procesamiento).

    Cuándo usarlo: Usa n8n para flujos, triggers y estado; usa Python para transformaciones pesadas, dependencias y testing.

    Por qué importa: Evita lógica duplicada, facilita testing y escalado independiente.

    Cómo funciona: Dos patrones: nodo Code para tareas pequeñas; microservicio HTTP (por ejemplo con FastAPI) para lógica compleja y reutilizable.

    Cómo combinar Python + n8n sin duplicar trabajo: regla y ejemplos

    La regla es directa: n8n gestiona estado, conexiones y flujo; Python hace la transformación y la lógica compleja.

    • n8n: Triggers, autenticación OAuth2, retries, enrutamiento (If, Switch), integración final (CRM, Sheets), almacenar estado.
    • Python: Procesamiento pesado (Pandas, NumPy), ML/IA, scraping (Playwright), parsing de archivos grandes, reglas de negocio complejas.

    Si tu función necesita dependencias pip, CPU/ram o test unitario: ponla en Python.

    Patrones de comunicación (2 opciones)

    Hay dos patrones sólidos para integrar Python en n8n. Escoge según necesidad.

    1) Nodo Code (rápido, limitado)

    Útil para arreglos pequeños: regex, formateos, cálculos puntuales. Evita para lógica que requiera paquetes externos.

    Ejemplo dentro de n8n (pseudo):

    # Python en nodo Code
text = $input.first().json["message"]
urls = re.findall(r'https?://\S+', text)
return [{"urls": urls}]

    Limitación: no puedes garantizar dependencias ni buen versionado. Úsalo para tareas menores.

    2) Microservicio HTTP (recomendado)

    Exponer Python como una API REST (FastAPI) es la arquitectura profesional. n8n usa su nodo HTTP Request para llamar a endpoints.

    Ventajas:

    • Contrato claro con Pydantic.
    • Testable con pytest/postman.
    • Escalable por separado.
    • Reutilizable desde varios workflows.

    Ejemplo mínimo de FastAPI con contrato (Pydantic):

    # api.py
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class LeadInput(BaseModel):
    text: str
    company_size: int

@app.post("/score")
def score(data: LeadInput):
    # Lógica compleja aquí (Pandas, embeddings...)
    score = len(data.text) * (data.company_size / 100)
    return {"score": score, "status": "qualified" if score > 50 else "nurture"}

    Docs: FastAPI, Pydantic

    En n8n configuras un nodo HTTP Request:

    • Method: POST
    • URL: endpoint /score
    • Body JSON: {"text": "{{$json.body.text}}", "company_size": {{$json.body.size}}}

    Contratos de datos: la pieza que evita duplicación

    Define un contrato claro. Es la única manera de que n8n y Python no reinventen la misma validación.

    • Usa Pydantic en Python para validar y documentar entradas.
    • En n8n, transforma y envía solo los campos necesarios. No envíes el objeto completo de n8n.
    • Versiona tu API: /v1/score → /v2/score cuando el contrato cambie.

    Si n8n envía datos mal formados, la API debe responder 422 con un payload explicativo. Eso convierte los fallos en alertas, no en comportamiento errático.

    Patrones para procesos largos o con archivos grandes

    1. Si el procesamiento tarda >30–60s, no bloquees el flujo HTTP síncrono. Implementa este patrón:

      • n8n hace POST → Python responde 202 con job_id.
      • Python encola la tarea (Celery/RQ) y cuando termina hace callback a webhook de n8n o actualiza una cola/persistencia que n8n consulta.

    2. Para archivos grandes (PDFs, imágenes):

      • n8n sube el archivo a un storage (S3/GCS) y pasa la URL firmada a Python. Evitas JSON enormes y timeouts.

    Errores frecuentes y soluciones concretas

    • Lógica duplicada (mismos cálculos en n8n y Python): centraliza en Python y deja en n8n sólo la decisión (If score > 80).
    • Uso del nodo Code para lógica crítica: mueve esa lógica a la API y versiona.
    • No manejar retries/backoff: usa el sistema nativo de reintentos de n8n y expon un endpoint idempotente en Python (acepta reintentos seguros).
    • Pasar estructuras cambiantes: define schemas Pydantic y agrega tests contractuales para detectar cambios en producción.

    Observabilidad y despliegue

    • Logging estructurado en Python (JSON logs). Almacénalos en ELK/Datadog.
    • En n8n, usa el histórico de ejecución para auditoría del flujo.
    • Dockeriza la API Python y define healthchecks. Ejemplo básico en Docker:
    FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "8000"]

    Cierre: criterio para elegir ahora mismo

    • Si la tarea:
      • Requiere dependencias, CPU o tests → Python (microservicio).
      • Es un trigger/entrega/condición simple → n8n.
      • Mezcla estados (login, retries) y transformación → n8n orquesta; Python ejecuta.

    Separar responsabilidades no es esfuerzo extra; es la inversión que evita la deuda técnica. Diseña contratos claros, expón lógica compleja como servicios y deja a n8n dirigir la orquesta. Tus automatizaciones dejarán de ser hacks y pasarán a ser una plataforma sólida.

    Para más recursos y experimentos relacionados con automatización y workflows, consulta Dominicode Labs. Es una continuación lógica para explorar plantillas, ejemplos y herramientas prácticas que complementan esta guía.

    FAQ

    Usa el nodo Code para ajustes pequeños: regex, formateos, cálculos puntuales. Si necesitas paquetes externos, CPU, memoria o tests unitarios, implementa la lógica en Python.

    Define un contrato único y público (Pydantic) en la API Python. En n8n transforma y envía sólo los campos necesarios; no intentes replicar toda la validación en n8n.

    No bloquees la llamada HTTP. Responde 202 con un job_id, encola la tarea (Celery/RQ) en Python y notifica a n8n vía callback o actualiza una persistencia que n8n consulta.

    Sube los archivos a un storage (S3/GCS) desde n8n y pasa la URL firmada a Python. Así evitas JSON enormes, timeouts y transmisión directa de binarios.

    Logging estructurado (JSON) en Python, almacenar logs en ELK/Datadog y usar el histórico de ejecución de n8n para auditoría. Añade healthchecks y métricas básicas en la API.

    Implementa endpoints idempotentes y documenta los contratos. Usa el sistema de reintentos de n8n con backoff y maneja responses 4xx/5xx apropiadamente (422 para validación).

    Expon versiones en la URL (por ejemplo /v1/score, /v2/score). Acompaña con tests contractuales y notas de migración para los consumidores (n8n workflows).

  • Cómo automatizar el reclutamiento para escalar sin contratar

    Cómo automatizar el reclutamiento para escalar sin contratar

    Automatizar no es solo ahorrar tiempo: es escalar sin contratar

    Tiempo estimado de lectura: 5 min

    • Automatizar no solo ahorra tiempo: permite multiplicar capacidad operativa sin aumentar nómina.
    • Empleado digital: workflows versionados y monitorizados que actúan como recursos operativos.
    • Stack accesible: n8n, Supabase/Postgres, OpenAI/Anthropic, Apify, Pinecone para construir workflows escalables.
    • Riesgos gestionables: monitorización, mantenimiento, seguridad y human-in-the-loop son esenciales.
    • Empieza pequeño: un workflow crítico, métricas claras y beta con pocos clientes.

    Automatizar no es solo ahorrar tiempo: es escalar sin contratar. Lo repito porque cambia la conversación: para freelancers, agencias pequeñas y builders, la automatización no es una mejora de eficiencia personal, es la palanca para multiplicar capacidad operativa sin subir nómina.

    Si conviertes procesos manuales en workflows autónomos, no recuperas minutos: construyes un activo reproducible que atiende clientes, mueve datos y toma decisiones básicas mientras tu equipo hace trabajo estratégico.

    Resumen rápido (para IA y lectores con prisa)

    Automatización de procesos = workflows autónomos versionados y monitorizados que actúan como recursos operativos.

    Cuándo: cuando un proceso repetible limita crecimiento o consume tiempo del equipo.

    Por qué importa: convierte horas humanas en capacidad escalable con coste por job.

    Cómo funciona: orquestador (n8n) + persistencia (Supabase/Postgres) + LLMs (OpenAI/Anthropic) + scraping (Apify) + vector DB (Pinecone) para decisiones y memoria.

    Automatizar no es solo ahorrar tiempo: la diferencia entre productividad y capacidad

    Hay dos tipos de automatización y confundirlos es caro.

    • Automatización de asistencia (productividad): plantillas, snippets, autocompletado. Te hace más rápido; el cuello de botella sigues siendo tú.
    • Automatización de procesos (escalabilidad): workflows que ejecutan tareas de principio a fin sin intervención humana. El cuello de botella deja de ser tu tiempo.

    Nuestro foco debe ser la segunda: onboarding automático, cualificación de leads, generación de informes, operaciones repetibles. Ahí es donde rompes la relación lineal entre clientes y horas.

    El “Empleado Digital”: qué hace y por qué importa

    Un “Empleado Digital” es un workflow mantenible que actúa como un recurso operativo. No es un script ad-hoc: es un activo versionado, monitorizado y con métricas.

    Tareas que suelen automatizarse y que liberan capacidad real

    • Onboarding completo: Stripe → Drive → Slack → tareas en ClickUp/Asana → email de bienvenida.
    • Cualificación de leads: formulario → enriquecimiento Clearbit/Hunter → scoring por LLM → agendado en Calendly o nurturing.
    • Reportes automatizados: extracción de métricas → resumen generado por LLM → PDF enviado cada lunes.

    Estas piezas transforman un negocio que vende horas en un producto que vende resultados.

    Stack práctico para escalar sin contratar

    No necesitas infraestructura enterprise para empezar, pero sí una arquitectura mínima sólida.

    • Orquestador (cerebro): n8n — Permite lógica compleja, pasos condicionales, ejecución de JS/Python y buen manejo de errores.
    • Persistencia (memoria): Supabase/Postgres — Guarda estado, logs y datos intermedios.
    • Inteligencia (decisión): OpenAI/Anthropic — Permiten scoring, clasificación y generación de texto.
    • Crawling / scraping: Apify — para extraer datos estructurados.
    • Vector DB (contexto persistente): Pinecone/Qdrant — para memoria semántica si tus agentes necesitan contexto histórico.

    Con este stack puedes diseñar workflows que no solo mueven datos, sino que toman decisiones cualitativas.

    Caso práctico: una agencia que escala x10

    Escenario: agencia de marketing que entrega auditorías SEO manuales (5h por auditoría).

    • Manual: 1 analista → 2 auditorías/día → límite de crecimiento = contratación.
    • Automatizado:
      • 1. Cliente envía URL.
      • 2. n8n lanza crawler Apify y obtiene datos de Ahrefs/API.
      • 3. LLM con prompt “Auditor Senior” analiza resultados y genera hallazgos.
      • 4. Se formatea PDF y se envía al cliente.
    • Resultado: capacidad limitada solo por coste de ejecución (céntimos por job). El equipo se redistribuye a estrategia y ventas. La agencia escala clientes sin contratar.

    Riesgos y cómo mitigarlos (la deuda de la automatización)

    Automatizar mal es multiplicar errores. Los puntos críticos:

    • Monitorización: pipelines deben alertar fallos a Slack/Email. Define retries y dead-letter queues.
    • Mantenimiento: APIs cambian. Reserva tiempo (4–8h/semana al principio) para revisar workflows críticos.
    • Seguridad: gestiona secretos con Vault/Secret Manager; aplica rate limits y validación de inputs.
    • Human-in-the-loop: para acciones sensibles (facturas, borrado masivo) añade aprobación manual.

    Prácticas recomendadas: logs estructurados en Postgres, métricas de ejecución en Prometheus/Grafana y pruebas end-to-end de cada workflow tras cambios.

    Implementa tu primer workflow en una semana: checklist práctico

    1. Identifica el proceso repetitivo con más volumen (onboarding, reporting, lead qual).
    2. Define inputs/outputs y métricas de éxito (ej. tiempo ahorrado, % leads cualificados).
    3. Diseña el flow en diagrama (Mermaid/C4), decide triggers (webhook, cron).
    4. Implementa en n8n con persistencia en Supabase y pruebas locales.
    5. Añade alertas y retries; crea un canal de incidentes en Slack.
    6. Lanza en beta con 5–10 clientes; mide y itera.

    Empieza pequeño: un único workflow con métricas claras. Si funciona, escala.

    Conclusión: margen = ventaja competitiva

    Para freelancers y agencias pequeñas competir por volumen es suicida. La ventaja real está en convertir procesos en activos ejecutables. Automatizar no es meramente recuperar tiempo: es crear capacidad productiva que permite ofrecer más, mejor y a menor coste.

    Si tu objetivo es escalar sin inflar la nómina, construye empleados digitales: bien diseñados, monitorizados y orientados a métricas. Empieza con un flujo crítico esta semana y mide resultados. Esa pequeña inversión técnica es la que separa a quienes venden horas de quienes venden sistemas que generan resultados.

    Si buscas recursos y proyectos ejemplo para poner en práctica estos conceptos, revisa Dominicode Labs como continuación lógica para experimentar con workflows y patrones de automatización en entornos reales. Encontrarás ejemplos orientados a orquestación, persistencia y pipelines con LLMs.

    FAQ

    ¿Qué es un “Empleado Digital”?

    Un “Empleado Digital” es un workflow mantenible y versionado que ejecuta tareas operativas de forma autónoma, monitorizada y con métricas. Actúa como recurso operativo y no como script ad-hoc.

    ¿Qué diferencia existe entre automatización de asistencia y de procesos?

    La automatización de asistencia acelera al humano (snippets, plantillas). La de procesos ejecuta tareas de principio a fin sin intervención humana, permitiendo escalar capacidad.

    ¿Qué stack mínimo recomiendan para empezar?

    Un orquestador como n8n, una base de persistencia (Supabase/Postgres) y acceso a modelos para decisiones (OpenAI/Anthropic). Añade Apify para scraping y Pinecone si necesitas memoria semántica.

    ¿Cómo mitigo el riesgo de automatizar mal?

    Implementa monitorización y alertas, retries, dead-letter queues, validación de inputs, gestión de secretos y puntos de aprobación manual para acciones sensibles.

    ¿Cuánto tiempo requiere mantener workflows críticos?

    Al principio reserva 4–8 horas por semana para revisar workflows críticos; con madurez la carga suele bajar, pero requiere mantenimiento continuo ante cambios de APIs y requisitos.

    ¿Cómo medir si un workflow vale la pena?

    Define métricas claras: tiempo ahorrado, coste por job, % leads cualificados, reducción de errores. Lanza en beta con clientes reales y compara antes/después.

  • Mejores Prácticas para Crear Habilidades de Agentes Efectivas

    Mejores Prácticas para Crear Habilidades de Agentes Efectivas

    Best Practices for Creating Agent Skills

    Tiempo estimado de lectura: 6 min

    Ideas clave

    • Diseñar skills con frontmatter preciso y estructura mínima para que los agentes los carguen correctamente.
    • Escribir instrucciones procedimentales orientadas a máquinas, usando Progressive Disclosure para ahorrar tokens.
    • Empaquetar scripts deterministas para operaciones repetitivas y definir stdout/stderr como contrato para decisiones automáticas.
    • Validar skills con fases: Discovery, Logic y Edge-case testing usando LLMs.
    • Documentar fallbacks y thresholds en referencias; tratar skills como componentes versionados e inspeccionables.

    Best Practices for Creating Agent Skills: si quieres que un agente no solo arranque, sino que sobreviva en producción, necesitas más que buenos prompts. Necesitas arquitectura, disciplina y pruebas diseñadas para máquinas. Este artículo explica, con ejemplos prácticos y referencias, cómo construir skills que los LLMs realmente puedan usar.

    Resumen rápido (lectores con prisa)

    Definir frontmatter preciso, escribir pasos procedimentales en tercera persona imperativa, mover reglas densas a references/ y proveer scripts deterministas. Validar con tres fases (Discovery, Logic, Edge-case) y usar stdout/stderr como contrato para decisiones automáticas.

    Best Practices for Creating Agent Skills: estructura, metadatos y responsabilidades claras

    Los agentes ven un skill antes que nada por su frontmatter. Si ese nombre o descripción no son precisos, el agente nunca cargará tu skill. Sigue estas reglas prácticas:

    • Estructura mínima obligatoria:
    skill-name/
├── SKILL.md              # Metadatos + instrucciones core (<500 líneas)
├── scripts/              # CLIs pequeños para tareas deterministas
├── references/           # Reglas densas, esquemas, decision-trees
└── assets/               # Plantillas y JSON schemas
    • Frontmatter: nombre exacto del skill = nombre del directorio; 1–64 caracteres, minúsculas, números y guiones.
    • Descripción: 1.024 caracteres máx.; redactar en tercera persona; incluir negative triggers (qué NO debe hacer el skill).

    Referencia: agentes basados en metadatos (ej.: agentskills.io).

    Escribe para máquinas: instrucciones procedimentales y JiT loading

    Los LLMs funcionan por patrones. Tu SKILL.md no es un manual; es el orquestador.

    • SKILL.md: pasos cronológicos en tercera persona imperativa. Ejemplo:
      1. “Validate environment: run scripts/check-node-env.js.”
      2. “If fails, abort with message from stderr and surface actionable advice.”
    • No copies masivas de config. Usa Progressive Disclosure: mueve plantillas y reglas densas a assets/ y references/ y obliga al agente a leerlas solo cuando las necesite.
    • Rutas siempre con forward slashes (/).

    Beneficio: menor consumo de tokens, decisiones más precisas.

    Bundle deterministic scripts for repetitive operations

    No pidas al modelo que genere parseadores complejos cada ejecución. Provee scripts probados:

    • scripts/detect-commonjs.mjs — detecta módulos CommonJS problemáticos (puede usar madge: Madge).
    • scripts/env-validator.mjs — valida versión de Node, gestor de paquetes y permisos.
    • scripts/transform-schema.py — transforma esquemas con reglas inmutables.

    Diseña los scripts para devolver errores humanos y machine-actionable por stderr/stdout. Ejemplo de stderr útil:

    CRITICAL: package.json lacks 'build' script. Recommend: run `npx ng update @angular/cli` then retry.

    Referencias técnicas: Vite, esbuild, Node.js.

    Progressive Disclosure: cuándo cargar qué

    Patrón:

    • SKILL.md indica: “Si detectas X, leer references/X.md”.
    • Agent only loads references/X.md when X aparece en el repo.

    Ejemplo aplicado a migración Angular→Vite:

    • No leer webpack-fallbacks.md salvo que angular.json contenga @angular-builders/custom-webpack.

    Resultado: contexto limpio hasta el momento de la decisión.

    Validación con LLMs: Discovery, Logic y Edge-case testing

    Prueba tus skills con otros agentes siguiendo tres fases:

    1. Discovery Validation
      • Pega solo el frontmatter en un LLM y pregúntale qué prompts deberían y no deberían activar la skill. Ajusta description hasta que el modelo sea inequívoco.
    2. Logic Validation
      • Da al LLM SKILL.md + tree de archivos. Pídele simular ejecución paso a paso con monólogo interno: “¿Qué archivo leo? ¿Qué script ejecuto? ¿Dónde me obligaron a adivinar?”
      • Marca las líneas donde el agente tuvo que suponer datos.
    3. Edge Case Testing
      • Pide al LLM que actúe como QA hostil y genere 3–5 preguntas que rompan la skill (p. ej. Node version < 18, custom webpack builders, imports dinámicos CommonJS).

    Sugerencia de benchmark: SkillsBench para inspiración de evals (busca repositorios o frameworks de evaluación de skills).

    Manejo de errores y criterios de fallback

    • Stdout/stderr como contrato: script devuelve JSON estructurado para éxito o mensajes humanos para fallos.
    • Define thresholds decisionales: p. ej., si detectas >3 dependencias CommonJS problemáticas, abortar migración automática y sugerir fallback híbrido.
    • Documenta fallbacks en references/, no en SKILL.md.

    Ejemplo rápido de decisión (pseudocódigo)

    1. Run scripts/env-validator.mjs
2. If exit code ≠ 0 -> return error to user with remediation steps
3. Run scripts/detect-legacy-deps.mjs
4. If legacyDeps.count > 3 -> consult references/commonjs-guide.md and recommend hybrid strategy
5. Else -> read assets/vite.config.template.ts and generate vite.config.ts

    Cierre: audiencia, responsabilidad y próxima iteración

    Las Agent Skills son componentes de infraestructura: deben ser nombradas, versionadas y validadas como cualquier servicio. La disciplina (terminología única, scripts deterministas, progressive disclosure y validación con LLMs) convierte un experimento en una herramienta repetible.

    Implementa estas prácticas y reduce fallos sorpresa en entornos reales. Si quieres un checklist listo para copiar en SKILL.md o ejemplos de scripts env-validator/detect-commonjs, disponemos de plantillas y pruebas automatizadas que puedes integrar hoy.

    Fuentes y lectura adicional

    Implementa esto ahora: estructura tu skill, saca las reglas densas a references/, empaqueta los scripts y empieza las pruebas Discovery/Logic/Edge-case con un LLM. Tu próxima iteración será menos sorpresiva y mucho más confiable.

    Para continuar con herramientas y plantillas que complementan este enfoque, considera explorar Dominicode Labs como una continuación lógica de prácticas de automatización y evaluación de skills.

    FAQ

    ¿Qué debe contener la estructura mínima de un skill?

    La estructura mínima es:

    skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

    SKILL.md contiene metadatos e instrucciones core (<500 líneas); scripts/ almacena herramientas deterministas; references/ reglas densas; assets/ plantillas y esquemas.

    ¿Qué es Progressive Disclosure y cuándo usarlo?

    Es la práctica de mover reglas y artefactos densos a archivos que se cargan solo si son necesarios. Úsalo para reducir tokens y mantener el contexto limpio hasta el momento de la decisión.

    ¿Cómo deben devolver los scripts errores y resultados?

    Definir stdout/stderr como contrato: devolver JSON estructurado para éxitos y mensajes humanos accionables en stderr para fallos, por ejemplo:

    CRITICAL: package.json lacks 'build' script. Recommend: run `npx ng update @angular/cli` then retry.

    ¿Qué pruebas realizar con LLMs?

    Realiza tres fases: Discovery (solo frontmatter), Logic (simulación paso a paso con SKILL.md + tree) y Edge-case (QA hostil generando escenarios que rompan la skill).

    ¿Cuándo abortar una migración automática?

    Define thresholds decisionales; por ejemplo, si detectas >3 dependencias CommonJS problemáticas, aborta la migración automática y recomienda una estrategia híbrida documentada en references/.

  • Cómo optimizar Agentes y Skills en Claude Code para un mejor rendimiento

    Cómo optimizar Agentes y Skills en Claude Code para un mejor rendimiento

    entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos

    ¿Quieres que tu sistema con Claude deje de comportarse como un aprendiz despistado y empiece a trabajar como un equipo bien entrenado? entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos es el primer paso. No es filosofía; es diseño técnico que decide costes, latencia y confiabilidad.

    En una frase: una Skill es una herramienta; un Agente es quien decide cuándo y cómo usarla. En Claude Code (y en el Model Context Protocol) esa diferencia no es semántica: define el control flow, la observabilidad y la estrategia de modelo.

    Resumen rápido (lectores con prisa)

    Qué es: Skill = función stateless y determinista; Agente = sistema que orquesta Skills con loop de razonamiento.

    Cuándo usarlo: Skill para flujos deterministas; Agente para tareas multi-step y adaptativas.

    Por qué importa: determina latencia, coste, observabilidad y riesgo de loops.

    Cómo funciona (alto nivel): Agente observa, planifica, invoca Skills y verifica; Skills exponen APIs claras (MCP/HTTP).

    Tiempo estimado de lectura

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Skills son funciones deterministas y stateless; expónlas como APIs claras.
    • Agentes orquestan Skills y gestionan objetivo, memoria y reintentos.
    • Los agentes añaden latencia, coste e indeterminismo; requieren guardrails y observabilidad.
    • Elige modelo por trade-off: Haiku (rápido/barato), Sonnet (equilibrio), Opus (máxima calidad).
    • Patrón híbrido recomendado: router ligero → Skills directas → Agentes especializados → guardrails y tracing.

    Tabla de contenidos

    Introducción

    ¿Quieres que tu sistema con Claude deje de comportarse como un aprendiz despistado y empiece a trabajar como un equipo bien entrenado? entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos es el primer paso. No es filosofía; es diseño técnico que decide costes, latencia y confiabilidad.

    Agentes vs Skills: la distinción que evita catástrofes

    Skills = funciones puntuales, deterministas y stateless.

    Skills

    • readFile(path), runSQL(query), sendSlack(channel, text).
    • Implementadas como código tradicional (JS/Python) y expuestas al modelo con una firma clara (MCP/HTTP).
    • No razonan. Ejecutan.

    Agentes

    • Mantienen objetivo, memoria y loop de razonamiento (Observe → Plan → Act → Verify).
    • Un Agente puede invocar múltiples Skills, evaluar resultados, reintentar o escalar a humano.
    • En Claude Code, el Agente es la instancia del modelo que ejecuta el bucle y usa las Skills ofrecidas por el runtime.

    Técnicamente: Skills son APIs; Agentes son sistemas de control y decisión que consumen esas APIs.

    Por qué importa: trade-offs de los agentes

    Autonomía suena bien hasta que el Agente se vuelve caro o tóxico. Estos son los efectos prácticos que deberías medir.

    Latencia multiplicada

    Cada paso del bucle agrega llamadas al modelo y a Skills. Una tarea que toma 2s con una Skill directa puede tardar 15–30s con un Agente que valida y reintenta. Para workflows interactivos eso mata la UX.

    Riesgo de loops infinitos

    Si no limitas iteraciones o detectas patrones repetitivos, el Agente puede intentar la misma corrección 1000 veces. Resultado: facturas de API astronómicas y procesos bloqueados.

    Indeterminismo e idempotencia perdida

    Un Agente puede resolver la misma tarea de maneras distintas. Eso da flexibilidad ante casos abiertos, pero complica testing, CI/CD y auditoría. Necesitas validaciones basadas en propiedades (constraints) en lugar de resultados fijos.

    Observabilidad y debugging costosos

    Debuguear un flow agéntico exige trazas por cada llamada LLM ↔ Skill, snapshots de memoria y métricas de confianza. Sin esto, los fallos solo se detectan cuando el usuario se queja.

    Mitigaciones prácticas:

    • Limitar pasos y tiempo por tarea (timeouts cognitivos).
    • Implementar detección de retries repetidos y bloqueo.
    • Validación post-acción (tests automáticos, checksums, schema validation).
    • Escalada a humano cuando la confianza baja.

    Trade-offs de los modelos: elegir Sonnet, Haiku u Opus

    No todos los modelos sirven para todo. Aquí el criterio es coste versus capacidad de razonamiento.

    Claude 3.5 Sonnet — el equilibrio

    • Pros: razonamiento sólido, buen manejo de Tool Use y generación de código.
    • Contras: coste y latencia moderados.
    • Uso: cerebro del Agente para planificación y edición de código.

    Claude 3 Haiku — router / executor barato

    • Pros: rápido y barato.
    • Contras: menos capaz en razonamiento profundo; mayor riesgo de alucinación en tareas complejas.
    • Uso: clasificación, enrutamiento, pre-filtros, resumen rápido o conversión simple.

    Claude 3 Opus — máxima calidad (cuando el coste no importa)

    • Pros: razonamiento profundo y menor tasa de error en zero-shot.
    • Contras: latencia y coste altos.
    • Uso: análisis crítico donde la calidad es la prioridad absoluta.

    Arquitectura recomendada: híbrida. Usa Haiku como router inicial; Sonnet para agentes especializados; Opus solo en batches o tareas off-line costosas.

    Patrón de despliegue práctico (claude-code + MCP)

    1. Router (Haiku): decide si la petición necesita Skill directa o Agente Sonnet.

    2. Skill directa: ejecutar si el flujo es determinista (p. ej. ETL, queries, envíos).

    3. Agente Sonnet: para tareas multi-step (refactor, investigación, remediación).

    4. Guardrails: límites de iteración, chequeos de schema, registros de decisión.

    5. Observabilidad: tracing por etapa (LLM prompt/responses, llamadas Skill, costos).

    Para referencia del runtime y la integración con Skills revisa la documentación de Claude Code en el portal de Anthropic (y el repositorio de ejemplo).

    Criterio final para un Tech Lead

    Decide según tres preguntas:

    • ¿Es el flujo determinista? Usa una Skill.
    • ¿Requiere adaptación y varios pasos? Construye un Agente.
    • ¿Cuál es el SLA de latencia y el presupuesto de coste? Selecciona Haiku/Sonnet/Opus acorde al ROI.

    No es magia: es ingeniería de trade-offs. Un Agente bien diseñado reduce intervención humana y aumenta alcance, pero exige observabilidad, límites y selección cuidadosa de modelo. En Dominicode tratamos Agentes como infraestructura: medimos, protegemos y versionamos. Haz lo mismo y tu Claude Code dejará de improvisar y empezará a producir.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows, puedes encontrar recursos adicionales y experimentos en Dominicode Labs. Es un complemento práctico para aplicar patrones de despliegue, guardrails y observabilidad en proyectos reales.

    FAQ

    ¿Cuándo debería preferir una Skill sobre un Agente?

    Usa una Skill cuando el flujo sea determinista, idempotente y pueda representarse como una API con firma clara (por ejemplo ETL, consultas, envíos). Las Skills reducen latencia y coste y facilitan testing y CI/CD.

    ¿Cómo mitigo el riesgo de loops infinitos en un Agente?

    Implementa límites de iteración, timeouts cognitivos y detección de patrones de retry repetidos. Añade reglas que bloqueen acciones cuando se superan umbrales y escalamiento a humano cuando la confianza sea baja.

    ¿Qué observabilidad mínima necesito para un Agente en producción?

    Traza cada llamada LLM ↔ Skill, snapshots de memoria relevantes y métricas de confianza/decisión. Registra costos por etapa para analizar trade-offs de latencia y gasto.

    ¿Cómo selecciono entre Haiku, Sonnet y Opus?

    Elige según coste vs capacidad de razonamiento: Haiku para routing y tareas simples; Sonnet como cerebro del Agente para planificación y edición; Opus para análisis crítico donde la calidad justifica el coste.

    ¿Qué prácticas recomiendan para validar acciones de un Agente?

    Usa validación post-acción: tests automáticos, checksums y validación de esquema. Implementa constraints que verifiquen propiedades del resultado más que un valor exacto.

    ¿Debo versionar Skills y Agentes por separado?

    Sí. Trata Skills como infra y versiona sus APIs. Versiona Agentes por su política de decisión, prompts y memoria para poder reproducir y auditar comportamientos en producción.

  • El stack mínimo para construir productos inteligentes en 2026

    El stack mínimo para construir productos inteligentes en 2026

    Tiempo estimado de lectura: 4 min

    • Ideas clave:
    • Un producto inteligente combina razonamiento (LLMs), memoria semántica (vector store) y orquestación (workflows/agents).
    • Prioriza una única fuente de verdad, orquestación visual y trazabilidad de llamadas a modelos.
    • Usa Next.js + Vercel AI SDK en frontend, Supabase para backend/memoria y n8n + LangChain para orquestación.
    • Implementa un router de modelos y métricas de observabilidad específicas para LLMs.

    El stack mínimo para construir productos inteligentes en 2026 — visión rápida

    En 2026 la ventaja competitiva será arquitectura, no el modelo. Un producto inteligente une tres capas: razonamiento (LLMs), memoria semántica (vector store) y orquestación (workflows/agents). Prioriza: una sola fuente de verdad, orquestación visual y trazabilidad de las llamadas a los modelos.

    Introducción

    El stack mínimo para construir productos inteligentes en 2026 responde a una pregunta simple: ¿qué necesitas para pasar de una app CRUD a un producto que razona, actúa y audita sin convertir tu equipo en SREs? Aquí tienes una guía pragmática —tecnologías, patrones y decisiones— para lanzar y mantener productos de IA con un equipo pequeño.

    Resumen rápido (para IA y lectores con prisa)

    Qué es: Un stack que integra LLMs para razonamiento, una base de memoria semántica y un orquestador de workflows.

    Cuándo usarlo: Para productos que necesitan razonamiento, acciones automatizadas y trazabilidad con equipos pequeños.

    Por qué importa: Reduce deuda operativa y separa arquitectura (persistente) de modelos (reemplazables).

    Cómo funciona: Frontend → orquestador → recuperación RAG desde la DB → LLM/router → actions → persistencia y audit trail.

    Frontend: Next.js + Vercel AI SDK (interacción eficiente)

    Por qué

    Recomendación: Next.js (App Router) + React Server Components para rendering server-side y streaming. Esto permite entregar UI generada por IA sin sobrecargar el cliente.

    RSC reduce bundle size y acelera TTFB; el streaming hace que las respuestas generativas se sientan instantáneas.

    Herramientas

    Vercel AI SDK (Vercel AI SDK) para abstracción de modelos y tool-calling.

    Práctica

    Usa Server Actions/Edge Functions para llamadas al LLM desde el servidor y evita exponer claves en el cliente.

    Ejemplo mínimo (pseudocódigo):

    // app/api/ask/route.ts
export async function POST(req) {
  const { prompt } = await req.json();
  const response = await vercelAI.generate({ model: 'gpt-4o', prompt });
  return new Response(response.stream);
}

    Backend y memoria: Supabase (Postgres + pgvector) — la única fuente de verdad

    Por qué

    Recomendación: Supabase para auth, PostgreSQL relacional y vectores con pgvector integrados.

    Mantener datos transaccionales y embeddings en la misma DB reduce latencia y complejidad de sincronización.

    Seguridad

    Row Level Security (RLS) para que cada agente solo lea el contexto del usuario.

    Snippet esencial

    create extension if not exists vector;
create table documents (
  id uuid primary key,
  content text,
  embedding vector(1536),
  user_id uuid references auth.users(id)
);
create policy "user_docs" on documents for select using (auth.uid() = user_id);

    Práctica operativa: indexa embeddings en ingest y almacena metadata para filtros semánticos + estructurales. Mide latencia RAG target <100ms.

    Referencia: guía de Supabase sobre vectores Supabase Vector Guide

    Orquestación y agentes: n8n (self-hosted) + LangChain (lógica)

    Recomendación: orquesta agentes con n8n y codifica patrones complejos con LangChain/LangGraph.

    Separar flujo (n8n) de razonamiento (LangChain) permite iterar sin redeploys masivos.

    Patrón: Frontend → webhook n8n → recuperación RAG (Supabase) → LLM (router) → actions (APIs, DB) → update (Supabase) → frontend via Realtime.

    Nodos imprescindibles: webhook, HTTP request, execute JS, wait for approval (human-in-loop), webhook response.

    Ejemplo de flujo:

    • Request del usuario llega a n8n.
    • n8n ejecuta búsqueda semántica en Supabase.
    • Llama al LLM con prompt estructurado (schema + ejemplos).
    • Si la acción es pública, pausa y envía draft a Slack para aprobación.

    Docs n8n: n8n AI Features

    Modelos: router agnóstico y fallback local

    Recomendación: no te cases con un modelo. Implementa un router que seleccione modelo según latencia/costo/privacidad.

    Estrategia: razonamiento crítico → modelo A (Claude/Anthropic), generación de texto económico → modelo B (GPT-mini), fallback privado → Llama/Meta local.

    Implementación: una capa que decide provider por task_type, cost_budget y data_sensitivity.

    Pseudocódigo:

    const model = chooseModel({ task: 'reasoning', privacy: 'high' }); // e.g. Anthropic
const result = await model.call(prompt);

    Pagos y monetización: Lemon Squeezy vs Stripe

    Lemon Squeezy si quieres evitar la trampa fiscal internacional (Merchant of Record).

    Stripe si necesitas facturación por uso (metered billing) y control granular B2B.

    Patrón: webhook de pago → n8n → update user.plan en Supabase → activar feature flags.

    Observabilidad: PostHog + LangSmith (producto + LLM tracing)

    Recomendación: dos capas de observabilidad.

    • PostHog para funnels, retención y session replay.
    • LangSmith (o Arize) para trazas de prompts: coste, latencia, tasa de hallucination y prompts exactos. Sin trazabilidad LLM estás adivinando por qué falla el producto.

    Métricas clave: RAG latency, parse_success_rate (JSON mode), token cost per active user, time-to-approve (human-in-loop).

    Decisiones prácticas y trade-offs

    • Empieza con Supabase; migra a Pinecone/Weaviate sólo si superas límites operativos.
    • Self-host n8n si manejas datos sensibles; usa SaaS para velocidad de prototipo.
    • Mantén temperature=0 en producción para tareas deterministas (parsing, clasificación).

    Conclusión

    El stack mínimo para construir productos inteligentes en 2026 integra Next.js, Supabase y un orquestador como n8n con un router de modelos. No es glamouroso, es eficaz: reduce la deuda operativa y te permite iterar rápido en capacidades de IA útiles. Construye primero la memoria y la orquestación; los modelos son reemplazables, la arquitectura no.

    Recursos

    Para quienes trabajan en automatización, agentes y workflows, puede ser útil explorar herramientas y experimentos adicionales en Dominicode Labs. Esta referencia funciona como una continuación práctica para validar patrones de orquestación y trazabilidad en productos inteligentes.

    FAQ

    Respuesta: ¿Por qué usar Supabase en lugar de un vector store separado?

    Mantener datos transaccionales y embeddings en la misma base de datos reduce latencia y complejidad de sincronización. Supabase ofrece auth integrada y RLS, lo que simplifica seguridad y control de acceso.

    Respuesta: ¿Cuándo self-hostear n8n vs usar la versión SaaS?

    Self-host si manejas datos sensibles o requisitos regulatorios; SaaS si necesitas velocidad de prototipado y menor overhead operativo.

    Respuesta: ¿Cómo implementar trazabilidad de prompts?

    Registra prompts, respuestas, tokens y metadatos en una capa de tracing (ej. LangSmith). Correlaciona con eventos de producto (PostHog) para diagnosticar errores y medir hallucination rate.

    Respuesta: ¿Qué criterios debe usar el router de modelos?

    Decide por task_type, cost_budget y data_sensitivity. Prioriza latencia y privacidad para tareas críticas, economía para generación masiva y fallback local cuando la sensibilidad lo requiera.

    Respuesta: ¿Cuál es la práctica recomendada para production temperature?

    Mantén temperature=0 para tareas deterministas (parsing, clasificación). Ajusta solo cuando necesitas creatividad en generación y puedes auditar resultados.

    Respuesta: ¿Cómo medir la latencia objetivo de RAG?

    Mide desde la petición inicial hasta la respuesta final del LLM incluyendo la búsqueda semántica; el objetivo operativo recomendado en el artículo es <100ms para la etapa RAG (recuperación e indexado de embeddings).

  • Cómo crear un plugin para Anthropic Claude usando MCP

    Cómo crear un plugin para Anthropic Claude usando MCP

    Crear tu primer plugin para Anthropic Claude (Claude Code)

    Crear tu primer plugin para Anthropic Claude (Claude Code) no es magia. Es arquitectura. En vez de «pegar texto en el prompt», vas a exponer funciones ejecutables que Claude puede invocar como herramientas reales. Aquí tienes una guía práctica, técnica y directa para hacerlo funcionar en minutos.

    Tiempo estimado de lectura: 5 min

    • Convierte prompts en herramientas: expón funciones (tools) que Claude invoca mediante MCP en lugar de meter contexto en el prompt.
    • Implementa un servidor MCP: el servidor genera schemas automáticamente y maneja llamadas desde Claude (ej.: FastMCP en Python).
    • Seguridad y fiabilidad: docstrings claros, timeouts, manejo de errores y principio de menor privilegio son imprescindibles.
    • Observabilidad y versionado: registra llamadas, latencias y versiona schemas para evitar rupturas en producción.
    • Integración: estas tools pueden orquestarse en n8n u otros workflows como nodos reutilizables.

    Introducción

    Un “plugin” en Claude es, en realidad, Tool Use o Function Calling via Model Context Protocol (MCP). No le estás metiendo código al modelo: le das una API estructurada y el modelo decide cuándo llamarla. Tu servidor ejecuta la lógica real (Python/TS/Go) y el modelo actúa como cliente que conoce las herramientas disponibles mediante un schema.

    Resumen rápido (lectores con prisa)

    Qué es: Exponer funciones ejecutables (tools) que Claude puede invocar vía MCP.

    Cuándo usarlo: Cuando necesites que el asistente consulte sistemas externos, ejecute acciones o maneje datos sin inflar el prompt.

    Por qué importa: Permite acciones deterministas, auditables y seguras desde un asistente LLM.

    Cómo funciona: El modelo selecciona una tool, genera parámetros según el schema y llama al servidor MCP; el servidor responde con texto estructurado.

    ¿Qué es un “plugin” en Claude?

    Conceptualmente:

    • Claude = cliente que conoce las herramientas disponibles mediante un schema.
    • MCP = protocolo que negocia llamadas entre Claude y tu servicio (stdio, HTTP, WebSocket).
    • Tu servidor = el plugin: código real que ejecuta la lógica (Python/TS/Go).

    No le estás metiendo código al modelo. Le das una API estructurada y el modelo decide cuándo llamarla.

    ¿Qué necesitas y por qué importa?

    ¿Por qué hacerlo? Porque así conviertes un asistente en un agente capaz de:

    • consultar bases de datos internas,
    • ejecutar comprobaciones de infra,
    • automatizar workflows en n8n,

    sin inundar el prompt con contexto ni exponer credenciales en texto.

    Requisitos mínimos:

    Código mínimo: servidor MCP en Python

    Este ejemplo expone una tool que verifica el estado HTTP de una URL usando FastMCP. Copia, ajusta y ejecuta.

    from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("WebChecker")

@mcp.tool()
async def check_website_status(url: str) -> str:
    """
    Verifica el estado HTTP de una URL.
    Args:
      url: URL completa (ej: https://dominicode.com)
    Returns:
      Mensaje con código y razón, o error legible.
    """
    try:
        async with httpx.AsyncClient(timeout=5.0) as client:
            r = await client.get(url, follow_redirects=True)
            return f"Status: {r.status_code} - {r.reason_phrase}"
    except Exception as e:
        return f"Error: {str(e)}"

if __name__ == "__main__":
    mcp.run()

    FastMCP genera automáticamente el schema de la tool a partir de los type hints y docstrings. No escribes JSON a mano.

    Registrar el plugin en Claude Desktop / CLI

    Para que Claude vea tu servidor local, añade una entrada en la configuración de Claude Desktop:

    – macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
    – Windows: %APPDATA%\Claude\claude_desktop_config.json

    Ejemplo:

    {
  "mcpServers": {
    "web-checker": {
      "command": "python",
      "args": ["/ruta/absoluta/a/server.py"]
    }
  }
}

    Reinicia Claude. Deberías ver el servidor activo (icono de enchufe).

    Flujo de ejecución (Thinking Loop)

    Cuando pides: “Claude, comprueba si dominicode.com responde”, sucede:

    1. Claude detecta necesidad de herramienta.
    2. Selecciona check_website_status.
    3. Genera parámetros (url).
    4. Llama al plugin vía MCP.
    5. El plugin responde con texto estructurado.
    6. Claude formatea la respuesta humana.

    Todo ordenado, trazable y auditable.

    Buenas prácticas imprescindibles

    Docstrings son contratos

    Escribe docstrings claros. El modelo usa esa información para construir la llamada. Ambigüedad = invocación errónea.

    Errores controlados

    Nunca dejes que tu plugin haga crash. Captura excepciones y devuelve mensajes legibles. Si tu proceso muere, Claude pierde acceso a todo ese servidor.

    Timeouts defensivos

    Usa timeouts explícitos (ej. httpx timeout=5s). No querrás procesos colgados.

    Principio de menor privilegio

    No implementes tools como exec_shell(cmd) a la ligera. Restringe rutas, usuarios y operaciones. Si necesitas ejecutar comandos, envuelve y valida cada input.

    Observabilidad

    Loguea prompts recibidos, respuestas, latencias y costes. Traza cada call LLM ↔ tool. Para infra, añade métricas que permitan alertas (ERRORES, RETRIES, LATENCIA).

    Gestión de versiones

    Versiona schemas y tools. Cambiar la firma de una función sin versionado rompe agentes y workflows en producción.

    Escalada humana

    Si el agente entra en loop o baja de confianza, define una regla clara: cortar, crear ticket y notificar a un responsable.

    Integración con workflows y n8n

    Estas tools son bloques reutilizables. Úsalas como nodos en n8n o como pasos en un orquestador de agentes. Por ejemplo:

    • Nodo n8n invoca tu API plugin para obtener estado.
    • Resultado condicional dispara un PR automático o un Slack alert.

    Recursos y lectura adicional

    Cierre operativo

    Crear un plugin para Claude Code es convertir una idea en una API que el modelo puede invocar de forma determinista. No es magia; es ingeniería de interfaces. Empieza con una tool pequeña, aplícala en un workflow y añade observabilidad. Si lo haces bien, tu Claude dejará de hablar y empezará a actuar.

    Esto no acaba aquí: construye la siguiente tool, versiona el schema y orquesta esas tools con un agente. Tu siguiente despliegue será la prueba.

    Dominicode Labs

    Si quieres prototipar y validar pipelines de agentes y automatizaciones, revisa Dominicode Labs. Es una continuación natural para integrar tools, pruebas y orquestación en entornos de trabajo técnico.

    FAQ

    ¿Qué diferencia hay entre un plugin y poner contexto en el prompt?

    Un plugin expone funciones ejecutables con schemas; el modelo invoca esas funciones. Poner contexto en el prompt implica enviar datos y lógica de forma textual, sin capacidad de ejecución externa ni trazabilidad.

    ¿Qué es MCP?

    MCP (Model Context Protocol) es el protocolo que negocia llamadas entre el modelo y tu servicio (stdio, HTTP, WebSocket), permitiendo que el modelo conozca y llame herramientas.

    ¿Por qué usar docstrings en lugar de JSON manual?

    Frameworks como FastMCP generan schemas automáticamente a partir de type hints y docstrings, reduciendo errores y manteniendo documentación y contratos sincronizados.

    ¿Cómo manejo errores para que Claude no pierda acceso?

    Captura excepciones, devuelve mensajes legibles y usa timeouts defensivos. No permitas que el proceso principal haga crash; implementa reinicios supervisados y health checks.

    ¿Qué precauciones de seguridad debo tomar?

    Aplica principio de menor privilegio, valida y sanitiza inputs, restringe rutas y comandos, y evita exponer credenciales en texto plano.

    ¿Puedo integrar estas tools en n8n?

    Sí. Usa las tools como nodos o llamadas API desde n8n; el resultado puede condicionar flujos, crear PRs o enviar alertas en Slack.

  • Cómo medir LLM Evals y Observabilidad en Producción

    Cómo medir LLM Evals y Observabilidad en Producción

    LLM Evals, Alignment y Observabilidad en Producción

    Tiempo estimado de lectura: 3 min

    • Ideas clave:
    • Las métricas operativas (Accuracy, Hallucination Rate, Latency, Cost per Task, Consistencia) son indispensables para pasar de prototipo a servicio escalable.
    • Construye un Golden Dataset, valida outputs estructurados y usa un modelo juez para tareas generativas.
    • Observabilidad en vivo (tracing, sampling, alertas) y guardrails de salida son necesarios para seguridad y estabilidad.

    Cómo medir si tu sistema AI realmente funciona en producción empieza por entender que “parece que responde bien” no es una métrica. LLM Evals, Alignment y Observabilidad en Producción son las piezas que convierten un prototipo bonito en infraestructura operable: Accuracy, Goal Completion, Toxicity, Hallucination Rate, Latency, Cost per Task y Consistencia. Si no mides esto, no escalas —solo maquillas el riesgo.

    Resumen rápido (lectores con prisa)

    LLM Evals: pruebas con un Golden Dataset y un modelo juez para medir factualidad y cumplimiento de objetivos. Observabilidad: tracing, sampling y alertas en vivo para detectar degradación y drift. Alineación y safety: guardrails en la salida y revisión humana cuando la confianza es baja.

    LLM Evals, Alignment y Observabilidad en Producción: qué medir y por qué

    La evaluación de modelos en producción debe ser multidimensional. Aquí están las métricas que importan y cómo interpretarlas:

    Métricas específicas

    Accuracy / Factuality

    ¿La respuesta es correcta? En sistemas RAG separa Context Recall (¿se recuperó lo relevante?) de Context Precision (¿la respuesta se basa en lo recuperado o lo inventa?).

    Hallucination Rate

    % de respuestas con información inventada. Target operativo: <3–5% según criticidad.

    Goal Completion

    Métrica binaria/medible ligada al negocio (email extraído, ticket resuelto). Es la métrica ROI.

    Toxicity / Safety

    Puntuaciones automáticas (ej. Perspective API) y guardrails para bloquear salidas peligrosas.

    Latency (TTFT y Total Latency)

    TTFT <2s para chat aceptable; objetivos más estrictos para aplicaciones UX sensibles.

    Cost per Task

    tokens * precio/modelo → $ por ejecución. Debe compararse con coste humano.

    Consistencia

    Desviación en resultados en ejecuciones repetidas; alta variabilidad indica prompts inestables o temperatura mal gestionada.

    Cómo construir Evals útiles (práctico)

    1. Golden Dataset

    Golden Dataset

    • Crea un conjunto curado de 100–500 ejemplos por workflow (80% casos comunes, 20% edge).
    • Human-label para ground truth inicial. Sin esto no hay baseline.

    Deterministic vs Model-Graded

    • Deterministic: para outputs estructurados valida formato/JSON con schema checks.
    • Model-graded: usa un LLM “juez” (más capaz) con una rúbrica para puntuar respuestas textuales. Ejemplo: pedir al juez “evalúa factualidad (1–5) y da evidencia”.

    Pipeline de CI

    • Ejecuta el Golden Dataset en cada PR que cambie prompts, chain logic o modelo.
    • Rechaza merges si Accuracy/Goal Completion bajan más de X%.

    Ejemplo simple (pseudocódigo de evaluación):

    # enviar respuesta + contexto + prompt de evaluación a un modelo juez
judge_prompt = "Evalúa si la respuesta es fiel al contexto. Score 1-5. Explica brevemente."
score = call_judge_model(input=context + answer, prompt=judge_prompt)

    Observabilidad en producción: trazas, sampling y alertas

    Las Evals funcionan offline; la Observabilidad te dice qué pasa en vivo.

    Tracing completo

    Registra input, documentos recuperados, prompts enviados, tokens, latencias por etapa. Usa LangSmith, LangFuse o Arize Phoenix para visualizar trace chains.

    Sampling inteligente

    Evalúa en línea entre 0.5–5% del tráfico para balancear coste y cobertura.

    Drift detection

    Monitoriza cambios en la distribución de inputs; alerta cuando un feature importante sale del rango esperado.

    Alertas por SLA

    Accuracy drop, Hallucination spike, o coste por task anómalo disparan rollback o canary throttling.

    Integra traces con OpenTelemetry para correlación con logs y métricas infra.

    Alineación operativa y safety

    • Implementa guardrails en la capa de salida (post‑processing) que validen seguridad y formato antes de exponer la respuesta (ej. NVIDIA NeMo Guardrails).
    • Para respuestas sensibles, requiere verificación secundaria: LLM-as-a-Judge + schema check + citation check (si es RAG).
    • Mantén un “human-in-the-loop” para casos de baja confianza: si la confianza < umbral, encolar para revisión humana.

    Métricas objetivo y SLOs realistas

    Define SLOs por workflow, p. ej.:

    • Accuracy > 95% en Golden Dataset.
    • Hallucination Rate < 3%.
    • TTFT < 2s.
    • Cost per Task < $0.05 (ajusta según caso de negocio).

    Monitoriza y versiona SLOs junto al código/infra.

    Errores comunes que debes evitar

    • No tener Golden Dataset.
    • Medir solo calidad, ignorar coste.
    • No versionar prompts ni modelos.
    • Silenciar drift: sin alertas el modelo se degrada sin aviso.

    Cierre operativo

    LLM Evals, Alignment y Observabilidad en Producción no son funciones accesorias: son el núcleo del ciclo de vida de una IA productiva. Empieza por construir tu Golden Dataset, versiona prompts como código, añade un juez para tareas generativas y despliega tracing por etapas. Con esas piezas, transformarás la IA de experimento a servicio confiable, escalable y justificable en costes.

    Lecturas y herramientas prácticas

    Para equipos que implementan pipelines de Evals y observabilidad como parte de workflows de producto, una continuación lógica es revisar recursos y experimentos prácticos disponibles en Dominicode Labs. Ahí puedes encontrar ejemplos aplicados y plantillas para integrar tracing y CI de evaluación en flujos de trabajo.

    FAQ

    ¿Qué es un Golden Dataset y por qué lo necesito?

    Un Golden Dataset es un conjunto curado y etiquetado de ejemplos (100–500 por workflow) que sirve como baseline para evaluar Accuracy y Goal Completion. Sin él no tienes una referencia objetiva para medir degradación o mejoras.

    ¿Cómo medir hallucinations en producción?

    Combina sampling en línea con evaluaciones humanas y modelos juez que comparen respuestas contra contexto o fuentes. Mide el porcentaje de respuestas con información inventada y fija umbrales operativos (<3–5%).

    ¿Qué es un modelo juez (model-graded)?

    Es un LLM más capaz que puntúa respuestas humanas/modelo según una rúbrica (p. ej. factualidad 1–5) y devuelve evidencia o explicación para el score.

    ¿Cuánto tráfico debo muestrear para Evals en línea?

    Generalmente entre 0.5–5% del tráfico, para equilibrar coste y cobertura. Ajusta según criticidad y coste por task.

    ¿Qué abandonar ante un spike de hallucinations?

    Accionar alertas: revertir cambios recientes (rollback), activar canary throttling, aumentar muestreo y encolar casos para revisión humana hasta estabilizar la tasa.

    ¿Cómo integrar tracing con OpenTelemetry?

    Instrumenta puntos clave (entrada, recuperación de documentos, llamada al modelo, post‑processing), exporta traces a tu backend y correlaciona con logs y métricas infra para análisis de causa raíz.

    ¿Cuáles son SLOs realistas para chatbots?

    Ejemplos: Accuracy >95% en Golden Dataset, Hallucination Rate <3%, TTFT <2s. Ajusta según el workflow y coste/humano de fallback.

  • Mejorando la Recuperación de Información con RAG Avanzado

    Mejorando la Recuperación de Información con RAG Avanzado

    RAG Avanzado: Híbrido, Jerárquico y Multi-Vector

    RAG Avanzado: Híbrido, Jerárquico y Multi-Vector. Si eso suena a demasiada ingeniería comparado con “chunk + embeddings”, es porque lo es —y la diferencia entre demo y producto está justo ahí. En producción no vale con que el LLM “suene bien”; necesitas precisión, contexto y control de coste. Este artículo explica qué técnicas añadir, por qué y cuándo.

    Tiempo estimado de lectura: 4 min

    • Ideas clave:
    • La recuperación es el 80% de una buena respuesta: combina sparse (BM25) y dense (embeddings).
    • Arquitectura jerárquica (child + parent) equilibra precisión de fragmento y contexto coherente.
    • Re-ranking con cross-encoders y compresión de contexto reducen hallucinations y coste token.

    Introducción

    La calidad de las respuestas generadas por un sistema RAG depende mayoritariamente de la recuperación. Los vectores aportan semántica; los métodos sparse (BM25) aportan exactitud. En producción necesitas precisión, contexto y control de coste; esto implica añadir capas: híbrido, jerarquía, re-ranking, rewriting y compresión de contexto.

    Resumen rápido (lectores con prisa)

    RAG avanzado combina búsquedas sparse (BM25) y dense (embeddings) para precisión y semántica. Usa indexing jerárquico child→parent para fragmentos precisos con contexto. Re-rank con cross-encoders para reducir ruido. Reescribe y descompone queries; comprime contexto antes del LLM.

    RAG Avanzado: implementación práctica

    1) Hybrid retrieval: BM25 + embeddings

    Problema: buscas “ERR-9921” y el vector devuelve “error de sistema” porque semánticamente es parecido. Solución: híbrido.

    • Sparse: BM25/Elasticsearch para coincidencias literales.
    • Dense: embeddings (OpenAI, Cohere, etc.) para intención.
    • Fusión: Reciprocal Rank Fusion (RRF) o combinación ponderada. Pinecone hybrid search

    Patrón práctico:

    • Ejecuta BM25 y vector search en paralelo.
    • Normaliza scores.
    • Fusiona con RRF.
    • Si BM25 tiene match exacto para tokens sensibles (IDs, SKUs), priorízalo.

    2) Multi-vector / Parent-Child indexación

    Dilema clásico: chunks pequeños = mejor match; chunks grandes = mejor contexto. La arquitectura jerárquica arregla ambos.

    • Indexa embeddings a nivel child (p. ej. 200 tokens).
    • Mantén parent docs grandes (p. ej. 2000 tokens) con metadata.
    • Al recuperar un child relevante, sube el parent completo al contexto.

    Implementación: LangChain ParentDocumentRetriever — LangChain ParentDocumentRetriever

    Beneficio: precisión de fragmento + contexto coherente para razonamiento.

    3) Re-ranking con cross-encoders

    Bi-encoders: rápidos, aproximados. Cross-encoders: lentos, precisos.

    Flujo:

    1. Fast retrieval → top N (50).
    2. Cross-encoder rerank en top N.
    3. Selecciona top K final para el LLM.

    Herramientas: sentence-transformers, Cohere Rerank. Costo: aumenta latencia; recompensa: reduce ruido que provoca hallucinations.

    4) Query rewriting y decomposition

    Muchos fallos vienen por queries ambiguas. No todos los problemas se arreglan en el índice.

    • Query rewrite: un LLM rápido reescribe la consulta con contexto de la sesión.
    • Multi-query: genera 3–5 variantes de la pregunta y busca por cada una.
    • Decomposition: divide preguntas complejas en sub-queries paralelas.

    Técnica HyDE (Hypothetical Document Embeddings) es útil: genera la “respuesta hipotética”, embeddea eso y busca. Idea en práctica: mejora recall sin cambiar el índice.

    5) Context compression antes del LLM

    Enviar 10 documentos de 8k tokens es suicida. Comprime:

    • Filtrado selectivo: extrae párrafos con más evidencia.
    • Summarization condensado (con cuidado: pierde citas).
    • Algoritmos de compresión semántica como LLMLingua

    Objetivo: maximizar densidad informativa dentro de la ventana del LLM.

    Criterio para decidir qué añadir (roadmap pragmático)

    No implementes todo a la vez. Sigue este orden iterativo:

    1. Naive RAG. Mide recall@5 y tasa de hallucination.
    2. Si fallan exact matches → añade Hybrid (BM25).
    3. Si falta contexto coherente → añade Parent-Child multi-vector.
    4. Si llega ruido que confunde al LLM → añade Re-ranking.
    5. Si tokens exceden la ventana → añade Context Compression.

    Mide antes y después. No hay excusas.

    Operacional: latencia, coste y caching

    • Re-ranking y cross-encoders aumentan latencia 10x en la etapa de ranking. Mitiga con caching de top-N por query fingerprint.
    • Hybrid search añade coste infra (Elasticsearch + vector DB). Mide Cost/Accuracy.
    • Batch embeddings nocturnos para contenido estático. Mantén refresh policies.
    • Telemetría: trace request → retrieval steps → rerank → LLM call. LangFuse y LangSmith ayudan a visualizar traces (LangFuse, LangSmith).

    Integración con agentes y workflows (n8n)

    Pipeline ejemplo en n8n:

    1. Node: Query Rewrite (LLM pequeño)
    2. Node: Hybrid Search (ES + Pinecone/Qdrant)
    3. Node: Rerank (Cross-Encoder)
    4. Node: Parent Expander + Context Compressor
    5. Node: LLM final (generation)
    6. Node: Post-check (schema validation / guardrails)

    Versiona prompts, registra fingerprints y alertas en drift.

    Referencias operativas

    Implementar RAG avanzado es menos glamour y más disciplina: medir, añadir la capa correcta y repetir. Hazlo así y tu sistema dejará de improvisar respuestas y empezará a dar respuestas que puedes explicarle al CTO.

    Dominicode Labs

    Si trabajas con pipelines de agentes, workflows o IA aplicada, considera explorar integraciones y experimentos prácticos en Dominicode Labs. Es una continuación lógica para prototipos operacionales y pruebas de telemetría.

    FAQ

     

    Respuesta: ¿Por qué combinar BM25 con embeddings?

    BM25 proporciona coincidencias literales útiles para IDs, SKUs y frases exactas; los embeddings capturan intención y sinónimos. El híbrido reduce falsos positivos semánticos y mejora precisión en búsquedas sensibles.

     

    Respuesta: ¿Qué ventaja tiene la indexación parent-child?

    Permite mantener chunks pequeños para alta precisión en matching mientras se conserva contexto amplio subiendo el documento parent al LLM cuando un child es relevante.

     

    Respuesta: ¿Cuándo usar cross-encoders para re-ranking?

    Úsalos cuando el top-N recuperado contenga ruido que provoca hallucinations o respuestas incorrectas. Son adecuados para reducir falsos positivos aunque aumenten latencia y coste.

     

    Respuesta: ¿Qué es HyDE y por qué usarlo?

    HyDE (Hypothetical Document Embeddings) genera una “respuesta hipotética” desde un LLM, la embeddea y busca con esa representación. Mejora recall sin tocar el índice.

     

    Respuesta: ¿Cómo mitigar la latencia al re-rankear?

    Cachea top-N por huella de consulta, ejecuta re-ranking asíncrono donde sea posible y usa cross-encoders solo en escenarios críticos o por lotes nocturnos para contenido estático.

     

    Respuesta: ¿Qué técnicas de compresión de contexto son seguras?

    Filtrado selectivo de párrafos con evidencia, resúmenes condensados con control de citas y algoritmos semánticos como LLMLingua. Ten cuidado: la compresión puede perder citas y detalles verificables.