Tag: Agentes IA

  • Las 4 habilidades que definen al programador en la era de la IA

    Las 4 habilidades que definen al programador en la era de la IA

    Un cliente me llamó a las 11 de la noche. Me dijo que su equipo llevaba tres semanas con Claude Code y que la productividad se había disparado. Más código por sprint. Menos bugs. Entregas más rápidas.

    Pero había un problema.

    "Bezael, el equipo construye muy rápido. El problema es que construye muy rápido la cosa equivocada."

    Tres semanas generando código con IA. Código correcto, bien estructurado, con tests. Y un producto que no resolvía lo que el cliente necesitaba.

    Ese es el nuevo riesgo para el programador en la era de la IA. No que la IA te reemplace escribiendo código. Sino que la velocidad de producción amplifique el coste de tomar decisiones equivocadas. Antes tardabas un mes en construir algo mal. Ahora tardas tres días.

    Lo que separa a los developers que avanzan de los que se atascan no son sus habilidades técnicas. Son cuatro habilidades del programador en la era de la IA que ningún LLM puede suplir.


    Las habilidades del programador en la era de la IA que este post desarrolla son cuatro: entender el problema real antes de escribir una línea, comunicar la solución a stakeholders no técnicos, especificar con precisión lo que el agente debe construir, y negociar trade-offs cuando los requisitos chocan. Son las habilidades que la IA no puede ejecutar por ti — y las que determinan si su velocidad se convierte en ventaja o en ruido.


    Por qué el código ya no es el cuello de botella del programador en la era IA

    Durante veinte años el cuello de botella en el desarrollo de software fue escribir el código. Encontrar developers. Escalar equipos. Mantener la velocidad.

    Eso ha cambiado.

    Hoy un developer con Claude Code puede producir en un día lo que antes llevaba una semana. Los agentes no se cansan, no tienen bloqueos creativos, y no discuten sobre si usar tabs o spaces. El Stack Overflow Developer Survey 2025 documenta que más del 75% de developers ya usa o planea usar herramientas de IA en su flujo de trabajo — el cambio está aquí.

    Pero los agentes hacen exactamente lo que les pides. Ni más, ni menos. Y si lo que les pides es impreciso, ambiguo, o directamente equivocado, producen código impecable que resuelve el problema equivocado.

    El cuello de botella se ha desplazado. Ya no está en escribir. Está en pensar.


    Habilidad 1: Entender el problema real antes de abrir el editor

    Esta es la más subestimada y la que más dinero cuesta cuando falla.

    Un cliente te dice: "Necesitamos un dashboard con métricas en tiempo real." Un developer técnico abre el editor y empieza a pensar en WebSockets, en qué charting library usar, en cómo estructurar el backend.

    Un developer con criterio hace una pregunta primero: "¿Para qué vas a usar ese dashboard? ¿Quién lo mira y qué decisión toma a partir de lo que ve?"

    Esa pregunta cambia todo.

    A veces el dashboard en tiempo real que pedían era en realidad un email diario con tres métricas. A veces era un CSV que se cargaba en Excel. A veces ni siquiera era un problema de visualización — era un problema de que nadie en la empresa sabía qué datos tenía disponibles.

    Con IA esto se vuelve crítico. Porque ahora la velocidad de producción es tan alta que el coste de empezar en la dirección equivocada es enorme. Construyes tres features completas en el tiempo que antes tardabas en escribir media. Si las tres están mal orientadas, has quemado tres veces más tiempo que antes.

    La habilidad de entender el problema real — no el síntoma que te describen, sino la causa raíz que lo genera — es la que protege todo lo demás.

    No se aprende con más cursos de programación. Se aprende haciendo preguntas incómodas antes de escribir una línea.


    Habilidad 2: Comunicar la solución a quien no es técnico

    El código más elegante del mundo no vale nada si nadie en la empresa entiende qué resuelve ni por qué importa.

    Esto ha sido siempre un problema para los developers. Pero con IA se vuelve más urgente, porque ahora eres capaz de construir cosas más complejas, más rápido, con más capas de abstracción. Y cuanto más complejo es lo que construyes, más difícil es explicarlo a quien toma las decisiones de negocio.

    La comunicación técnica a stakeholders no técnicos no es "simplificar para que lo entienda un niño". Es traducir impacto.

    Un stakeholder no necesita entender cómo funciona una cola de mensajes asíncrona. Necesita entender que gracias a esa cola, el sistema puede procesar diez mil pedidos en paralelo sin que ningún usuario espere más de dos segundos. Eso sí lo entiende. Y eso sí cambia cómo percibe el valor de lo que has construido.

    Esta habilidad también protege tu trabajo. Si tu contribución es invisible para quien decide los presupuestos, eres vulnerable. Si puedes hacer visible el impacto técnico en términos de negocio, eres indispensable.

    Practica esto: después de cada feature que entregues, escribe en dos frases qué problema de negocio resuelve y qué habría pasado sin ella. Si no puedes hacerlo, tienes un problema antes de que alguien externo lo detecte.

    Hay un ejercicio que funciona muy bien para esto: antes de la próxima reunión de sprint, prepara una explicación de lo que estás construyendo en menos de 60 segundos, sin usar términos técnicos. Si necesitas más tiempo o tienes que recurrir al jargon, la feature aún no está suficientemente clara en tu cabeza. Esa claridad — la que te permite explicarla en voz alta — es exactamente la que también necesitas para especificarla bien para un agente.

    Esta habilidad se conecta directamente con la siguiente. Un developer que no puede explicar lo que construye a un humano tampoco puede especificarlo con precisión para una máquina.


    Habilidad 3: Especificar con precisión lo que el agente debe construir

    Esta es la habilidad nueva. La que no existía como tal hace tres años y que ahora es central.

    Los agentes de IA son ejecutores extraordinarios de instrucciones precisas. Son ejecutores pésimos de instrucciones vagas.

    "Construye un sistema de autenticación" puede producir cualquier cosa desde un JWT básico hasta un sistema OAuth completo con múltiples proveedores y gestión de sesiones. El agente hará algo. Y lo que haga puede ser técnicamente correcto y completamente inadecuado para tu contexto.

    Especificar bien significa definir:

    1. Qué hace el sistema — comportamiento concreto, no intención abstracta
    2. Qué NO hace — los límites son tan importantes como las funcionalidades
    3. Bajo qué restricciones — tecnología, rendimiento, compatibilidad, seguridad
    4. Cómo se valida que está correcto — criterios de aceptación verificables

    Si quieres entender mejor el perfil completo del developer que trabaja con agentes en producción, el post sobre qué es un Agentic Engineer cubre ese rol con detalle. La especificación es su primer requisito.

    Llevo varios años aplicando una metodología para esto que llamo Spec-Driven Development. La idea es que antes de que el agente escriba una línea, tienes un documento que responde esas cuatro preguntas. No un documento largo ni burocrático — uno preciso. El Libro SDD documenta este proceso completo, desde cómo estructurar la especificación hasta cómo convertirla en tareas que un agente puede ejecutar sin desviarse.

    La diferencia entre un developer que especifica bien y uno que no lo hace no se mide en velocidad. Se mide en cuánto código hay que tirar a la basura al final de cada sprint.


    Habilidad 4: Negociar trade-offs cuando los requisitos chocan

    Los requisitos siempre chocan. Siempre.

    "Quiero que sea seguro, rápido, barato, flexible y que esté listo para el martes." No puedes tener las cinco cosas. Nunca has podido. Pero antes la conversación sobre qué sacrificar era más lenta porque construir era más lento. Ahora, con la velocidad que da la IA, la presión para tomarlo todo aumenta.

    Un developer que sabe negociar trade-offs no es el que cede ante la presión del cliente. Es el que hace explícito el coste de cada decisión y ayuda a quien decide a entender qué están eligiendo realmente.

    "Si priorizamos velocidad de lanzamiento, el sistema no va a escalar bien por encima de diez mil usuarios. Podemos lanzar en dos semanas con esa limitación asumida, o lanzar en seis semanas con una arquitectura que aguante cien mil. ¿Qué es más importante ahora mismo para el negocio?"

    Esa conversación requiere que el developer entienda el negocio suficientemente bien como para hacer la pregunta correcta. Requiere que sepa comunicar la implicación técnica en términos de impacto. Y requiere que tenga la seguridad de plantear la conversación antes de que los problemas aparezcan en producción.

    Con agentes de IA esto se vuelve más delicado porque la velocidad de implementación hace que sea tentador no tener esa conversación. "Lo construimos rápido, si no funciona lo cambiamos." Pero cambiar una decisión arquitectural después de que cuatro features dependen de ella no es barato, aunque la IA escriba el código.

    En el curso Construye con IA dedicamos una parte específica a cómo estructurar estas conversaciones antes de empezar a generar código — porque los errores más costosos no son de sintaxis, son de dirección.


    Las habilidades del programador que la IA no puede reemplazar

    La IA escribe código. Lo depura. Lo refactoriza. Lo documenta. Lo testea.

    No puede entrar a una reunión y detectar que lo que el cliente pide en realidad responde a un miedo que no ha verbalizado. No puede leer el contexto político de una organización para entender por qué un requisito existe. No puede mirar los ojos de un stakeholder y saber que cuando dice "necesitamos esto para el viernes" en realidad está diciendo "si esto no sale el viernes, me cuesta el trabajo".

    Esas lecturas son humanas. Y en un entorno donde el código se genera en segundos, son el verdadero diferencial.

    Los developers que van a crecer en los próximos años no son los que más saben de LLMs. Son los que combinan criterio técnico con las habilidades de comunicación, especificación y negociación que hacen que ese criterio tenga impacto.


    El developer que va a sobrevivir a la IA

    No es el que sabe más frameworks.

    No es el que tiene mejores prompts para Claude.

    Es el que puede entrar en una sala con personas técnicas y no técnicas, entender lo que realmente está en juego, definir con precisión lo que hay que construir, y explicar con claridad por qué ciertas cosas no se pueden tener al mismo tiempo.

    Este cambio de rol — de ejecutar tareas a tomar decisiones con criterio — es lo que ya analizamos en profundidad en el post sobre el programador que se convierte en product builder. Las cuatro habilidades de este post son el motor que hace posible ese salto.

    La IA amplifica la velocidad de ejecución. Las cuatro habilidades de las que hablamos hoy amplifican la calidad de las decisiones. Y en software, las decisiones siempre cuestan más que el código.

    En Dominicode Labs trabajamos estos temas con developers que están construyendo con IA en proyectos reales — no ejercicios de academia, sino productos con usuarios, deadlines, y stakeholders que necesitan respuestas los lunes por la mañana.

    Si quieres empezar hoy, elige la habilidad que sabes que tienes más floja de las cuatro y pasa esta semana ejerciéndola deliberadamente. Una conversación con un stakeholder. Un documento de especificación antes de abrir el editor. Una pregunta incómoda que no has hecho todavía.

    El código lo escribe la IA. El criterio lo pones tú.


    Preguntas frecuentes

    ¿Estas habilidades sustituyen al conocimiento técnico profundo?
    No, lo complementan. Sin base técnica sólida no puedes especificar bien ni negociar trade-offs con conocimiento de causa. Lo que cambia es que el conocimiento técnico ya no es suficiente por sí solo — necesitas combinarlo con estas capacidades para que tenga impacto real. Un developer que solo sabe programar pero no puede comunicar ni especificar ni negociar tiene cada vez menos diferencial frente a un agente de IA.

    ¿Cómo se aprende a especificar para agentes de IA si nunca lo he hecho?
    Empieza por escribir, antes de cualquier tarea, un documento de dos párrafos: uno con lo que el sistema debe hacer y uno con lo que no debe hacer. Con ese ejercicio simple ya estás especificando. A medida que lo practiques, irás añadiendo restricciones, criterios de aceptación y contexto. La metodología Spec-Driven Development es un marco más completo para esto, documentado en el Libro SDD.

    ¿Estas habilidades son más importantes para freelancers que para developers en empresa?
    Son importantes en los dos contextos, pero de formas distintas. El freelance que no sabe comunicar ni negociar pierde clientes. El developer en empresa que no sabe hacer estas cosas se queda estancado en roles de ejecución y ve cómo los que ascienden son los que saben tener las conversaciones difíciles. En ambos casos, la consecuencia de no desarrollarlas es la misma: invisibilidad.

    ¿La velocidad que da la IA no hace que estos trade-offs sean menos importantes porque "se puede cambiar todo fácilmente"?
    Es una trampa común. Sí, la IA acelera la implementación. Pero hay decisiones — de arquitectura, de modelo de datos, de contratos de API — que una vez tomadas son costosas de cambiar aunque el código lo escriba un agente.

    Si tu base de datos está mal modelada, reescribir las queries con IA no resuelve el problema. El coste de las malas decisiones estructurales no ha bajado con la IA.

    Lo que ha bajado es el coste de implementar la decisión, buena o mala. Eso amplifica el impacto de decidir bien tanto como el de decidir mal.

    ¿Existe algún perfil técnico donde estas habilidades no importan?
    Si trabajas en investigación pura, en open source sin usuarios directos, o en roles muy especializados de bajo nivel donde el contacto con stakeholders es mínimo, el peso relativo de estas habilidades es menor. Pero para la mayoría de developers que trabajan en productos, servicios o consultoría — que es la mayoría — estas cuatro capacidades son cada vez más determinantes para el crecimiento profesional.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Proyecto greenfield con SDD: spec global + slices verticales

    Proyecto greenfield con SDD: spec global + slices verticales

    Hace unas semanas un developer del canal me contó lo que había pasado en su último proyecto.

    Seis horas. Eso tardó en planificar un proyecto greenfield con SDD usando slices verticales. Tenía un spec global, features bien definidas, tareas granulares. Parecía perfecto.

    Ejecutó el primer slice con su agente IA. La app funcionaba. Autenticación, flujo de datos, navegación — todo correcto.

    Y era completamente gris. Sin estilos. Sin diseño. Una interfaz que parecía sacada de 1998.

    No había especificado nada sobre la UI en su spec. Ni colores, ni componentes, ni sistema de diseño. El agente hizo exactamente lo que se le pidió: implementar la lógica. Y lo hizo bien.

    El problema no era el agente. Era el spec.

    El error que nadie te dice sobre SDD en proyectos nuevos

    Spec-Driven Development (SDD) es una metodología en la que cada feature comienza con un documento de especificación estructurado — el spec — antes de escribir código. El spec define qué hace la feature, cómo se ve, y qué criterios debe cumplir para considerarse completa.

    Cuando descubres SDD, la primera intuición es clara: especifica todo antes de escribir una línea de código. Visión, usuarios, funcionalidades, arquitectura, flujos.

    Y esa intuición es correcta… pero incompleta.

    Hay dos errores que se cometen casi siempre en un proyecto greenfield con SDD:

    El primero es intentar especificar el proyecto completo antes de tocar el teclado. Un spec monolítico de 40 páginas que detalla hasta la última feature antes de que exista una sola línea de código. Es atractivo. Se siente seguro. Y casi siempre es un error.

    El segundo es lo que le pasó a ese developer: especificar las features en términos de lógica y flujos, pero olvidar que las features tienen una cara visible. Que los usuarios las ven. Que el diseño no es una capa que se añade al final — es parte de la feature.

    Ambos errores llevan al mismo resultado: rediseño tardío, deuda técnica, y la sensación de que SDD no funciona cuando el problema real es la estrategia, no la metodología.


    La estructura que sí funciona: spec global ligero + slices con UI

    La solución tiene dos capas. Una sesión corta de spec global que define las reglas del juego, y luego un ciclo de feature-por-feature donde cada spec incluye explícitamente la UI.

    Capa 1: El spec global ligero

    Este documento no especifica features. Especifica el contexto en el que todas las features van a vivir. Se hace una sola vez, en una sola sesión, y no debería tomar más de 45 minutos.

    # Spec Global — [Nombre del proyecto]
    _Versión: 1.0 | Fecha: YYYY-MM-DD_
    
    ## Visión
    [Una sola frase que describe qué es el producto y para quién.]
    
    ## Stack técnico
    - Frontend: Angular 22 con Signals
    - Backend: NestJS + Supabase
    - Estilos: Tailwind CSS v4
    - Testing: Jest + Testing Library
    
    ## Sistema de diseño
    - Librería de componentes: Angular Material / PrimeNG / custom
    - Paleta de colores: primario #1A73E8, fondo #F8FAFC, texto #0F172A
    - Tipografía: Inter, base 16px
    - Espaciado: escala de 4px (4, 8, 12, 16, 24, 32, 48...)
    - Breakpoints: sm 640px / md 768px / lg 1024px / xl 1280px
    
    ## Convenciones de arquitectura
    - Estructura: feature-based (cada feature es un módulo independiente)
    - Estado global: NgRx Signal Store
    - Llamadas HTTP: Resource API (Angular 22)
    - Validación: Zod en schemas compartidos
    
    ## Decisiones técnicas ya tomadas
    - Autenticación: Supabase Auth (no reinventar)
    - Despliegue: Vercel (frontend) + Railway (backend)
    - No usar: Redux clásico, Class Components, módulos NgModule legacy
    
    ## Features planificadas (sin detallar)
    1. Autenticación
    2. Dashboard principal
    3. Gestión de proyectos
    4. Reportes
    

    Eso es todo. No más. El spec global no detalla cómo funciona cada feature — solo establece las reglas que todas van a respetar.

    Lo más importante de ese documento son las secciones de sistema de diseño y convenciones de arquitectura. Son el contrato que el agente va a respetar en cada feature. Si no las defines aquí, las decide él — y probablemente no va a coincidir con lo que tienes en la cabeza.

    Capa 2: El spec de cada feature — con sección UI obligatoria

    Aquí está el cambio que lo transforma todo. Cuando vas a implementar una feature, escribes su spec detallado en ese momento, no antes. Y ese spec siempre incluye una sección de UI/UX.

    # Feature 1: Autenticación
    _Contexto: spec global v1.0 | Estado: en implementación_
    
    ## Qué hace
    Permite al usuario crear cuenta, iniciar sesión y recuperar contraseña.
    Usa Supabase Auth. No hay lógica de autenticación propia.
    
    ## Flujos principales
    1. Registro: email + contraseña → verificación por email → redirect a dashboard
    2. Login: email + contraseña → redirect a dashboard (o a la ruta que intentaba visitar)
    3. Recuperación: email → link con token → nueva contraseña → login
    
    ## UI/UX (obligatorio)
    - Layout: columna centrada, max-width 400px, padding 24px
    - Componentes a usar: InputField, Button, Alert — todos del sistema de diseño global
    - Estados visuales a implementar:
      - Loading: botón con spinner, campos desactivados
      - Error: Alert rojo con mensaje específico (no "algo salió mal")
      - Éxito: redirect inmediato, sin pantalla intermedia
    - Mobile first: el form debe funcionar bien en 320px
    - No inventar componentes nuevos — usar los del spec global
    
    ## Criterios de aceptación
    - [ ] El usuario puede registrarse con email válido
    - [ ] El usuario recibe email de verificación
    - [ ] El usuario puede iniciar sesión y llega al dashboard
    - [ ] Los estados de loading y error son visibles
    - [ ] El form es usable en móvil
    
    ## Lo que NO hace esta feature
    - No maneja OAuth (Twitter, Google) — queda para v2
    - No maneja roles de usuario — eso es responsabilidad del dashboard
    

    La sección UI/UX no es opcional. Es donde especificas exactamente qué tiene que ver el usuario cuando interactúa con esta feature. Si la omites, el agente tomará esa decisión por ti, y probablemente tomará la decisión más rápida, no la más correcta.


    Spec total upfront vs spec incremental — la comparativa real

    La tentación de escribir el spec completo del proyecto antes de arrancar tiene sentido desde afuera. La realidad es diferente.

    Spec total upfront Spec incremental (global ligero + features)
    Tiempo inicial 2-3 días o más 45 min (spec global) — hasta 20× más rápido para arrancar
    Riesgo Alto — cambias de opinión cuando ves el código real Bajo — ajustas cada feature antes de implementarla
    UI/UX Probablemente omitida o abstracta Concreta en cada feature, con contexto real
    Consistencia Dependes de que el spec inicial fuera perfecto El spec global garantiza coherencia entre features
    Deuda de redesign Alta — aparece cuando el 80% del código ya existe Baja — se elimina en cada ciclo de validación visual
    Útil con agentes IA Solo si el agente tiene memoria perfecta (no la tiene) Sí — cada prompt incluye contexto concreto y actualizado

    El spec incremental no significa improvisación. Significa que el contexto que tienes cuando implementas la feature 4 es mejor que el que tenías antes de escribir una sola línea de código. Y ese contexto — los componentes que ya existen, las decisiones que ya se tomaron, los problemas que ya aparecieron — enriquece el spec de la siguiente feature.

    Este enfoque es una variación de la Vertical Slice Architecture documentada por Jimmy Bogard, aplicada al contexto de specs con agentes IA.

    El rediseño tardío no ocurre porque el spec sea incremental. Ocurre porque no hay spec en absoluto.


    El ciclo de trabajo en un proyecto greenfield SDD

    El flujo que funciona es simple, y se repite para cada feature:

    1. Escribe el spec de esa feature (con sección UI incluida)
    2. Dáselo al agente como contexto completo
    3. Implementa
    4. Valida visualmente antes de marcar como hecho
    5. Usa lo aprendido para enriquecer el spec de la siguiente feature

    El paso 4 es crítico y muchos lo saltan. Validar visualmente significa abrir el navegador, probar el flujo como lo haría un usuario real, y confirmar que los estados de loading, error y éxito se ven como los especificaste. No basta con que los tests pasen.

    Si en el paso 4 descubres que algo no se ve bien, arréglalo antes de avanzar. El coste de arreglar un componente mal implementado en la feature 1 es mínimo. El coste de arreglar el mismo patrón cuando ya está repetido en las features 1, 3, 5 y 7 es considerable.


    Lo que cambia cuando tienes el spec global

    El spec global tiene un efecto que no es obvio hasta que lo usas en producción.

    Cuando llegas a la feature 4, el agente tiene contexto. Sabe que los inputs van con Tailwind, que el estado global es NgRx Signal Store, que los errores se muestran con el componente Alert del sistema de diseño. Si estás usando Angular 22, también puedes aprovechar la Resource API para centralizar las llamadas HTTP en el spec desde el principio — sin que el agente invente su propio patrón. No lo tienes que repetir en cada prompt.

    Y cuando llega alguien nuevo al proyecto — o cuando tú mismo vuelves al código tres meses después — entiende en 10 minutos las decisiones que se tomaron y por qué.

    Eso no lo da el código. Lo da el spec.

    Si quieres profundizar en la metodología completa, en el libro de Spec-Driven Development tienes el framework completo: cómo estructurar specs, cómo trabajar con agentes IA de forma efectiva, y los patrones que se usan en proyectos reales de producción.


    La UI no es una capa. Es un contrato.

    El error del developer que me escribió no fue usar SDD. Fue asumir que SDD significa especificar todo el proyecto antes de arrancar.

    SDD significa especificar lo suficiente, en el momento correcto, con el nivel de detalle correcto. El spec global define el campo de juego. El spec de cada feature define las reglas de ese momento.

    Y la UI no es una capa que se añade al final. Es parte del contrato de cada feature.

    Si quieres ver este flujo en acción — desde el spec hasta el commit — en el curso Construye con IA: De la Idea al Producto aplicamos exactamente esta metodología: spec global, slices verticales, validación visual antes de avanzar. Con agentes IA reales, en proyectos que no son de juguete.

    Y si prefieres el formato comunidad, en Dominicode Labs compartimos los specs reales de los proyectos que construimos juntos — con las decisiones que se tomaron y las que se descartaron.

    El spec no te quita velocidad. Te quita el coste de arreglar lo que nadie especificó.


    FAQ

    ¿Cuánto tiempo debería tardar el spec global de un proyecto real?

    Entre 30 y 60 minutos. Si tardas más, estás especificando features en el spec global, y eso no es su función. El spec global define el contexto y las reglas. Las features se detallan una a una cuando llega su turno.

    ¿Es obligatoria la sección UI/UX en el spec de cada feature?

    En proyectos con interfaz visible, sí. Si estás construyendo una API sin frontend, la sección UI/UX no aplica, pero deberías incluir una sección de contratos de API: endpoints, tipos de respuesta, códigos de error. El principio es el mismo: especifica todo lo que el agente necesita para no tomar decisiones que tú deberías tomar.

    ¿Cómo manejo las features que dependen de otras que aún no están implementadas?

    En el spec de la feature con dependencia, añades una sección “Asunciones” que documenta qué esperas de las features previas. Si la feature A aún no existe, especificas el contrato que A debería cumplir — y cuando implementes A, ese contrato ya está documentado. Es una forma de diseño by contract que funciona muy bien con agentes.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Qué es un agent harness: la anatomía del sistema que rodea al LLM

    Qué es un agent harness: la anatomía del sistema que rodea al LLM

    En AI Engineer 2026, Tejas Kumar (IBM) hizo algo incómodo delante de cientos de ingenieros: cogió GPT-3.5 Turbo — un modelo de 2023, una antigualla — y le pidió completar una tarea con herramientas. El agente falló. Y no solo falló: mintió. Dijo “he votado” sin haber votado. La tool call nunca se ejecutó.

    Entonces hizo lo interesante. No tocó el prompt ni una vez. No cambió de modelo. Solo añadió piezas alrededor — lo que hoy llamamos un agent harness: límites de pasos, un paso de verificación determinista, un handler de login que no dependía del LLM. Mismo modelo viejo, misma tarea. El agente la completó.

    Entender qué es un agent harness — qué piezas lo componen y por qué el modelo es la parte más pequeña del sistema — es probablemente la habilidad más rentable que puedes desarrollar como developer este año.

    La charla de Tejas ya pasa de 132.000 visualizaciones. Martin Fowler publicó sobre harness engineering. LangChain publicó “The Anatomy of an Agent Harness”. MongoDB lo resumió en una frase: el LLM es la parte más pequeña de tu sistema de agentes. Esto no es una moda de Twitter. Es la disciplina consolidándose.

    Y como dijo Tejas: 2025 fue el año de los agentes. 2026 es el año de los harnesses.

    Qué es un agent harness, sin humo

    La definición de Tejas es la mejor que he escuchado: el harness es todo lo que rodea al modelo y le da anclaje en la realidad.

    La metáfora es literal. El arnés de un escalador lo ancla a algo estable: si resbala, no cae. El arnés de un perro evita que se desboque detrás de la primera ardilla. El harness de un agente hace las dos cosas: ancla al modelo a tu sistema real y evita que se desboque.

    ¿Por qué importa tanto? Por una asimetría brutal de control. El modelo es una caja negra que alquilas por tokens. No puedes abrirla, no puedes depurarla, no puedes garantizar nada sobre ella. El harness es la parte que tú controlas al cien por cien. Si quieres fiabilidad — y en producción no hay otra opción — la fiabilidad vive en el harness, no en el modelo.

    Ya escribí sobre el harness desde el lado del usuario en Harness Engineering con Codex de OpenAI: cómo configurar AGENTS.md, modos de aprobación, ese terreno. Este post va por el otro lado. Vamos a abrir el capó.

    La anatomía: las 6 piezas de un harness

    Todo harness serio — Claude Code, Codex, Pi, el que construyas tú — tiene estas seis piezas. Cambian los nombres y la sofisticación, no la anatomía.

    1. Tool registry

    El catálogo de herramientas que el modelo puede invocar: leer archivos, ejecutar comandos, llamar APIs. Sin tools, el modelo solo genera texto. Las tools son sus manos.

    2. El modelo

    Sí, es una pieza más. Una de seis. No el sistema entero. Interiorizar esto cambia cómo diseñas.

    3. Gestión de contexto

    La ventana de contexto se llena, y un contexto saturado degrada al modelo mucho antes de reventar el límite de tokens. El harness necesita primitivas de compaction: resumir lo viejo, descartar lo irrelevante, conservar lo esencial. En Hacker News los devs ya lo dicen abiertamente: la gestión de contexto es hoy un cuello de botella mayor que la calidad del modelo.

    4. Guardrails

    Límites duros que el modelo no puede negociar: máximo de pasos, máximo de mensajes, qué comandos requieren aprobación. Son el código determinista que evita que un agente confundido queme tu presupuesto de API en un bucle infinito.

    5. El agent loop

    El corazón: el ciclo que llama al modelo, ejecuta sus tool calls, le devuelve los resultados y repite hasta terminar. Y alrededor, el “loop sobre el loop”: qué pasa cuando el ciclo interno acaba — ¿se verifica? ¿se reintenta? ¿se escala a un humano? Si quieres ver esta pieza llevada a producción, ya escribí sobre cómo implementar un loop de agente efectivo para LLM en producción.

    6. El verify step determinista

    La pieza que casi todo el mundo omite y la que más fiabilidad compra. Cuando el agente dice “he terminado”, no le crees: lo compruebas con código. ¿Existe el archivo? ¿Pasan los tests? ¿Devuelve 200 el endpoint? Verificación sin LLM. Sobre esta pieza volvemos luego, porque es la moraleja de la demo de Tejas.

    Pi: un harness de cristal

    El problema de estudiar harnesses con Claude Code o Codex es que son opacos. Usas el harness, pero no puedes leerlo.

    Por eso el mejor ejemplo pedagógico ahora mismo es Pi (badlogic/pi-mono en GitHub, hoy bajo la org Earendil). Lo creó Mario Zechner y hoy lo desarrolla junto a Armin Ronacher — sí, el creador de Flask y Jinja2 — y lleva más de 61.000 stars. Es un coding agent de terminal con un harness mínimo a propósito: puedes leerlo entero en una tarde y entender cada pieza.

    Recorre la anatomía con Pi en la mano:

    Tool registry: cuatro tools. Read, Write, Edit, Bash. Nada más. Y con eso un coding agent funciona, porque casi todo lo que hace un developer se reduce a leer, escribir, editar y ejecutar.

    Agent loop: un ReAct mínimo. Streamea la respuesta del modelo, comprueba si hay tool calls, las ejecuta, mete los resultados en el contexto y repite. En pseudocódigo (ilustrativo, no el código real de Pi):

    // Ilustrativo: la forma del loop ReAct de un harness mínimo
    while (true) {
      const response = await model.stream(context);
    
      if (response.toolCalls.length === 0) break; // terminó
    
      for (const call of response.toolCalls) {
        const result = await tools.execute(call); // Read | Write | Edit | Bash
        context.push(toolResult(call, result));
      }
    }
    

    Eso es. Esa docena de líneas es el corazón de todo coding agent que has usado. El resto del harness existe para que ese loop no se estrelle contra la realidad.

    Contexto: Pi inyecta una sola línea de descripción por capacidad instalada. Minimalismo deliberado: contexto pequeño, modelo más fino.

    Extensibilidad: aquí está la filosofía de Pi. Lo que otros agentes traen de fábrica, en Pi lo construyes tú — extensiones en TypeScript con acceso a tools, comandos, atajos, eventos y la TUI completa, más skills, prompt templates y themes. El core no engorda. Y esa decisión lo convirtió en plataforma: tanto Flu (del equipo de Astro) como OpenClaude están construidos sobre Pi.

    Si quieres tocarlo: npm install -g @earendil-works/pi-coding-agent y a leer código.

    La lección del verify step

    Vuelve a la demo de Tejas, porque ahí está la tesis del post.

    GPT-3.5 Turbo sin harness: el agente miente. Afirma haber hecho cosas que no hizo. Y ojo — no es maldad, es la naturaleza del modelo: genera el texto más plausible, y “ya he votado” es texto plausible.

    La solución no fue prompt engineering. Fue un guardrail más una verificación determinista:

    // Ilustrativo: guardrail + verify step alrededor del loop
    const MAX_STEPS = 15;
    
    for (let step = 0; step < MAX_STEPS; step++) {
      await agentLoop(task, context);
    
      if (await verify(task)) return "done"; // código, no LLM:
      // ¿existe el registro? ¿pasó el test? ¿respondió 200?
    
      context.push("La verificación falló. La tarea NO está completa. Continúa.");
    }
    throw new Error("Máximo de pasos alcanzado: escalar a humano");
    

    Con eso, el modelo de 2023 deja de mentir. No porque sea más listo: porque el harness no le permite declarar éxito sin pruebas. El verify step convierte "confío en lo que dice el agente" en "compruebo lo que hizo el agente". Esa es toda la diferencia entre demo y producción.

    Qué significa esto para ti

    Que el valor se está moviendo. De saber elegir modelo a saber construir el sistema alrededor del modelo.

    Con un buen harness, un modelo barato u open source — GPT-OSS, Qwen3 — llega muchísimo más lejos de lo que crees. La demo de Tejas lo prueba con un modelo de hace tres años. Inviertes una vez en el harness (código tuyo, determinista, testeable, versionado en git) y cada modelo nuevo que conectes hereda esa fiabilidad gratis.

    Y hay otra consecuencia que me toca de cerca: un harness se especifica, no se improvisa. Decidir guardrails, criterios de verificación y límites del loop antes de escribir código es exactamente el enfoque Spec-Driven que cuento en el libro de SDD. Un agente sin spec es un loop sin guardrails.

    Si quieres practicar este músculo construyendo productos reales con agentes, es la lógica que aplicamos de principio a fin en el curso Construye con IA: de la idea al producto, con el sistema — no la fe en el modelo — sosteniendo el resultado.

    Tu tarea para hoy es concreta: clona Pi, abre el loop y léelo. Es la mejor clase de arquitectura de agentes disponible, y es gratis.

    Lo que viene: Flu

    Este post es la pieza 1 de la serie "El año de los harnesses".

    En la pieza 2 subo de nivel: video en YouTube sobre Flu, el framework harness del equipo de Astro, construido precisamente sobre Pi. Si Pi es el harness mínimo para entender la anatomía, Flu es lo que pasa cuando un equipo serio construye encima de esa base para producción.

    Suscríbete al canal de YouTube de Dominicode para no perdértelo. Y si quieres discutir tu propio harness con otros developers que están construyendo con agentes, en Dominicode Labs es la conversación de cada semana.

    El harness es el andamiaje; lo que envuelve es otra cosa. La distinción entre las dos anatomías —y qué es un agente de IA exactamente— la desarrollo en la guía del cluster.

    Preguntas frecuentes

    ¿Qué es un agent harness?

    Es todo el sistema que rodea al LLM y le da anclaje en la realidad: el tool registry, el agent loop, la gestión de contexto, los guardrails y la verificación determinista. El modelo genera decisiones; el harness las ejecuta, las limita y las comprueba. Es la parte del sistema de agentes que tú controlas.

    ¿Cuál es la diferencia entre un harness y un framework de agentes?

    Un framework de agentes (LangChain, CrewAI) te da abstracciones para orquestar LLMs: chains, grafos, equipos de agentes. El harness es más fundamental: es la pieza concreta que conecta un modelo con la realidad — loop, tools, guardrails, verificación. Todo framework de agentes contiene un harness dentro; pero puedes escribir un harness completo en cien líneas sin ningún framework, como demuestra Pi.

    Agent harness Framework de agentes
    Qué resuelve Conectar un modelo con la realidad de forma fiable Orquestar uno o varios agentes entre sí
    Nivel de abstracción Bajo: loop, tools, guardrails, verify Alto: chains, grafos, roles, equipos
    Ejemplos Pi, el harness de Claude Code, Flu LangChain, CrewAI, LangGraph
    Cuándo usarlo Siempre — todo agente corre dentro de uno Cuando orquestas flujos multi-agente complejos

    ¿Necesito construir mi propio harness o uso uno existente?

    Para programar día a día, usa uno existente (Claude Code, Codex, Pi). Construye el tuyo cuando el agente sea parte de tu producto: ahí necesitas controlar guardrails, verificación y costes, y un harness propio mínimo suele ganar a un framework genérico. En cualquier caso, lee uno entero al menos una vez — Pi es la opción perfecta — porque te cambia cómo usas todos los demás.

    ¿Qué es Pi (pi coding agent)?

    Pi es un coding agent open source de terminal creado por Mario Zechner y desarrollado hoy junto a Armin Ronacher (creador de Flask), con más de 61.000 stars en GitHub. Su harness es mínimo a propósito: 4 tools (Read, Write, Edit, Bash) y un loop ReAct que cabe en una pantalla. Todo lo demás se añade con extensiones TypeScript, skills y templates. Es la base sobre la que se construyen Flu y OpenClaude, y el mejor harness para estudiar porque puedes leerlo completo.

    ¿Por qué un modelo viejo con harness supera a un modelo nuevo sin harness?

    Porque los fallos típicos de un agente — declarar éxito sin haber hecho el trabajo, entrar en bucles, perder el contexto — no se arreglan con más inteligencia, se arreglan con estructura: guardrails que cortan los bucles y un verify step determinista que no acepta "ya está" sin pruebas. En la demo de Tejas Kumar (AI Engineer 2026), GPT-3.5 Turbo pasó de mentir a completar la tarea solo añadiendo harness, sin tocar el prompt.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Cómo monitorear efectivamente agentes de IA en producción

    Cómo monitorear efectivamente agentes de IA en producción

    Cómo monitorear tus agentes de IA en producción

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Instrumentación desde el día 0: traces y spans que representen sesiones completas y decisiones individuales.
    • Métricas triples: rendimiento (TTFT, percentiles), coste (tokens/coste por span/sesión) y calidad (feedback y señales automáticas).
    • Elegir plataforma según arquitectura: LangSmith para stacks centrados en LangChain; Langfuse (+ ClickHouse) para portabilidad y escala.
    • Cultura operacional: versionado de prompts, tests de regresión y despliegue progresivo son obligatorios.

    Cómo monitorear tus agentes de IA en producción debería ser la primera conversación del equipo antes de lanzar una beta. Si no instrumentas traces, spans, costes y calidad desde el día 0, tu siguiente sprint será apagar fuegos y explicar facturas inexplicables.

    Este artículo explica el diseño mínimo de observabilidad para agentes (LLM Observability), las métricas que importan y las decisiones tecnológicas prácticas entre plataformas como Langfuse y LangSmith. Incluye enlaces directos a recursos: Langfuse, LangSmith y ClickHouse.

    Resumen rápido (lectores con prisa)

    Qué es: Observabilidad para agentes de IA: traces distribuidos y spans que capturan prompts, llamadas a LLM, búsquedas vectoriales y tool calls.

    Cuándo usarlo: desde el día 0 en cualquier beta u ambiente productivo que use agentes/LLMs.

    Por qué importa: APMs tradicionales no detectan fallos semánticos ni picos de coste por tokens.

    Cómo funciona (resumen): instrumenta spans por acción, mide rendimiento/coste/calidad, y almacena traces para query analítica y alertas.

    Principio: los APM tradicionales no son suficientes

    APM como Datadog o Prometheus miden latencia HTTP, errores y consumo de CPU. Perfecto para servicios deterministas. Un agente de IA devuelve HTTP 200 y puede a la vez fabricar información falsa, ejecutar llamadas externas y disparar costes por token. En ese escenario, el APM dice “todo bien” mientras tu soporte recibe tickets.

    Necesitas telemetría diseñada para flujos probabilísticos: rastreo distribuido con traces que representen sesiones completas y spans que documenten cada decisión y llamada (LLM, búsqueda vectorial, tool calls, llamadas externas).

    Traces y spans: la unidad mínima de diagnóstico

    Diseña cada interacción como un trace. Cada acción —prompts, retrievals, llamadas a herramientas, transformaciones— es un span con metadata.

    Trace: session_42
    ├─ Span 1: receive_prompt (userId=42, promptHash=…)
    ├─ Span 2: vector_search (index=kb_v1, hits=3, latency=320ms)
    ├─ Span 3: LLM_call (model=gpt-4o, tokens_in=1800, tokens_out=120, cost=$0.012)
    └─ Span 4: synthesize_response (format=short-answer)

    Con esto puedes responder rápido: ¿por qué tardó 12s? ¿qué span generó el mayor coste? ¿qué prompts producen más fallos semánticos?

    Métricas imprescindibles (no negociables)

    Rendimiento

    • Time to First Token (TTFT): impacto directo en la UX.
    • Latencia por span y percentiles: p50 / p95 / p99 por tipo de span.

    Coste

    • Tokens y coste por span: calcular coste por span y por session/userId.
    • Coste acumulado por workflow: agente que llama al LLM varias veces debe sumar costes por workflow.
    • Alertas de coste: activar alertas cuando una sesión supera un umbral definido.

    Calidad

    • Feedback explícito: thumbs up/down ligado al trace.
    • Señales implícitas: tiempo de interacción, copias realizadas.
    • LLM-as-a-judge: usar un modelo más económico para evaluar respuestas automáticamente como señal de calidad (no como veredicto absoluto).

    Langfuse vs LangSmith: criterio técnico para elegir

    LangSmith es excelente si tu stack está centrado en LangChain/LangGraph: integración out-of-the-box, datasets de evaluación y UI lista para depurar agentes complejos. El coste es acoplamiento: extraer datos o migrar a otro sistema será costoso.

    Langfuse es agnóstico y open source; se integra con llamadas directas a APIs, Vercel AI SDK, n8n, etc. La reciente incorporación de ClickHouse al ecosistema refuerza su escalabilidad analítica: consultas sobre millones de traces con latencias bajas y análisis de coste en tiempo real. Si prevés escala o necesitas evitar vendor lock-in, Langfuse+ClickHouse es una apuesta sólida.

    Decisión práctica

    • Si dependes de LangChain → LangSmith.
    • Si buscas portabilidad, alto throughput analítico y autoalojamiento → Langfuse (+ ClickHouse).

    Implementación práctica: checklist mínimo viable

    1. Wrap de llamadas al LLM: envuelve cada llamada con un SDK de observabilidad (Langfuse/LangSmith) que capture prompt, model, tokens, cost y versión del prompt.
    2. Correlación: adjunta userId, sessionId y deployment/version tags a cada trace.
    3. Ignorar ruido: no envíes node_modules, logs grandes o secretos. Usa reglas de exclusión (.lfignore / .langsmith-ignore).
    4. Costeo por sesión: suma tokens y coste por sessionId y expón dashboards con coste por feature o cliente.
    5. Evaluación automatizada: configura un pipeline de “LLM-as-a-judge” para marcar respuestas sospechosas y crear datasets de retraining.
    6. Sandboxing y alertas: ejecuta tool calls en entornos aislados y genera alertas cuando spans ejecutan operaciones potencialmente destructivas.
    7. Auditoría y retenimiento: guarda prompts y respuestas (con enmascarado si hay datos sensibles) para reproducibilidad y cumplimiento.

    Operación y cultura: monitoreo como contrato

    No es sólo técnica: es proceso. Cada cambio en prompts o pipelines debe ir acompañado de: etiquetas de versión, tests de regresión en datasets de evaluación y despliegue progresivo (canary). Sin estos pasos, la observabilidad será un registro pasivo en lugar de un control activo.

    La regla final es simple: ningún agente a producción sin traces, coste por session y un mecanismo automático de evaluación. Si ignoras eso, no estás operando IA; estás apostando.

    Implementa observabilidad desde el primer sprint, usa Langfuse o LangSmith según tu arquitectura y organiza tus dashboards en rendimiento, coste y calidad. La visibilidad no es un lujo: es la única forma de mantener agentes de IA útiles, seguros y rentables en producción.

    Para equipos que construyen flujos, agentes o automatizaciones, una referencia práctica y recursos adicionales están disponibles en Dominicode Labs. Es una continuidad natural para explorar integración, pipelines de evaluación y despliegue controlado en proyectos de IA aplicada.

    FAQ

    ¿Por qué los APM tradicionales no detectan problemas de agentes de IA?

    Porque miden señales infraestructurales (HTTP, CPU, errores) pero no la veracidad semántica ni el consumo de tokens. Un agente puede devolver HTTP 200 y producir contenido incorrecto o costoso.

    ¿Qué debe contener un span para ser útil?

    Metadata mínima: tipo de acción (prompt, search, tool call), timestamps, latencia, modelo, tokens_in/tokens_out, coste estimado, userId/sessionId y versión del prompt.

    ¿Cómo calcular el coste por sesión?

    Suma los tokens y el coste asociado de todos los spans pertenecientes al mismo sessionId. Agrupa por workflow o por cliente para dashboards y alertas.

    ¿Cuándo elegir LangSmith sobre Langfuse?

    Elige LangSmith si tu stack está fuertemente integrado con LangChain/LangGraph y aprecias integración out-of-the-box. Evita si necesitas portabilidad o evitar vendor lock-in.

    ¿Qué es LLM-as-a-judge y para qué sirve?

    Es usar un modelo más económico para evaluar respuestas automáticamente como señal de calidad. Sirve para priorizar revisiones humanas y construir datasets de retraining, pero no debe ser el veredicto final.

    ¿Qué datos debo enmascarar al guardar prompts?

    Enmascara datos sensibles: PII, credenciales, secretos y cualquier información regulada. Guarda versiones y hashes cuando sea posible para reproducibilidad sin exposición directa.

  • Crea un agente en TypeScript con Mastra para soporte técnico

    Crea un agente en TypeScript con Mastra para soporte técnico

    Crea tu primer agente en TypeScript con Mastra

    Tiempo estimado de lectura: 6 min

    • Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA con validación de esquemas en runtime.
    • Separar Agent, Tool y Model permite pruebas unitarias y facilita cambiar proveedor de LLM.
    • Usa Zod para convertir inputs/outputs del LLM en contratos verificables.
    • Incluye un ejemplo práctico listo para ejecutar (agente de soporte técnico) y reglas operativas para producción.

    Crear tu primer agente en TypeScript con Mastra es la forma más práctica de evitar la fragmentación entre Node.js y microservicios Python. Si tu stack es TypeScript, mantener todo en el mismo lenguaje reduce latencia, elimina fricciones en despliegue y preserva tipos end-to-end. En las siguientes secciones veremos qué es Mastra, su arquitectura y un ejemplo práctico listo para ejecutar.

    Resumen rápido (lectores con prisa)

    Mastra es un framework en TypeScript para agentes de IA que integra validación de esquemas con Zod.

    Separa responsabilidades en Agent, Tool y Model para pruebas y cambio de proveedor de LLM.

    Usa Zod para que las invocaciones a tools sean contratos verificables en runtime.

    Incluye un ejemplo práctico (agente de soporte) y recomendaciones para producción.

    Documentación y repositorio oficiales están disponibles para referencia.

    Crea tu primer agente en TypeScript con Mastra: por qué importa y cuándo usarlo

    Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA. Su ventaja principal no es solo técnica: es contractual. Al integrar Zod para la validación de esquemas como parte del runtime, convierte las llamadas del LLM en contratos verificables, no en texto libre que “parece correcto”. Documentación: mastra.ai/docs. Repositorio: github.com/mastra-ai/mastra.

    Úsalo cuando quieras:

    • Ejecutar agentes dentro del mismo proceso Node/Next.js.
    • Forzar esquemas de entrada/salida con Zod.
    • Testear herramientas aisladas sin invocar modelos.

    No es la solución si necesitas capacidades avanzadas aún no soportadas por Mastra; evalúa la madurez del proyecto antes de producción.

    Arquitectura mínima: Agent, Tool y Model

    Divide responsabilidades desde el inicio:

    • Agent: orquesta la conversación, mantiene historial e instrucciones del sistema.
    • Tool: funciones asíncronas fuertemente tipadas (Zod). Son la única forma controlada en la que el agente “toca” el mundo.
    • Model: abstracción del proveedor de LLM (OpenAI, Anthropic, etc.). Cambiar proveedor debe ser un cambio mínimo.

    Esa separación permite testing unitario de herramientas y garantiza que la lógica de negocio no quede oculta en un prompt.

    Paso a paso: ejemplo práctico (Agente de soporte técnico)

    Instalación rápida

    mkdir mastra-agent && cd mastra-agent
    npm init -y
    npm install @mastra/core zod
    npm install -D typescript @types/node tsx
    npx tsc --init
    export OPENAI_API_KEY="tu_api_key"

    1) Define la herramienta (Tool)

    Controla exactamente qué parámetros acepta el LLM:

    // src/tools/check-service.ts
    import { createTool } from '@mastra/core';
    import { z } from 'zod';
    
    export const checkServiceTool = createTool({
      id: 'check-service-status',
      description: 'Consulta el estado operativo de un servicio interno por nombre.',
      inputSchema: z.object({
        service: z.enum(['api', 'database', 'frontend']),
      }),
      execute: async ({ context }) => {
        // Reemplaza por consultas reales a monitorización/DB
        const statuses = { api: 'degraded', database: 'operational', frontend: 'operational' };
        return { service: context.service, status: statuses[context.service], checkedAt: new Date().toISOString() };
      },
    });

    2) Instancia el agente

    Define instrucciones claras (system prompt) que actúen como contrato operativo:

    // src/agent.ts
    import { Agent } from '@mastra/core/agent';
    import { checkServiceTool } from './tools/check-service';
    
    export const supportAgent = new Agent({
      name: 'TechSupportAgent',
      instructions: `
        Eres un ingeniero de soporte de nivel 1.
        Antes de concluir que un servicio está caído, INVÓCAME la herramienta de estado.
        Responde con datos y recomendaciones técnicas claras.
      `,
      model: { provider: 'OPENAI', name: 'gpt-4o-mini' },
      tools: { checkServiceTool },
    });

    3) Ejecuta el flujo

    Ejecuta el agente y deja que Mastra coordine modelo y tools:

    // src/main.ts
    import { supportAgent } from './agent';
    
    async function main() {
      const prompt = 'Los usuarios reportan lentitud. ¿Está la API bien?';
      const res = await supportAgent.generate(prompt);
      console.log(res.text);
    }
    
    main().catch(console.error);

    Lanza con npx tsx src/main.ts. Mastra coordina al LLM y las herramientas: si el modelo decide invocar checkServiceTool, el framework valida el input con Zod, ejecuta la función y alimenta la respuesta final.

    Reglas prácticas para llevar esto a producción

    1. Observabilidad desde el día 0: logs estructurados en cada invocación de tool (request id, input validado, tiempo, resultado).

    2. Errores como datos: las herramientas deben devolver errores tipados que el agente pueda razonar y comunicar (no lanzar excepciones sin contexto).

    3. Testing aislado: tests unitarios para execute y tests de integración para la orquestación. No confundas velocidad con cobertura.

    4. CI/CD: bloquea merges que introduzcan nuevas dependencias sin revisión de licencia/reputación. En entornos corporativos, valida paquetes recomendados por LLMs.

    5. Ownership y ADRs: cualquier herramienta crítica debe tener un Architecture Decision Record que explique por qué existe y cómo se prueba.

    Para guiar verificaciones de seguridad y dependencia sigue prácticas de NIST/OWASP (por ejemplo: owasp.org).

    Conclusión: Mantén el criterio humano donde importa

    Mastra te da la ergonomía de TypeScript y contratos verificables con Zod. Eso reduce alucinaciones estructurales y acelera integración en stacks web. Pero la ganancia real viene cuando aplicas disciplina: diseño previo, validación estricta, observabilidad y pruebas. Implementa el agente, mide cómo toma decisiones y exige que cualquier acción en producción esté documentada y testeada. En la próxima entrega de Dominicode mostraremos cómo añadir memoria persistente y encadenar múltiples tools para workflows complejos.

    Dominicode Labs

    Si trabajas en automatización, agentes o workflows y quieres ejemplos prácticos y guías operativas, consulta Dominicode Labs. Encontrarás recursos que complementan patrones de diseño y pruebas para agentes en producción.

    FAQ

    Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA que integra Zod para validación de esquemas en runtime.

    Cuando tu stack principal es TypeScript/Node.js y quieres ejecutar agentes en proceso, forzar esquemas de entrada/salida y testear herramientas sin invocar modelos externos.

    Integra Zod como parte del runtime: las entradas a las tools se validan contra esquemas definidos y solo se ejecutan si cumplen el contrato tipado.

    Sí. La arquitectura separa Model como una abstracción, de modo que cambiar proveedor (OpenAI, Anthropic, etc.) debe ser un cambio mínimo en la configuración.

    Observabilidad desde el día 0, errores como datos tipados, testing aislado, control de dependencias en CI/CD y ADRs para herramientas críticas.

    La documentación oficial está en mastra.ai/docs y el repositorio en github.com/mastra-ai/mastra.

  • Cómo mantener la sincronización en arquitecturas con IA

    Cómo mantener la sincronización en arquitecturas con IA

    Sincronización Arquitectónica: Código, Especificaciones y Agentes de IA

    Tiempo estimado de lectura: 4 min

    • La sincronía entre spec, tests y código es la unidad de trabajo esencial en equipos con agentes de IA.
    • Decisiones efímeras (commits, chats de agentes) sin trazabilidad crean deuda técnica y riesgo.
    • Herramientas como Plum convierten decisiones en artefactos auditables para alinear intentos y ejecución.

    Sincronización Arquitectónica: Código, Especificaciones y Agentes de IA. Si un Product Manager cambia algo hoy, ¿el resto del sistema se adapta mañana? La respuesta habitual es no. Y con agentes de IA escribiendo código, ese desajuste ya no es un fallo aislado: es una bomba de tiempo.

    El problema es simple y profundo: el código evoluciona en commits. Las specs siguen en un README. Los hotfixes saltan directo al trunk. Los agentes generan decisiones en chats y desaparecen con el log. Resultado: intención sin rastro, comportamiento sin documentación y deuda técnica que crece en silencio.

    Resumen rápido (lectores con prisa)

    La sincronización entre spec, tests y código es crítica cuando agentes de IA participan. Convierte decisiones efímeras en artefactos rastreables en el momento del commit. Usa aprobación humana para validar cambios que afectan gobernanza y negocio.

    El Triángulo: Spec, Tests, Código

    Piensa en spec, tests y código como los tres vértices de un triángulo. Tradicionalmente trabajábamos en una línea: spec → código → tests. Con IA esto falla. La implementación revela nuevas decisiones que deben volver a la spec y a los tests. Si no, todo se desincroniza.

    El verdadero trabajo de ingeniería hoy no es escribir más código. Es mantener ese triángulo alineado. Si mejoras el vértice del código, la spec y las pruebas deben moverse al mismo tiempo. Si no lo hacen, la arquitectura entra en drifting y el proyecto se vuelve inmanejable.

    Señales que indican desincronización

    • Commits que no referencian cambios en la spec.
    • PRs que pasan tests unitarios pero rompen invariantes de negocio.
    • Conversaciones con agentes sin registro estructurado.
    • Falta de trazabilidad entre decisión y autoría.

    Si reconoces cualquiera de estas, ya estás en modo emergencia controlada.

    Plum: la plomada para decisiones

    Plum es la herramienta que propone convertir decisiones efímeras en artefactos rastreables. No es un generador de código; es una plomada digital que alinea intención y ejecución.

    Cómo funciona, en cuatro pasos

    1. Al hacer commit, Plum revisa los diffs y los traces del agente.
    2. Extrae decisiones técnicas (qué se decidió, por qué).
    3. Presenta esas decisiones para aprobación humana.
    4. Si las apruebas, actualiza la spec y reporta gaps entre spec, tests y código.

    Plum genera además un archivo .jsonl con cada decisión: la pregunta, la respuesta, quién la aprobó y en qué rama quedó. Eso convierte la intención en un artefacto auditable.

    Por qué eso importa para equipos reales

    • Auditabilidad: Ya no dependes del recuerdo del autor del commit.
    • Gobernanza: Puedes diferenciar decisiones humanas de sugerencias de un LLM.
    • Recuperabilidad: Si un PM cambia una regla, puedes medir el impacto y forzar actualizaciones en spec/tests.
    • Escalabilidad: En equipos con múltiples agentes o muchos desarrolladores, reduce choques de integración.

    Limitaciones prácticas hoy

    • Plum, en su versión inicial, está acoplado a pytest para análisis de coverage. Si tu stack usa otro runner, la integración requiere trabajo.
    • Funciona mejor cuando la spec va por delante del código. Backfilling de specs desde bases legacy masivas sigue siendo difícil.
    • Los LLMs pueden sugerir decisiones razonables pero sin visión de negocio a largo plazo. La aprobación humana no es opcional.

    Patrón operativo recomendado

    1. Escribe spec antes de generar código. Hazla lo más concreta posible.
    2. Cubre casos límite en tests automáticos. No confíes en el “lo arreglamos después”.
    3. Usa Plum o una herramienta equivalente para capturar decisiones en el momento del commit.
    4. Ejecuta un pipeline de sync: spec ↔ tests ↔ código. Fallas: bloqueo del merge hasta que todo esté alineado.
    5. Mantén el .jsonl como fuente de verdad para auditorías y retroalimentación del producto.

    Casos prácticos y referencias

    Los equipos que han escalado Spec-Driven Development reutilizan suites de tests maduras (CPython, Bash). Ejemplos relevantes:

    No es trivial. Requiere inversión en especificaciones y disciplina en procesos. Pero sin eso, delegar en agentes solo acelera la creación de un monolito incomprensible.

    Cierre con criterio

    Si quieres que un cambio de producto active el resto del sistema de forma fiable, no te obsesiones con generar más código. Obsesiónate con capturar decisiones. Haz que tus specs sean artefactos vivos. Instrumenta los traces de los agentes. Automatiza la sincronía. Convierte la intención en datos auditable.

    Instala la plomada. Pruébala en una rama pequeña. Verás cómo las discusiones pasan de “qué falló” a “qué decidimos y por qué”. Esa es la arquitectura que realmente escala cuando la IA entra en la ecuación.

    Dominicode Labs

    Para equipos interesados en experimentar con patrones de sincronización y captura de decisiones, Dominicode Labs ofrece recursos y experimentos relacionados que pueden servir como continuación lógica a este enfoque.

    FAQ

    ¿Qué es la desincronización arquitectónica?

    La desincronización ocurre cuando spec, tests y código divergen: decisiones implementadas no reflejadas en la spec o tests, cambios en tests que no documentan intención, o commits sin trazabilidad. Resulta en comportamiento no documentado y deuda técnica creciente.

    ¿Qué hace Plum?

    Plum revisa diffs y traces del agente al hacer commit, extrae decisiones técnicas, las presenta para aprobación humana y, si se aprueban, actualiza la spec y reporta gaps entre spec, tests y código. Además genera un archivo .jsonl con registro auditable de cada decisión.

    ¿Cómo integrar esto en mi pipeline?

    Incorpora la captura de decisiones en el paso de commit: ejecutar revisión automática de diffs y traces, bloquear merges si el sync falla, y mantener el registro .jsonl como fuente de verdad. Preferible integración con runners de tests compatibles (ej. pytest para la versión inicial de Plum).

    Limitaciones al usar Plum

    En su versión inicial está acoplado a pytest para análisis de coverage; la integración con otros runners requiere trabajo. Funciona mejor con specs que preceden al código y requiere aprobación humana para decisiones de negocio.

    ¿Qué conservar del proceso?

    Conserva la disciplina de escribir specs antes de código, cubrir casos límite en tests, capturar decisiones en cada commit y mantener el .jsonl como registro auditable.

    ¿Qué hago si detecto deuda técnica por agentes?

    Identifica los commits o decisiones sin trazabilidad, prioriza backfilling de specs y tests para las áreas críticas, y aplica bloqueo de merges hasta que el triángulo spec‑tests‑código vuelva a alinearse.

  • Construcción de memoria efectiva en agentes de LLMs

    Construcción de memoria efectiva en agentes de LLMs

    ¿Quieres que tu agente recuerde cosas útiles… o que haga como si recordara y te deje colgado en la siguiente conversación?

    Tiempo estimado de lectura: 7 min

    • Separar memoria corta y larga: la conversación viva debe manejarse aparte de hechos estructurados.
    • Extraer hechos estructurados: usar un extractor que emita JSON y aplicar UPSERT/DELETE, no append infinito.
    • Decisiones arquitectónicas: síncrono vs asíncrono, versionado y locks para evitar race conditions.
    • Optimizar costes: usar modelos baratos para extracción, modelos premium solo para generación crítica.
    • Observabilidad y Gobernanza: logs, métricas, cifrado y políticas de retención son imprescindibles.

    Poca gente habla de esto: la memoria en agentes no es un problema de “mandar el historial” al modelo. Es un problema de arquitectura, coste y criterio. Hacerlo mal es pagar tokens, cargar latencia y, lo peor, construir una ilusión de memoria que falla cuando más importa.

    Te voy a contar, sin florituras, cómo se construyó el sistema de memoria de Agent Builder y qué decisiones concretas puedes tomar hoy para replicarlo sin pelearte con un monster framework.

    Resumen rápido (lectores con prisa)

    Separar memoria corta (últimos N mensajes) de memoria larga (hechos estructurados). Usar un extractor barato que devuelva JSON forzado con operaciones UPSERT/DELETE. Preferir extracción asíncrona por defecto y checkpoints síncronos para acciones críticas. Versionado y locks para evitar race conditions; observabilidad y gobernanza desde el día 1.

    Primera verdad incómoda

    Primera verdad incómoda: los LLMs no recuerdan.

    Cada petición es una hoja en blanco. Si quieres que el agente actúe con coherencia, tienes que diseñar la memoria fuera del modelo.

    Resumen rápido del approach que funciona

    • Separar memoria a corto plazo (conversación viva) de memoria a largo plazo (hechos estructurados).
    • Extraer hechos con un LLM dedicado (extractor) y guardarlos como pares clave-valor o documentos estructurados.
    • Forzar salidas en JSON (Tool Calling) para que la memoria sea determinista.
    • Resolver conflictos con UPSERT/DELETE, no con append infinito.
    • Decidir entre extracción síncrona o asíncrona según prioridades (latencia vs coherencia).

    1) Memoria a corto plazo: lo que vive ahora

    ¿Qué es? Los últimos N mensajes del hilo (thread_id).

    Para qué sirve: referencias inmediatas (“bórralo”, “ese archivo”, “la última tarea”).

    Implementación simple: Redis o una tabla en Postgres con TTL y lista acotada.

    Por qué importa: reduce tokens enviados al LLM principal y mantiene claridad a corto plazo.

    2) Memoria a largo plazo: hechos, no chats

    No guardes el chat crudo. Guarda hechos estructurados: preferencias, roles, reglas de negocio, acciones ya realizadas.

    ¿Cómo se obtienen? Un LLM extractor lee el hilo (o el resumen) y emite objetos JSON con campos tipo {key, value, source, timestamp, confidence}.

    Dónde guardarlos: una tabla Key-Value en Postgres o en Redis para lecturas rápidas; opcionalmente, una base vectorial si necesitas búsquedas semánticas sobre fragmentos largos.

    3) El extractor: el héroe silencioso

    Debe ser un LLM barato y rápido (GPT-4o-mini, Claude 3 Haiku o un modelo local si tienes infra).

    Se le da: el hilo reciente + la memoria actual (opcional, si quieres que compare).

    Debe devolver: operaciones del tipo {op: “UPSERT”, key: “pref_theme”, value: “dark”, reason: “…”} o {op: “DELETE”, key: “pref_theme”, reason: “…”}.

    Forzar JSON es obligatorio. Si el modelo alucina, valida la salida con un schema validator (Zod, JSON Schema).

    4) Resolver conflictos: no más “y también”

    Problema típico: ayer dije “React”, hoy “Angular” y el sistema almacena ambos.

    Solución: lógica de reconciliación dentro del extractor — recibe la memoria existente y decide overwrites o borrados.

    Políticas útiles: última declaración gana para preferencias personales; para estados transaccionales usar confirmación explícita (“Confirmo que he migrado a Angular”).

    5) Síncrono vs Asíncrono — la decisión que rompe equipos

    Síncrono: esperas a que el extractor actualice la memoria antes de responder. Plus: coherencia. Contra: latencia.

    Asíncrono: respondes al usuario y actualizas memoria en background. Plus: experiencia rápida. Contra: race conditions si el usuario dispara múltiples mensajes seguidos.

    Recomendación práctica: asíncrono por defecto, con checkpoints síncronos en operaciones críticas (ej. ejecutar acciones que dependen de la memoria: “programa el pago” → usa extracción síncrona o confirmación humana).

    6) Mitigar race conditions: patrones que funcionan

    • Versionado por evento: cada update incluye un version_id. Si un job en background llega con versión vieja, lo descarta.
    • Locks optimistas: comparar-timestamps antes de aplicar UPSERT.
    • Event sourcing ligero: mandar events al bus (Kafka, Redis Streams) y procesarlos ordenadamente.
    • Si necesitas garantía fuerte, usa transacciones y bloqueo por llave (Postgres advisory locks).

    7) Costes y optimización de tokens

    No envíes texto innecesario al LLM principal. Inyecta solo facts relevantes (top-K) y un resumen de contexto.

    Batch extraction: agrupa varias interacciones y extrae cada X minutos si no hay acciones críticas.

    Usar modelos cheap para extractor y modelos premium para generación cuando haga falta.

    8) Observabilidad y LLMOps: no es opcional

    • Logea: inputs al extractor, salidas JSON, ops aplicadas (UPSERT/DELETE), latencias, errores de parsing.
    • Métricas clave: TTFT, tiempo de extracción, tasa de conflictos, porcentaje de respuestas incoherentes relacionadas con memoria.
    • Guarda trazabilidad para auditoría (what was injected, when, by which extractor) — imprescindible si manejas PII.

    9) Privacidad y gobernanza

    • Nunca almacenes datos sensibles sin cifrado y consentimiento.
    • Tokeniza o anonimiza cuando sea posible.
    • Control de accesos: solo servicios autorizados pueden leer/escribir la memoria.
    • Políticas de retención: define cuánto tiempo quedan los hechos y cómo se borran permanentemente.

    10) Tests y validación

    • Tests unitarios de extractor: inputs -> JSON schema válido.
    • Integración: simula secuencias de diálogos para validar conflict resolution.
    • E2E: pruebas que cubran casos de race conditions y rollback.
    • Prueba manual de A/B: compara comportamiento con y sin memoria en producción limitada.

    11) Stack recomendado mínimo (para lanzar rápido)

    • Storage corto: Redis (listas con TTL)
    • Storage largo: Postgres (tabla kv con versioning) + opcional vector DB (Pinecone/Qdrant)
    • Orquestador: n8n / Lambda / Sidecar service
    • Extractor model: GPT-4o-mini / Claude 3 Haiku (económicos)
    • Generación model: GPT-4o / Claude 3 Sonnet (cuando necesites calidad)
    • Validación: JSON Schema + Zod en backend
    • Observabilidad: logs estructurados + Sentry / Datadog

    12) Checklist práctico para ponerlo en producción (si te gusta lo concreto)

    • [ ] Definir qué “hechos” guardas (user_prefs, last_actions, contracts_signed, etc.).
    • [ ] Implementar almacenamiento corto (Redis) y largo (Postgres).
    • [ ] Crear extractor con JSON forced output y validar schema.
    • [ ] Implementar operaciones UPSERT/DELETE con versionado.
    • [ ] Diseñar flujo asíncrono por defecto y rutas síncronas para operaciones críticas.
    • [ ] Añadir metrics y logs para cada extracción y operación.
    • [ ] Revisar PII/retención y cifrado en reposo y en tránsito.
    • [ ] Tests automáticos para race conditions y reconciliación.
    • [ ] Plan de rollback si una actualización de prompt rompe el extractor.

    Metáfora que guarda la idea

    La memoria del agente no es una mochila donde tiras todo el chat. Es una libreta indexada. Solo apuntas lo que te sirve, lo fechas, lo restructuras y borras lo viejo. Si apilas notas sin orden, la libreta es ruido. Si la estructuras, te salva.

    Historias reales (1 párrafo cada una)

    El equipo A metió todo el historial en cada prompt: coste x10, latencias enormes y usuarios desconectados. Migraron a extractor asíncrono y bajaron costes un 70%.

    El equipo B aseguró cada operación con versión y locks: sacrificaron un poco de velocidad, pero nunca perdieron coherencia en flujos transaccionales.

    El equipo C dejó la extracción en background y puso un checkpoint síncrono antes de ejecutar pagos — ganador en UX y seguridad.

    Cierre con decisión: ¿lo haces tú o lo dejas para después?

    Construir memoria útil no es sexy. Es ingeniería, decisiones difíciles y pruebas. Pero sin ella, tu “agente” será otro bot que habla bonito y olvida todo. Si quieres lanzar algo que realmente parezca inteligente, hazlo con lógica, no con parcheos.

    Si quieres la checklist descargable, un prompt extractor listo para copiar/pegar y un mini-plan de 30 días para implementar esto en tu stack, respóndeme “QUIERO MEMORIA” y te lo mando. Esto no acaba aquí — y si no empiezas hoy, otro equipo lo hará.

    Como continuación lógica para quienes trabajan en automatización, agentes y workflows, puedes encontrar recursos y experimentos en Dominicode Labs.

    FAQ

    Respuesta: ¿Qué diferencia hay entre memoria a corto y a largo plazo?

    La memoria a corto plazo contiene los últimos N mensajes del hilo y sirve para referencias inmediatas. La memoria a largo plazo almacena hechos estructurados (preferencias, roles, acciones realizadas) que deben persistir y consultarse por el agente cuando sea relevante.

    Respuesta: ¿Por qué no guardar el chat completo?

    Guardar el chat crudo aumenta costes (tokens), latencia y ruido. Es mejor extraer hechos útiles y estructurarlos para lecturas rápidas y deterministas.

    Respuesta: ¿Qué es un extractor y qué formato debe devolver?

    Un extractor es un LLM barato y rápido que lee el hilo o su resumen y devuelve operaciones en JSON forzado, por ejemplo {op: “UPSERT”, key: “…”, value: “…”, reason: “…”}. La salida debe validarse con un schema validator.

    Respuesta: ¿Cuándo usar extracción síncrona en lugar de asíncrona?

    Usa extracción síncrona para operaciones críticas que dependen inmediatamente de la memoria (ej. ejecutar pagos). Por defecto, asíncrono para mejor UX y menor latencia, con checkpoints síncronos donde haga falta.

    Respuesta: ¿Cómo mitigo race conditions en actualizaciones de memoria?

    Patrones efectivos: versionado por evento (version_id), locks optimistas (comparar timestamps), event sourcing ligero y, si necesitas garantías fuertes, transacciones y bloqueo por llave en Postgres.

    Respuesta: ¿Qué métricas debo monitorizar?

    Métricas clave sugeridas: TTFT, tiempo de extracción, tasa de conflictos y porcentaje de respuestas incoherentes relacionadas con memoria. Además, loggear inputs, salidas JSON y ops aplicadas para trazabilidad.

    Respuesta: ¿Qué precauciones de privacidad aplicar?

    Nunca almacenar datos sensibles sin cifrado y consentimiento. Tokenizar o anonimizar cuando sea posible, controlar accesos y definir políticas de retención claras.

  • Cómo los Cloud Agents transforman la automatización del software

    Cómo los Cloud Agents transforman la automatización del software

    “When we started building Cursor a few years ago, most code was written one keystroke at a time”: La evolución a Cloud Agents

    Tiempo estimado de lectura: 5 min

    • La producción de software está pasando de autocompletados locales a flotas de agentes en la nube, lo que exige repensar pipelines, CI/CD y gobernanza.
    • Reemplaza diffs extensos por artefactos verificables (logs estructurados, grabaciones de pruebas, previews desplegados) para revisar resultados de agentes.
    • Patrón de trabajo para Tech Leads: problema claro, herramientas, VMs aisladas, métricas y revisión de artefactos.
    • Riesgos críticos: flaky tests, privilegios, coste y observabilidad; requieren inversión en determinismo, least-privilege y trazabilidad.
    • Empieza con tareas confinadas que tengan tests automatizados para obtener ROI medible.

    Introducción

    “When we started building Cursor a few years ago, most code was written one keystroke at a time”. Esa frase aparece en las primeras líneas porque resume el punto de inflexión: del autocompletado puntual a la orquestación de agentes en la nube. Para equipos técnicos, la pregunta ya no es si los agentes serán relevantes, sino cómo rediseñar pipelines, CI/CD y gobernanza para que las flotas de agentes produzcan software fiable y mantenible.

    Resumen rápido (lectores con prisa)

    Cloud Agents son agentes que ejecutan trabajos largos y autónomos en VMs en la nube. Úsalos cuando tienes CI/CD estable y tests fiables; importan porque permiten paralelizar y automatizar tareas a escala. Funcionan produciendo artefactos verificables (logs JSON, grabaciones de pruebas, previews desplegados) que los humanos revisan en lugar de inspeccionar cada línea.

    “When we started building Cursor a few years ago, most code was written one keystroke at a time” — tres eras y sus implicaciones técnicas

    1) Era Tab — autocompletado local

    Tab y autocompletados similares automatizaron trabajo repetitivo: imports, snippets, patrones boilerplate. Ventaja: latencia nula y control humano total. Limitación: incapacidad para juicio y contexto extendido.

    2) Era de agentes síncronos — prompt-and-response

    Modelos más capaces permitieron agentes que mantienen contexto y usan herramientas en secuencia. El desarrollador sigue en el bucle, supervisando cada paso. Beneficio: mayores tareas automatizables (refactorings, debugging multiarchivo). Problema: consumo de recursos locales y atención humana constante, lo que limita la paralelización.

    3) Era Cloud Agents — ejecución asíncrona y autónoma

    Ahora entramos en la era donde los agentes corren en VMs dedicadas en la nube, trabajan durante horas, iteran, ejecutan pruebas y entregan artefactos revisables (logs, videos de pruebas, previews). El desarrollador deja de “teclear” para diseñar y gobernar la fábrica que produce software.

    Arquitectura práctica: de diffs a artefactos (qué cambiar en tu stack)

    Revisar diffs pierde sentido cuando un agente genera miles de líneas. En su lugar, los artefactos éstandarizados son la unidad de revisión:

    • Logs estructurados (JSON con traces, métricas, cobertura).
    • Grabaciones o snapshots de pruebas E2E.
    • Previews desplegados en entornos efímeros con URLs accesibles.

    Diseña tu pipeline para producir esos artefactos automáticamente: el agente debe terminar con un paquete que contenga build, test-report, y endpoint de preview. Orquestadores como n8n facilitan la integración entre triggers, ejecución de agentes y recolección de artefactos.

    Patrón de trabajo recomendado para Tech Leads

    • 1. Define el problema y criterios de aceptación (no prompts vagos).
    • 2. Provee herramientas: repositorio, tokens con scopes limitados, staging determinista, y datos de prueba.
    • 3. Despliega agentes en VMs aisladas con acceso controlado.
    • 4. Recolecta artefactos y métricas automáticas de calidad (test coverage, lint score, performance baselines).
    • 5. Revisa artefactos y da feedback estructurado; reitera a nuevos runs si aplica.

    Este patrón transforma al humano en arquitecto del proceso y evaluador del comportamiento, no inspector de cada línea de código.

    Riesgos críticos al escalar flotas de agentes

    • Flaky tests y no-determinismo: lo que un desarrollador soluciona en minutos puede paralizar cientos de ejecuciones. Solución: invertir en tests deterministas, sandboxing y pre-indexado de dependencias.
    • Seguridad y privilegios: agentes necesitan acceso (repos, staging, servicios). Aplica principios de least privilege, rotación de tokens y entornos staging aislados.
    • Coste y latencia: vectoriza qué procesar en la nube. Preprocesado off-line y compresión de artefactos mitigan gasto y reducen tiempos de respuesta.
    • Observabilidad: sin trazabilidad fina, fallos de agente se vuelven cajas negras. Instrumenta cada run con métricas, logs y checkpoints claros.

    Casos de uso iniciales con ROI claro

    • Refactorizaciones repetitivas en código legacy donde reglas de transformación son estables.
    • Migraciones de dependencias donde tests y builds están automatizados.
    • Generación de PRs para scaffolding y plantillas con pruebas mínimas ya verificadas.

    Empieza con tareas confinadas; mide tiempo total (setup + run + review) versus esfuerzo humano reemplazado.

    Criterio para decidir adopción

    Adopta Cloud Agents si:

    • Tienes pipelines CI/CD estables y tests confiables.
    • Puedes automatizar la evaluación mediante artefactos objetivos.
    • El coste de setup y gobernanza se amortiza con paralelismo y tiempo liberado.

    Evítalos cuando:

    • El entorno de staging es frágil o las pruebas son intermitentes.
    • El conocimiento crítico reside en «contexto tribal» no documentado.
    • Las políticas de seguridad impiden conceder accesos controlados a VMs externas.

    Conclusión

    La frase inicial —”When we started building Cursor a few years ago, most code was written one keystroke at a time”— no es nostalgia: es punto de partida. El valor real hoy está en construir la fábrica que permite que agentes trabajen como compañeros: bien orquestados, auditables y seguros. La transición exige inversión en pruebas deterministas, gobernanza de accesos y artefactos que permitan revisar comportamiento en lugar de código línea por línea. Si lo haces bien, pasarás de acelerar tareas repetitivas a escalar la producción de software con flotas autónomas.

    Dominicode Labs

    Para quien explora integración de agentes, workflows y automatización en equipos técnicos, puede ser útil revisar recursos adicionales en Dominicode Labs. Es una continuación lógica para experimentar con orquestación, artefactos y gobernanza en entornos controlados.

    FAQ

    ¿Qué es un Cloud Agent?

    Un Cloud Agent es un agente de software que ejecuta tareas de forma asíncrona y autónoma en VMs o entornos en la nube, con capacidad para iterar durante largos periodos y producir artefactos verificables (logs, pruebas, previews).

    ¿Cuándo debería usarlos?

    Úsalos cuando tus pipelines CI/CD son estables, cuentas con tests fiables y puedes automatizar la evaluación por artefactos objetivos. Evítalos si el staging es frágil o el contexto crítico no está documentado.

    ¿Qué artefactos deben producir los agentes?

    Artefactos estandarizados como logs estructurados en JSON (traces, métricas, cobertura), grabaciones o snapshots de pruebas E2E y previews desplegados con URLs accesibles.

    ¿Cómo mitigo flaky tests?

    Invierte en tests deterministas, sandboxing, pre-indexado de dependencias y aislar variables externas en entornos staging para reducir no-determinismo.

    ¿Qué requisitos de seguridad son críticos?

    Aplica principios de least privilege, usa tokens con scopes limitados, rota credenciales y ejecuta agentes en VMs aisladas con accesos controlados a repos y servicios.

    ¿Cuál es el primer caso de uso recomendado?

    Comienza con tareas confinadas y repetitivas que tengan reglas estables y tests automatizados, como refactorizaciones en código legacy o migraciones de dependencias con cobertura de pruebas.

  • Cómo implementar un Event Bus para arquitecturas con agentes descentralizados

    Cómo implementar un Event Bus para arquitecturas con agentes descentralizados

    ¿Y si tu app dejara de ser un monstruo monolítico con un único “asistente” y se convirtiera en un enjambre de agentes que se pasan la pelota sin romper nada?

    Tiempo estimado de lectura: 6 min

    • Reducir contexto inútil en prompts, aislar fallos y permitir equipos autónomos sin perder UX coherente.
    • Descentraliza la responsabilidad cognitiva; centraliza seguridad, auditoría y orden.
    • Usa un Event Bus global con contratos claros y BFFs que versionen prompts y auditen inferencias.
    • Mide confidence, delegaciones y latencia; trata prompts como código.

    Poca gente lo dice así: dividir la inteligencia en agentes especializados no es exotismo. Es economía de tokens, menos alucinaciones y menos puntos únicos de falla. Y sí: también es más trabajo. Pero si tu producto escala, vale cada minuto invertido.

    Resumen rápido (lectores con prisa)

    Qué es: Un patrón para dividir inteligencia en agentes por dominio y comunicarlos vía un Event Bus global.

    Cuándo usarlo: Cuando la complejidad de dominios y volumen hacen ineficiente un único asistente monolítico.

    Por qué importa: Reduce tokens, mitiga alucinaciones y falla de forma aislada; facilita equipos autónomos.

    Cómo funciona (resumen): Host publica USER_INPUT al bus; agentes calculan confidence; el agente ganador responde y puede delegar sub-problemas a otros agentes vía eventos.

    Introducción

    Te doy el patrón completo. Arquitectura, contratos de evento, anti-patrones, seguridad y el pacto UX que nadie firma hasta que explota.

    Qué estamos resolviendo (en claro)

    Puntos

    • Reducir contexto inútil en prompts.
    • Aislar fallos por dominio.
    • Permitir equipos autónomos (cada uno con su BFF y su agente).
    • Mantener una UX coherente pese a la descentralización.

    Principio arquitectónico imprescindible

    Descentraliza la responsabilidad cognitiva. Centraliza la infraestructura técnica que garantiza seguridad, auditoría y orden. Traducción: agentes por dominio + un Event Bus global para hablarse.

    Componentes esenciales (resumen)

    Host / Shell

    Monta el Event Bus y el UI unificado. No ejecuta prompts.

    Micro-frontends (Remotes)

    UI + agnostic agent client.

    BFF por dominio

    Ejecuta inferencia, almacena prompts versionados, audita.

    Event Bus Global

    Canal estándar para intentos y delegaciones.

    Orquestación concreta

    Coreografía por defecto; orquestador solo si necesitas transacciones distribuidas.

    El contrato del evento (no lo negocies)

    Si no tienes un schema, tendrás ruido. Exige este JSON mínimo:

    {
      "id": "uuid",
      "source": "inventory-agent",
      "intent": "REQUIRE_BILLING_CHECK",
      "context": { "userId": "123", "orderId": "405" },
      "confidence": 0.87,
      "metadata": { "traceId": "abc", "locale":"es-ES" },
      "timestamp": 1700000000
    }
    

    Reglas rápidas

    • confidence < 0.6 => requiere confirmación humana o UI consent.
    • context debe llevar solo IDs y flags. No historial de chat completo.
    • metadata incluye traceId para rastrear en las trazas distribuidas.

    Cómo se mueven los eventos (flujo)

    1. Usuario pregunta algo en el host.
    2. Host publica evento USER_INPUT al bus.
    3. Agentes suscritos calculan su confidence local.
    4. El agente ganador responde y/o emite delegaciones (events) sobre sub-problemas.
    5. Si hay delegación, otros agentes reaccionan y devuelven resoluciones.
    6. Host compone respuestas y muestra coherencia al usuario.

    Ejemplo práctico (en vivo)

    Usuario: “¿Por qué no ha salido el pedido #405? ¿Falló mi tarjeta?”

    • Inventory-agent: detecta pedido retenido → responde estado del envío → emite REQUIRE_BILLING_CHECK.
    • Billing-agent: suscribe y consulta pasarela en su BFF → descubre tarjeta vencida → emite BILLING_ISSUE_FOUND.
    • Host: recibe ambas respuestas y muestra un flujo: “Pedido retenido. Tarjeta expirada. ¿Actualizar ahora?”

    Cómo implementar el Event Bus (dos opciones)

    Opción A — RXJS (más control dentro de Angular)

    // event-bus.service.ts
    import { Subject } from 'rxjs';
    export const globalEventBus = new Subject();
    // publish: globalEventBus.next(event)
    // subscribe: globalEventBus.subscribe(e => ...)
    

    Opción B — CustomEvent (mejor para micro-frontends aislados)

    // emit
    window.dispatchEvent(new CustomEvent('app:event', { detail: event }));
    // listen
    window.addEventListener('app:event', e => handle(e.detail));
    

    Anti-patterns del bus (evítalos)

    • Enviar cada pensamiento del LLM. Solo conclusiones.
    • Compartir historial completo en context.
    • Permitir que cualquier módulo escuche todo sin roles.
    • Esperar sincronía absoluta entre agentes.

    Mecanismo de arbitraje: quién responde primero

    Necesitas un árbitro débil. No un maestro, sino una regla simple:

    1. Cada agente publica su confidence ante USER_INPUT.
    2. Host espera X ms (ej. 200–400ms) o hasta el primer confidence >= threshold.
    3. El agente ganador toma la palabra; los demás quedan “en espera” para delegaciones.

    Seguridad y datos: no es opcional, es ley

    • No inferes en cliente. Nunca. Las keys quedan en los BFF.
    • Filtrado por roles en el Event Bus: cada agente tiene claims y scopes.
    • Sanitización en BFF: elimina PII innecesaria antes de enviar a LLM.
    • Audit log centralizado: guarda hash de mensajes, no el texto completo salvo consentimiento.
    • Rate limiting por agente y por usuario.

    Prompts y versionado: trátalos como código

    Versiona prompts. Haz CI sobre prompts. Un cambio de prompt puede cambiar comportamiento entero. Guarda el promptId en metadata del evento para reproducibilidad.

    Observabilidad: métricas mínimas que necesitas YA

    • Latencia total por intent (ms).
    • Confidence distribution por agente.
    • Delegation rate (cuántas veces un agente pide otro agente).
    • Fallas y errores por BFF.
    • Casos humanos de override (undo/confirm).

    Costes y escalado

    Agentes especializados consumen menos tokens por prompt. Pero multiplicas llamadas si no cacheas. Cachea respuestas frecuentes en BFF. Si el dominio es alto volumen, considera modelos on-prem o inferencia en región cercana.

    UX: cómo evitar que la UX parezca multi-agente

    • Unifica la voz: host normaliza tono y formato.
    • Muestra trazabilidad solo si el usuario la pide (ej. “ver detalle técnico”).
    • Siempre provee undo para acciones críticas.
    • Si confidence baja, pide confirmación editable: muestra la transcripción + intención sugerida.

    Sincronización del historial

    Historial maestro en Host. Los BFFs pueden guardar copias locales por dominio. Para reproducir una conversación: traceId + promptId + promptVersion + snapshot del context.

    Tests y despliegue

    • Contract tests para el Event Schema.
    • E2E con agentes stubs (simula respuestas con confidence).
    • Canary deploy de prompts: prueba nuevos prompts con 1% de tráfico antes de publicar.

    Cuando usar orquestador en vez de coreografía

    Coreografía = menos acoplamiento. Pero si necesitas transacciones distribuidas (ej. reserva + pago atómico), añade un orquestador o un workflow engine (Temporal, Durable Functions). No lo hagas por conveniencia.

    Checklist práctico para arrancar en 2 semanas

    • [ ] Definir dominios y agentes.
    • [ ] Diseñar Event Schema y contract tests.
    • [ ] Implementar Bus (CustomEvent + roles).
    • [ ] BFFs mínimos con secreto seguro y prompt versionado.
    • [ ] UI host de chat, arbiter de confidence y UX confirmaciones.
    • [ ] Observability (traces + metrics).
    • [ ] Políticas de privacidad y retención.

    Cierre directo: lo que debes hacer hoy

    No diseñes agentes porque “está de moda”. Distribuye inteligencia solo donde tenga sentido. Empieza por 2 agentes: uno crítico (ej. facturación) y otro de baja prioridad (ej. FAQ). Lanza el Event Bus y valida la coreografía. Mide confidence y delegations la primera semana. Ajusta prompts con datos reales.

    ¿Quieres el kit para arrancar? Te puedo pasar:

    • Event Bus + arbiter en TypeScript.
    • BFF skeleton que llama a LLM y valida JSON.
    • Prompts versionados y tests de contrato.

    Responde “QUIERO EL KIT” y te lo envío listo para pegar en tu repo.

    Esto no acaba aquí. Si lo haces bien, tu app dejará de ser un oráculo confuso y empezará a funcionar como un equipo de especialistas que no se pisan el uno al otro. ¿Empezamos por el Event Bus o por el BFF? Responde “BUS” o “BFF”.

    Dominicode Labs

    Si quieres recursos prácticos y plantillas para implementar este patrón, revisa Dominicode Labs. Encontrarás ejemplos de Event Bus, skeletons de BFF y tests de contrato que aceleran la puesta en marcha.

    FAQ

    ¿Por qué dividir en agentes en vez de un asistente monolítico?

    Dividir reduce contexto inútil en prompts, aisla fallos por dominio y permite equipos autónomos con BFFs propios. Es coste de ingeniería que compensa cuando el producto escala.

    ¿Qué contiene el contrato mínimo de un evento?

    El JSON mínimo incluye id, source, intent, context (solo IDs/flags), confidence, metadata (traceId, locale) y timestamp. Sin schema tendrás ruido.

    ¿Cómo evito que la UX se perciba como multi-agente?

    Unifica la voz desde el Host, muestra trazabilidad solo si el usuario la solicita y siempre ofrece undo para acciones críticas. Normaliza tono y formato antes de mostrar respuestas.

    ¿Cuándo necesito un orquestador en lugar de coreografía?

    Cuando necesitas transacciones distribuidas atómicas (ej. reserva + pago). Para casos simples, coreografía reduce acoplamiento; usa orquestador solo para transacciones complejas.

    ¿Dónde deben residir las claves y la inferencia?

    Nunca en el cliente. Las keys y la inferencia deben vivir en los BFFs o infraestructura backend segura. El cliente solo publica eventos y muestra resultados.

    ¿Qué métricas son imprescindibles al arrancar?

    Latencia por intent, distribución de confidence por agente, delegation rate, fallas por BFF y casos humanos de override.