Tag: AI

  • 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.

  • El futuro de los programadores en un mundo de IA

    El futuro de los programadores en un mundo de IA

    Dejarán de existir los programadores debido a la AI, cuál será el futuro ?

    Tiempo estimado de lectura: 4 min

    • La profesión no desaparece: se transforma hacia orquestación, seguridad y responsabilidad técnica.
    • Habilidades críticas: testeo semántico, control de agentes, observabilidad de LLMs, FinOps y seguridad.
    • Roles emergentes: orquestadores de agentes, AI FinOps, observability y security engineers especializados en IA.

    Dejarán de existir los programadores debido a la AI, cuál será el futuro? No: la profesión no desaparece, se transforma. Lo que muere es la recompensa por saber cerrar un paréntesis. Lo que surge es la demanda por gente que tenga criterio para diseñar, orquestar y responsabilizar una capa de IA dentro de sistemas reales.

    Los LLMs generan código. Bien. Eso no es la mitad del problema; es solo la parte fácil. El verdadero trabajo será asegurar que ese código no rompa la seguridad, no arruine las finanzas del proyecto y funcione 1.000 veces en producción sin alucinar.

    Resumen rápido (lectores con prisa)

    Qué es: La automatización con LLMs transforma el rol de programador hacia orquestación, seguridad y fiabilidad.

    Cuándo usarlo: Al integrar LLMs en sistemas productivos que requieren disponibilidad, coste controlado y seguridad.

    Por qué importa: Implementar IA sin pruebas semánticas, observabilidad y control de costes puede generar fallos graves y gastos inesperados.

    Cómo funciona (resumen): Orquesta agentes, traza prompts/embeddings/tool-calls, aplica tests semánticos y controles financieros por flujo.

    Dejarán de existir los programadores debido a la AI, diagnóstico técnico

    No estamos ante la extinción del oficio, sino ante su re-especialización. La automatización desplaza tareas repetitivas; obliga a los ingenieros a evolucionar hacia roles donde el juicio técnico y la orquestación valen más que teclear rápido.

    Los puntos clave

    • La IA reduce el coste de producción de implementación, no el coste de responsabilidad técnica.
    • El valor pasa de la implementación a la arquitectura, la seguridad y la fiabilidad.
    • Aparecen roles nuevos: orquestadores de agentes, ingenieros FinOps de IA, responsables de observabilidad de LLMs.

    Estos cambios ya son prácticos: n8n y LangChain no son hobbies; son infra para orquestar lógica humana + IA. Pinecone es la memoria cuando el modelo no puede cargar todo el contexto. OpenTelemetry y Arize son los instrumentos para medir lo que antes sólo se infería.

    El nuevo skill set crítico (cinco prioridades)

    Si quieres seguir siendo indispensable, domina estas cinco áreas. No son “buenas ideas”; son requisitos de producción.

    1) Testeo automático inteligente (Evals)

    Los tests string-to-string fallan con LLMs. Necesitas evaluadores semánticos: datasets de respuestas esperadas, pruebas basadas en esquemas (JSON Schema) y LLMs que actúen como juez. Herramientas y patrones: golden datasets, pruebas adversariales y evaluación automática de coherencia y factualidad.

    2) Evaluación de agentes y control de flujo

    Un agente que funciona una vez es un experimento. Uno que opera a escala requiere máquinas de estado, grafos de flujo y guardrails. Usa FSMs, límites de iteración y validaciones por step para evitar loops, fugas de datos o ejecuciones no deseadas.

    3) Observabilidad de LLMs

    La traza del stack ya no es suficiente. Tienes que recolectar: prompt original, embeddings usados (RAG), tool calls, respuesta del modelo, tokens consumidos y latencia por paso. Implementa tracing end-to-end con OpenTelemetry y tableros que correlacionen degradación de calidad con cambios en prompts o datos.

    4) Cost control (FinOps para IA)

    Un bug puede costar miles en una noche. Controla tokens, cachea respuestas recurrentes (Redis), enruta cargas a modelos baratos para operaciones simples y reserva modelos caros solo para razonamientos complejos. Mide coste por petición y ROI por cada flujo automatizado.

    5) Seguridad y prompt injection

    La seguridad ya no es sólo SQLi o XSS. Es impedir que una instrucción de usuario manipule el prompt o que un agente ejecute acciones peligrosas. Aplica mínimo privilegio en cada tool que expongas, valida outputs con esquemas y aisla tokens/credenciales. Considera frameworks de guardrails como NVIDIA NeMo Guardrails y políticas de ejecución restringidas.

    Roles que emergen: quiénes ganan

    • Orquestador de agentes: diseña flujos, define límites y asegura estabilidad.
    • AI FinOps Engineer: controla coste, optimiza rutas de modelos y define SLAs económicos.
    • Observability Engineer para IA: instrumenta trazas y define alertas sobre calidad, no solo sobre latencia.
    • Security Engineer de IA: modela amenazas específicas de LLM y aplica mitigaciones.

    La diferencia entre un “operador” y un “orquestador” será la diferencia entre un puesto reemplazable y uno que aguante la próxima década.

    Qué hacer desde ya (práctico)

    1. Empieza por auditar: ¿qué procesos usan IA y cuánto cuestan en tokens al mes?
    2. Implementa tracing básico: persistir prompts, respuestas y metadatos por petición.
    3. Define 10 pruebas de “smoke” semánticas para tus agentes: respuestas que siempre deben cumplirse.
    4. Añade límites de ejecución y una ruta de escalado humano si el agente falla.
    5. Establece un plan de costes: modelos baratos para lo trivial, modelos caros para lo crítico.

    Cierre — no se acaba aquí

    La IA no borrará a los programadores; los forzará a subir de nivel. Si te niegas a aprender testeo semántico, observabilidad y FinOps para IA, estarás desapareciendo a cámara lenta. Si lo aprendes, pasarás de escribir funciones a diseñar sistemas confiables que realmente automaten trabajo de valor.

    Empieza hoy: instrumenta un flujo con tracing, añade una prueba semántica y pon límites de coste. Lo siguiente será orquestarlo a escala.

    Si trabajas en automatización, agentes o workflows y buscas recursos prácticos para prototipar trazas y pruebas semánticas, consulta Dominicode Labs. Es una continuidad lógica para equipos que quieren pasar de experimentos a pipelines reproducibles y observables.

    FAQ

    Respuesta: No. La profesión se transforma: disminuye el valor de tareas repetitivas y aumenta la demanda de roles que gestionen, orquesten y aseguren sistemas con IA.

    Respuesta: Testeo semántico, control de agentes/flow, observabilidad de LLMs, FinOps para IA y seguridad frente a prompt injection.

    Respuesta: Empieza creando golden datasets de respuestas esperadas, define pruebas basadas en esquemas (JSON Schema) y automatiza evaluaciones usando LLMs como juez y pruebas adversariales.

    Respuesta: Es trazar prompts, embeddings, tool calls, respuestas, tokens y latencias end-to-end para correlacionar degradación de calidad con cambios en datos o prompts.

    Respuesta: Mide coste por petición, cachea respuestas recurrentes, enruta cargas simples a modelos baratos y reserva modelos caros para razonamiento complejo; aplica límites y alertas.

    Respuesta: Aplica mínimo privilegio a tools, valida outputs con esquemas, aísla tokens/credenciales y usa frameworks de guardrails para mitigar prompt injection.

  • Prácticas para crear skills efectivas en agentes

    Prácticas para crear skills efectivas en agentes

    Best Practices for Creating Agent Skills

    Tiempo estimado de lectura: 5 min

    • Diseña SKILL.md como orquestador compacto: no como una enciclopedia; enumera pasos y triggers claros.
    • Externaliza lo frágil: scripts deterministas en scripts/, reglas densas en references/, templates en assets/.
    • Progressive Disclosure (JiT): carga solo archivos cuando surge un trigger explícito.
    • Validación en tres fases con LLMs: discovery, lógica y edge-case testing.

    Introducción

    ¿Quieres que tus agentes dejen de fallar por cosas tontas? La mayoría lo hace porque sus skills son documentación para humanos disfrazada de herramienta para máquinas. Los agentes no leen; ejecutan. Y para ejecutar necesitan reglas claras, rutas exactas y scripts que no improvisen.

    Aquí va la arquitectura práctica que uso cuando diseñamos skills que realmente funcionan en producción.

    Resumen rápido (lectores con prisa)

    Qué es: Un conjunto de reglas, scripts y plantillas organizadas para que un agente tome decisiones deterministas.

    Cuándo usarlo: Al diseñar skills que interactúan con repositorios, migraciones, o tareas automatizadas que requieren reproducibilidad.

    Por qué importa: Evita ambigüedades que causan alucinaciones y resultados inconsistentes.

    Cómo funciona: SKILL.md orquesta; scripts ejecutan validaciones; references/ y assets/ se cargan sólo mediante triggers explícitos.

    Estructura de una skill: la regla de hierro

    skill-name/
    ├── SKILL.md              # Metadatos + instrucciones core (<500 líneas)
    ├── scripts/              # CLIs pequeños para tareas deterministas
    ├── references/           # Reglas densas, cheatsheets, esquemas
    └── assets/               # Templates y archivos estáticos

    SKILL.md es “el cerebro”: orquesta, no enciclopedia. scripts/ ejecuta lo que no puede fallar. references/ y assets/ guardan lo pesado, pero el agente sólo los lee cuando se lo indicas.

    Naming y frontmatter: haz que la skill sea visible

    El agente decide cargar una skill solo por el frontmatter. Si tu nombre y descripción son vagos, la skill es invisible.

    Reglas:

    • name = 1–64 chars, minúsculas, números y guiones. Debe coincidir exactamente con el nombre del directorio.
    • descripción = máximo 1,024 caracteres, en tercera persona e incluye negative triggers.

    Ejemplo práctico:

    name: angular-vite-migrator
    description: Migra proyectos Angular CLI de Webpack a Vite y esbuild. Usar para actualizar builders o reemplazar plugins de Webpack por equivalentes de Rollup. No usar para proyectos React, Svelte o para sólo actualizar la versión de Angular.

    Eso reduce falsos positivos. Punto.

    Progressive Disclosure: carga solo lo necesario

    Los LLMs tienen memoria limitada. Meter 800 líneas de vite.config.ts en el prompt es pedir perdón por las alucinaciones.

    Patrón: JiT (Just-in-Time).

    • SKILL.md enumera pasos altos y dice exactamente cuándo abrir un archivo.
    • Coloca plantillas complejas en assets/ y reglas en references/.
    • Instrucción clara: “Si detectas @angular-builders/custom-webpack en angular.json, abre references/webpack-fallbacks.md”.

    El agente no ve nada hasta que el trigger ocurre. Menos tokens, más precisión.

    Escribe para máquinas: imperativo y pasos numerados

    Las skills son código en lenguaje natural. Escribe en tercera persona, imperativo y con pasos numerados.

    Correcto:

    1. Ejecuta scripts/env-validator.mjs
    2. Si el exit code es 1, reporta: "Node version incompatible. Upgrade required." Termina.

    Incorrecto: “Quizá quieras comprobar la versión de Node…” — frase que confunde y genera ambigüedad.

    Scripts deterministas: no pidas improvisación

    No le pidas al LLM que escriba parsers complejos en cada ejecución. Empaqueta esos parsers y detectores como scripts pequeños y probados en scripts/. El agente los invoca con parámetros y actúa según stdout/stderr.

    Ejemplo de stdout útil:

    CRITICAL: Found legacy CommonJS 'legacy-lib' that uses dynamic require(). Recommendation: add to optimizeDeps.include or shim with esm-adapter. See references/commonjs-guide.md

    Ese mensaje debe permitir al agente decidir el siguiente paso sin adivinar.

    Templates y outputs parseables

    Coloca un template en assets/ (por ejemplo, assets/vite.config.template.ts). Instrucción en SKILL.md:

    • “Copia assets/vite.config.template.ts a vite.config.ts y rellena los placeholders según el mapeo en references/mapping.md.”

    Los LLMs reconocen patrones; darles la plantilla evita salidas rotas y archivos inválidos.

    Validación con LLMs: prueba en tres fases

    Las skills las usarán LLMs, así que valídalas con LLMs.

    1. Discovery Validation

    Pega solo el frontmatter en un LLM limpio. Pide 3 prompts que deben activar la skill y 3 que no. Ajusta la descripción hasta que el modelo acierte.

    2. Logic Validation

    Pasa el SKILL.md y la estructura de archivos. Pide al LLM que actúe como agente y escriba su monólogo paso a paso: qué lee, qué ejecuta, y dónde se ve obligado a adivinar.

    3. Edge Case Testing (Red Team)

    Pide al LLM que te rompa la skill con preguntas concretas: Node antiguo, builders custom, imports dinámicos. Si responde con huecos, rellena referencias y scripts hasta que no queden ambigüedades.

    Ejemplos de fallas comunes y cómo prepararlas

    • CommonJS legacy en esbuild: añade scripts/detect-commonjs.mjs que devuelvan JSON con las dependencias problemáticas y recomendaciones.
    • @angular-builders/custom-webpack en angular.json: stop automatic migration. Instruye a abrir references/webpack-fallbacks.md y proponer un plan híbrido (mantener Webpack para producción, migrar dev a Vite).
    • Entorno Node no compatible: scripts/env-validator.mjs debe chequear process.version y salir con mensaje accionable.

    Cierre con criterio

    Construir skills no es arte ni redacción creativa: es ingeniería. Nombra con precisión, externaliza lo frágil a scripts, usa templates y obliga a los agentes a cargar sólo lo que necesitan. Haz esto y tus agentes dejarán de inventar soluciones —y empezarán a producir resultados reproducibles.

    Reestructura una skill bajo estas reglas hoy y verás cómo el agente deja de improvisar. Esto no acaba aquí; las skills bien diseñadas son la base de la automatización fiable.

    Dominicode Labs

    Para equipos que diseñan workflows y agentes, recursos y experimentos prácticos en automatización y agentes están disponibles en Dominicode Labs. Considera revisarlo como complemento para validar skills y pipelines en entornos reales.

    FAQ

     

    ¿Qué debe contener SKILL.md?

    SKILL.md debe ser el orquestador: metadatos (frontmatter), pasos numerados claros, triggers explícitos sobre cuándo abrir archivos en references/ o assets/, y referencias a scripts/ ejecutables. Mantenerlo por debajo de 500 líneas.

     

    ¿Por qué externalizar parsers en scripts/?

    Porque los parsers y detectores complejos son frágiles si se piden al LLM en cada ejecución. Scripts deterministas devuelven stdout/stderr o JSON que permite decisiones automáticas sin ambigüedad.

     

    ¿Cómo funciona Progressive Disclosure?

    El agente solo carga información adicional cuando un trigger en SKILL.md lo indica (JiT). Así se evita saturar el prompt con archivos largos y se mejora la precisión.

     

    ¿Qué formato deben tener los outputs de los scripts?

    Outputs legibles por máquina: líneas con prefijos (ej. CRITICAL:) o JSON. Deben contener suficiente contexto y una recomendación accionable para que el agente decida el siguiente paso.

     

    ¿Cuándo incluir references/webpack-fallbacks.md?

    Incluirlo cuando detectes @angular-builders/custom-webpack en angular.json. La instrucción en SKILL.md debe ordenar abrir ese archivo y proponer un plan híbrido si aplica.

     

    ¿Cómo validar una skill con LLMs?

    Validación en tres fases: Discovery Validation con solo frontmatter, Logic Validation con SKILL.md y estructura de archivos (monólogo del agente), y Edge Case Testing (Red Team) para cerrar huecos.

  • Implementa Amazon Ads MCP Server para optimizar integraciones publicitarias

    Implementa Amazon Ads MCP Server para optimizar integraciones publicitarias

    Pero, ¿qué es Amazon Ads MCP Server?

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Amazon Ads MCP Server actúa como middleware MCP para exponer la API de Amazon Advertising como herramientas consumibles por agentes IA.
    • Reduce integraciones punto a punto: traduce prompts/llamadas MCP a REST de Amazon con OAuth.
    • Ofrece lectura de estructura, reportes KPI, operaciones CRUD y gestión de pujas (según permisos).
    • Riesgos: latencia, rate limiting, seguridad y alucinaciones operativas del LLM.
    • Flujo recomendado: levantar en testing, comenzar con solo lectura y añadir guardrails para escrituras.
    Pero, ¿qué es Amazon Ads MCP Server? Es la pregunta que están haciendo hoy los equipos que quieren dejar de pelearse con APIs, scripts rotos y automatizaciones que fallan en producción. Aquí tienes una respuesta técnica, práctica y sin ruido.

    Amazon Ads MCP Server es una implementación de middleware que sigue el estándar Model Context Protocol (MCP). Su propósito: exponer la funcionalidad de la API de Amazon Advertising como “herramientas” que un agente de IA (un LLM) puede descubrir e invocar de forma segura y estructurada. En lugar de tener múltiples integraciones punto a punto, tienes una capa de traducción que convierte prompts en llamadas API consistentes.

    Resumen rápido (lectores con prisa)

    Qué es: Un middleware MCP que expone la API de Amazon Advertising como herramientas JSON-RPC para agentes IA.

    Cuándo usarlo: Cuando quieres que un LLM ejecute consultas y acciones sobre advertising-api.amazon.com sin integrar cada endpoint manualmente.

    Por qué importa: Reduce deuda técnica, centraliza permisos y disminuye alucinaciones operativas del LLM.

    Cómo funciona: Cliente MCP → JSON-RPC → MCP Server → REST Amazon (con OAuth) → respuesta JSON al LLM.

    Pero, ¿qué es Amazon Ads MCP Server? — definición técnica y flujo

    Técnicamente, es un servidor que ofrece primitivas MCP (tools, resources) vía JSON-RPC para que un cliente MCP —Claude Desktop, un agente custom o un orquestador tipo n8n con adaptador— hable con advertising-api.amazon.com.

    Flujo resumido

    • Usuario: “Analiza ROAS de las campañas de zapatillas, última semana.”
    • LLM: decide qué herramienta usar (ej. get_campaign_metrics).
    • Cliente MCP: envía la solicitud JSON-RPC al MCP Server.
    • MCP Server: traduce la llamada a la REST de Amazon, añade OAuth (Bearer token), ejecuta y devuelve JSON.
    • LLM: interpreta y genera respuesta o acción.

    Documentación oficial: Documentación oficial

    Anuncio de beta: Anuncio de beta

    Qué expone y para qué sirve (capabilities)

    Una implementación típica ofrece:

    • Lectura de estructura: cuentas, portafolios, campañas, ad groups.
    • Reportes KPI: impresiones, clics, costo, ventas, ROAS, ACOS con filtros temporales.
    • Operaciones CRUD: crear/actualizar campañas y grupos de anuncios.
    • Gestión de pujas y presupuestos (si se habilitan permisos de escritura).
    • Endpoints de facturación y perfil.

    Eso permite que un agente haga tareas de alto valor: detectar anomalías, reequilibrar presupuestos, ejecutar reglas de puja o generar reportes complejos con un único prompt.

    ¿Por qué te importa como equipo técnico?

    Porque cambia el coste de propiedad de una integración. En lugar de mantener docenas de scripts que se rompen cuando Amazon cambia un endpoint, mantienes una capa estable que define qué herramientas están disponibles y cómo usarlas. Ventajas prácticas:

    • Menor deuda técnica.
    • Integración agnóstica del LLM: funciona con Claude, ChatGPT u otros que implementen MCP.
    • Menos alucinaciones: el LLM opera sobre herramientas y metadatos claros.

    Requisitos y ejemplo mínimo de configuración

    Necesitas:

    • Cuenta de desarrollador Amazon Ads y una app registrada.
    • Credenciales OAuth: CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN, PROFILE_ID.
    • Entorno Node.js (v18+) o Python 3.10+ para ejecutar el servidor.

    Ejemplo mínimo (configuración cliente MCP)

    {
      "mcpServers": {
        "amazon-ads-service": {
          "command": "node",
          "args": ["./dist/index.js"],
          "env": {
            "AMAZON_CLIENT_ID": "amzn1.application-oa2-client...",
            "AMAZON_CLIENT_SECRET": "tu_secreto",
            "AMAZON_REFRESH_TOKEN": "tu_refresh_token",
            "AMAZON_PROFILE_ID": "1234567890"
          }
        }
      }
    }

    (El JSON anterior es un trozo de config real que usan clientes como Claude Desktop para lanzar servidores MCP locales.)

    Limitaciones y riesgos que no puedes ignorar

    Esto no es magia. Considera:

    • Latencia: LLM → MCP → API añade retraso. No esperes microsegundos en operaciones complejas.
    • Rate limiting: Amazon impone límites estrictos. Un agente en bucle puede provocar throttling y bloqueos.
    • Seguridad: dar permiso de escritura es peligroso. Audita el código del MCP Server antes de poner credenciales en producción.
    • Alucinaciones operativas: el MCP reduce errores, pero el LLM todavía puede elegir parámetros inadecuados si la especificación de la herramienta es ambigua.
    • Ecosistema joven: muchas librerías y ejemplos están en alpha; prueba y versiona con cuidado.

    Cómo empezar hoy (práctico)

    1. Registra la app en Amazon Advertising y obtén tus credenciales OAuth.
    2. Levanta un MCP Server en un entorno de testing (local o staging).
    3. Conecta tu cliente MCP (Claude Desktop, agente propio o n8n con adaptador).
    4. Ejecuta prompts de solo lectura primero (reportes, métricas).
    5. Añade controles para escrituras: validaciones, límites de cambio y un modo “simulación” antes de aplicar pujas reales.

    Documentación recomendada: Documentación recomendada

    Anuncio y guía inicial: Anuncio y guía inicial

    Conclusión breve

    Amazon Ads MCP Server es la infraestructura que permite a los agentes de IA operar sobre tu stack publicitario con menos fricción y más contexto. No es la bala de plata, pero sí la base para construir agentes de supervisión que detecten anomalías, propongan optimizaciones y, cuando esté permitido, las ejecuten bajo reglas guardadas.

    Empieza en testing, audita todo, y deja que el agente haga lo repetitivo. Lo inteligente —lo que realmente crea ventaja— es diseñar las reglas y guardrails; el resto lo ejecuta la máquina. En el próximo artículo mostraremos un ejemplo práctico conectando MCP Server con n8n y Claude para automatizar una regla de puja segura.

    Puedes profundizar en experimentos y guías prácticas relacionadas con automatización y agentes en Dominicode Labs. Es una continuación lógica para equipos que quieran prototipar flujos MCP y automatizaciones seguras.

    FAQ

    Respuesta

    Amazon Ads MCP Server es un servidor middleware que implementa el estándar MCP para exponer la funcionalidad de la API de Amazon Advertising como herramientas consumibles vía JSON-RPC por clientes MCP y agentes IA.

    Respuesta

    Reduce la deuda técnica al centralizar traducciones y autenticación (OAuth). Evita mantener múltiples scripts frente a cambios de endpoint y define un conjunto claro de herramientas para el LLM.

    Respuesta

    Latencia adicional, riesgo de throttling por rate limits, seguridad de credenciales y posibles alucinaciones operativas del LLM si las herramientas no están bien especificadas.

    Respuesta

    Sí, se pueden habilitar escrituras, pero es de alto riesgo. Audita el código, añade validaciones y pruebas, y usa modos de simulación antes de permitir cambios reales.

    Respuesta

    Necesitas una cuenta de desarrollador Amazon Ads, una app registrada y credenciales OAuth (CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN, PROFILE_ID). Además, un entorno Node.js (v18+) o Python 3.10+ para ejecutar el servidor.

    Respuesta

    Implementa backoff y límites en el agente, monitoriza llamadas y prueba en staging. Evita bucles automáticos que multipliquen peticiones sin control.

    Respuesta

    Clientes como Claude Desktop, agentes custom y orquestadores tipo n8n con adaptador pueden comunicarse vía MCP con el servidor.

    Respuesta

    Consulta la Documentación oficial y el Anuncio de beta para guías y noticias.

  • Cómo evaluar habilidades de agentes AI efectivamente

    Cómo evaluar habilidades de agentes AI efectivamente

    Testing Your AI Agent Skills — GEMINI_API_KEY=your-key npm run eval superlint — –provider=docker –trials=5

    Testing Your AI Agent Skills empieza con un comando. Si tu flujo de trabajo no incluye algo parecido a:

    GEMINI_API_KEY=your-key npm run eval superlint -- --provider=docker --trials=5

    estás confiando en “vibes” y no en ingeniería. Las Skills son código que otros agentes ejecutan. Si no las pruebas, fallan en silencio y rompen cosas.

    Resumen rápido (lectores con prisa)

    Un eval correcto ejecuta la skill en un entorno aislado (Docker), repite la prueba varias veces y valida resultados con un grader determinista. Esto mide tanto capacidad (pass@k) como fiabilidad (pass^k). Automatiza el gate en CI para evitar merges que degraden la calidad.

    Testing Your AI Agent Skills: por qué este comando importa

    Ese comando condensa tres principios no negociables:

    • Aislamiento: --provider=docker ejecuta la skill en un contenedor efímero. Si el agente borra archivos o instala paquetes, no rompe tu máquina.
    • Repetición: --trials=5 reconoce la no-determinismo de los LLMs. Una ejecución no prueba nada; cinco sí dan una métrica.
    • Foco: superlint es la unidad de prueba —una Skill— no el modelo entero. Testear por skill te da trazabilidad y responsabilidad.

    Si quieres ejemplos y un framework listo, clona: skill-eval

    ¿Qué mide un buen eval? (y cómo diseñarlo)

    Un eval efectivo combina tres capas:

    1. Dataset realista

    Usa repositorios con errores reales, no ejemplos limpios. Capturan edge cases.

    2. Ejecución sandboxed

    Docker + skill completa (scripts, assets, references).

    3. Grader determinista

    Código que valida outcomes, no prompts que se autoevalúan.

    Métricas que realmente importan: pass@k y pass^k

    Los LLMs varían. Dos métricas clave:

    • pass@k: ¿lo resuelve al menos una vez en k intentos? Mide capacidad.
    • pass^k: ¿lo resuelve todas las veces en k intentos? Mide fiabilidad.

    Para producción, prioriza pass^k. Recomendación práctica: 90%+ pass^k para skills críticas (migraciones, despliegues, cambios en infra).

    Recuerda la ley compuesta: si cada paso tiene 95% de éxito y encadenas 5 pasos, la probabilidad de éxito compuesto cae a ~77%. Las pruebas end-to-end capturan eso.

    Tipos de graders y cuándo usarlos

    Graders deterministas (script): imprescindibles. Validan artefactos: archivos creados, tests que pasan, DB migrada.

    Graders de rúbrica LLM: útiles para intencionalidad (¿siguió el workflow correcto?). Úsalos con peso menor. Nunca dependas solo de ellos.

    Combina ambos. Pondera, por ejemplo, 0.8 para el grader determinista y 0.2 para la rúbrica.

    Integración CI: Quality Gate para Skills

    No dejes que una PR rompa el comportamiento del agente. Añade esto al pipeline:

    name: Skill Eval
    on:
      pull_request:
        paths: ['skills/', 'tasks/']
    
    jobs:
      eval:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - run: npm ci
          - run: npm run eval my_task -- --trials=5 --provider=docker
            env:
              GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

    Si la tasa de éxito cae bajo el umbral, bloquea el merge. Esto transforma tests en barrera de calidad, no en opción.

    Diagnósticos útiles que debe entregar un eval

    Un buen sistema no solo dice PASS/FAIL. Debe decir por qué:

    Trial 1: FAIL - Agent used 'eslist' (typo) instead of 'eslint'
    Trial 2: FAIL - Ignored extends in .eslintrc; used default rules
    Trial 3: PASS
    Trial 4: PASS
    Trial 5: FAIL - Fixed src/utils.js instead of src/main.js

    Con eso rehaces el SKILL.md: aclaras paths, ajustas templates, añades checks previos.

    Reglas prácticas para diseñar Skills testeables

    • SKILL.md = orquestador, <500 líneas. No cargues reglas densas ahí.
    • Scripts deterministas en scripts/. No pidas al LLM escribir parsers complejos en tiempo real.
    • Assets y references planos. Usa JiT loading: “Si ocurre X, abre references/X.md”.
    • Frontmatter claro para discovery: name exacto, descripción con negative triggers.

    Referencia práctica: skill-eval

    Checklist rápido antes de mergear una skill

    • [ ] Eval pasa 5/5 en provider=docker
    • [ ] pass^5 ≥ 90% para skills críticas
    • [ ] Grader determinista cubre outcomes principales
    • [ ] Transcripts almacenados para debugging
    • [ ] PR bloqueado si la tasa baja

    Cierre: deja de confiar en sensaciones

    Testing Your AI Agent Skills no es un lujo: es el último seguro antes de que tu agente se convierta en riesgo operativo. Ejecuta evals en contenedores, repite pruebas, mide pass^k y automatiza la puerta en CI. Hazlo y tus agentes dejarán de ser promesas para convertirse en herramientas confiables. Esto no acaba aquí: empieza con un eval, recoge datos y depura la skill hasta que el Pass Rate deje de ser una estadística y pase a ser garantía.

    Como continuación natural para equipos que exploran automatización y evaluación de agentes, visita Dominicode Labs para recursos y proyectos experimentales. Encontrarás plantillas y ejemplos que facilitan implementar pipelines de evaluación reproducibles y seguros.

    FAQ

    Respuesta: Docker aísla la ejecución, evitando que la skill modifique el entorno del host. Esto protege la máquina y garantiza reproducibilidad en entornos controlados.

    Respuesta: No hay número mágico, pero --trials=5 es un buen compromiso práctico para capturar no-determinismo. Aumenta k para mayor confianza en pass@k/pass^k.

    Respuesta: El grader determinista debe validar artefactos concretos: archivos creados/actualizados, tests unitarios que pasen, migraciones aplicadas, salidas esperadas y códigos de salida del proceso.

    Respuesta: No. Los graders LLM son útiles para evaluar intención, pero deben tener peso menor. Nunca dependas exclusivamente de evaluaciones subjetivas.

    Respuesta: Añade un job en el pipeline que ejecute el eval con --provider=docker y --trials. Bloquea merges si la tasa de éxito es inferior al umbral establecido.

    Respuesta: Prioriza pass^k para producción (fiabilidad) y usa pass@k como métrica secundaria para capacidad. Objetivo práctico: 90%+ pass^k para operaciones críticas.

    Respuesta: Revisa diagnósticos por trial, ajusta dataset y grader, corrige SKILL.md y scripts deterministas, y reitera hasta mejorar la tasa. Guarda transcripts para depuración.

  • Implementación de IA en producción con Python: patrones efectivos

    Implementación de IA en producción con Python: patrones efectivos

    Python + IA en producción (sin hype)

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Tratar al LLM como servicio predecible: input → validación → procesamiento → output validado → observabilidad.
    • Validación estricta: Pydantic / Instructor para outputs estructurados; fallback rules-based cuando falle la validación.
    • RAG anclado: embeddings + vector DB + prompt que use solo el contexto recuperado para evitar hallucinations.
    • Generación con revisión humana: producir borradores estructurados que reduzcan el trabajo humano al 20–30%.

    Tabla de contenidos

    Introducción

    Python + IA en producción (sin hype) significa integrar modelos de lenguaje como componentes técnicos previsibles: funciones probabilísticas encapsuladas, validadas y monitorizadas. No es “darle un prompt y esperar magia”; es diseñar pipelines que conviertan texto ruidoso en datos accionables, enrutando, extrayendo, recuperando y generando borradores útiles.

    Resumen rápido (lectores con prisa)

    Qué es: integrar LLMs como servicios deterministas y validados para procesos de negocio.

    Cuándo usarlo: cuando los inputs textuales son ruidosos y requieren estructura o enrutamiento automatizado.

    Por qué importa: reduce errores, controla coste y evita entregar contenido no verificado.

    Cómo funciona: pipelines con validación (Pydantic), recuperación anclada (embeddings + vector DB) y revisión humana para entregables finales.

    Python + IA en producción (sin hype): casos y patrones comprobables

    Abajo tienes cuatro patrones que realmente funcionan en empresas: clasificación, extracción, RAG y generación con revisión humana. Cada uno incluye la arquitectura mínima, fragmentos de código y consideraciones operativas.

    1) Clasificación de documentos: el Router Pattern

    Problema: cientos de reglas basadas en keywords que rompen con variaciones de lenguaje.

    Solución: usar un modelo como clasificador determinista (temperature=0) y forzar respuestas válidas contra un Enum. Resultado: enrutamiento a colas (Celery), webhooks (n8n) o routers internos.

    from enum import Enum
    from pydantic import BaseModel
    from openai import OpenAI
    
    class Category(str, Enum):
        SUPPORT = "support"
        BILLING = "billing"
        SALES = "sales"
    
    client = OpenAI()
    
    def classify(text: str) -> Category:
        resp = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role":"system","content":"Responde con una sola de: support, billing, sales"},
                      {"role":"user","content":text}],
            temperature=0
        )
        return Category(resp.choices[0].message.content.strip())

    Determinismo + validación reducen falsos positivos. Docs modelos

    2) Extracción estructurada: Text → JSON fiable

    Problema: OCR/HTML sucio produce texto que no entra directo en una base de datos.

    Solución: definir un esquema con Pydantic y usar una capa que obligue al LLM a devolver ese esquema (Instructor o Structured Outputs de OpenAI). Valida antes de insertar.

    from pydantic import BaseModel, Field
    from instructor import from_openai
    from openai import OpenAI
    
    class Invoice(BaseModel):
        vendor: str
        date: str  # validar con regex si hace falta
        total: float = Field(...)
    
    client = from_openai(OpenAI())
    invoice = client.chat.completions.create(
        model="gpt-4o-mini",
        response_model=Invoice,
        messages=[{"role":"user","content":ocr_text}]
    )

    Instructor: https://github.com/jxnl/instructorPydantic

    Siempre: retry + fallback rules-based si la validación falla.

    3) RAG simple y robusto (Búsqueda semántica anclada)

    RAG práctico = embeddings + vector DB + prompt que obliga a usar solo el contexto recuperado. Evita “hallucinations” anclando la generación a fragmentos verificados.

    Arquitectura mínima:

    • Chunking de documentos (ej. 500 tokens).
    • Embeddings (OpenAI embeddings o HuggingFace).
    • Vector store (ChromaDB o pgvector).
    • Recuperación top-k + prompt con instrucción de uso exclusivo del contexto.
    # obtener top_k documentos -> context
    prompt = f"Usa SOLO este contexto:\n{context}\n\nPregunta: {query}"
    answer = llm.chat(prompt)

    Stack y enlaces: ChromaDB ; pgvector

    Medir: recall de recuperación, latencia y coste por llamada.

    4) Generación de borradores: human-in-the-loop

    No entregues contenido final. Genera estructuras (Markdown/JSON) que reduzcan el trabajo humano al 20–30%.

    Patrón:

    1. Ingesta (diff, transcripción, notas).
    2. LLM genera estructura estandarizada (usando Pydantic).
    3. Enviar borrador a CMS/Notion/Slack para revisión.

    Beneficio: consistencia, velocidad y control de calidad.

    Stack recomendado y consideraciones operativas

    – Modelos/abstracción: usar LiteLLM para poder cambiar provider sin reescribir lógica.

    – Validación: Pydantic + Instructor / Structured Outputs.

    – Vector store: ChromaDB o pgvector (Postgres) según infraestructura.

    – Orquestación: código Python limpio; para workflows visuales, n8n. FastAPI para endpoints.

    – Observabilidad: LangSmith / Helicone para trazabilidad y coste por llamada.

    Criterios de producción

    • Determinismo: temperature=0 para clasificación/extraction.
    • Validación estricta: si Pydantic falla, fallback o alert.
    • Control de costes: medir tokens por request; cache de embeddings y respuestas frecuentes.
    • Fallbacks: reglas deterministas para casos críticos cuando el LLM no valida.
    • Telemetría: loggear prompts, embeddings IDs, latencia y coste por petición.

    Conclusión: ingeniería antes que hype

    Python + IA en producción funciona cuando tratas al LLM como un servicio: input → validación → procesamiento → output validado → observabilidad. Empieza por casos que entreguen ROI medible: clasificación y extracción. Añade RAG cuando la base de conocimiento sea crítica. Usa generación para acelerar humanos, no para sustituirlos.

    Para experimentación interna y pruebas de integración continua, considera también recursos y prototipos en Dominicode Labs. Es una continuación lógica para validar pipelines y plantillas operativas antes de llevarlos a producción.

    Recursos directos

    FAQ

    ¿Por qué usar temperature=0 para clasificación?

    Temperature=0 reduce la aleatoriedad en la generación, promoviendo respuestas deterministas que facilitan la validación contra enums o listas cerradas.

    ¿Cómo garantizar la fiabilidad de la extracción estructurada?

    Definiendo esquemas estrictos (Pydantic), obligando al LLM a devolver un modelo estructurado (Instructor/Structured Outputs) y aplicando validación previa a la inserción; en caso de fallo, usar retries y reglas deterministas.

    ¿Qué métricas son críticas para RAG?

    Recall de recuperación, precisión de respuestas ancladas, latencia end-to-end y coste por petición (tokens + inferencia).

    ¿Cuándo aplicar fallbacks rules-based?

    En casos críticos donde la validación falla o el coste de un error es alto; los fallbacks deben cubrir las rutas esenciales para mantener disponibilidad y consistencia.

    ¿Cómo integrar revisión humana sin frenar el flujo?

    Genera borradores estructurados y metadatos que reduzcan la edición humana al 20–30%, y delega la aprobación final a revisores mediante integraciones con CMS/Slack/Notion para revisión asincrónica.

    ¿Qué vector store elegir entre ChromaDB y pgvector?

    Elegir según infraestructura: ChromaDB para despliegues dedicados y rápidos de prototipo; pgvector si ya usas Postgres y necesitas consolidar datos en una sola plataforma.