Ingeniería de grafos para agentes de codificación de IA: contexto, contratos y reparación

“La ingeniería de grafos” ha recibido mucha atención últimamente, y la mayoría de las explicaciones se centran en los grafos, los nodos y los DAG. Esas partes son importantes, pero no responden a la pregunta que realmente merece hacerse: ¿por qué los agentes de programación basados en IA necesitarían de repente la ingeniería de grafos?

Un desarrollador que pasó meses utilizando herramientas como Claude Code y posteriormente Codex observó un patrón. La mayoría de las tareas de programación fallan no porque el modelo no pueda escribir código, sino porque los flujos de trabajo de larga duración pierden gradualmente su estructura. El contexto se desincroniza, se olvidan los requisitos, resulta difícil verificar los resultados, y cuando algo sale mal, la solución más sencilla suele ser reiniciar toda la tarea.

Esa observación dio lugar a un pequeño marco de investigación llamado ContractGraph. La explicación que sigue detalla sus ideas, qué funcionó y qué falló. No fue creado para competir con los marcos existentes, ni está vinculado a un modelo en particular. El objetivo era más específico: ¿se podía diseñar un flujo de trabajo en el que cada paso tuviera un objetivo claro, un contrato bien definido y una forma determinista de decidir si ese paso realmente se ha completado?

El resultado fue un grafo basado en contratos que gestionaba un flujo de trabajo de investigación a través de tareas aisladas, validación explícita y reparación dirigida, en lugar de un único comando complejo. La primera implementación estuvo orientada a agentes de investigación, pero las ideas subyacentes son igualmente aplicables a agentes de programación, pipelines de documentos, sistemas de evaluación y cualquier proceso en el que varios pasos impulsados por la IA deban generar resultados verificables. Tenga en cuenta que se trata de un experimento realizado por un profesional, por lo que las conclusiones se basan en la experiencia y no en métricas medibles.

Qué significa la ingeniería de grafos

La ingeniería de grafos consiste en dividir un flujo de trabajo de IA complejo en pequeñas unidades de ejecución y vincularlas mediante reglas explícitas. Un sistema diseñado con ingeniería de grafos suele combinar varias unidades de ejecución, enrutamiento explícito, estado compartido, verificación y coordinación duradera.

Una responsabilidad por nodo. Los bordes eligen el siguiente paso. El estado compartido en todo el flujo de trabajo transmite información, y una etapa de verificación decide si continuar, intentar de nuevo, reparar o detenerse.

Las dos preguntas detrás del diseño

Al esperar pasar la mayor parte del tiempo en los nodos, los bordes y el flujo de ejecución, el desarrollador descubrió que esos no eran la parte difícil. Dos preguntas seguían apareciendo una y otra vez.

Primero: ¿qué información debería permitírsele a un agente de IA tratar como verdadera? Segundo, una vez que termina una tarea: ¿cómo se puede saber si el resultado realmente cumple con lo solicitado?

Cuanto más se probaban los flujos de trabajo de larga duración, más claro se volvía que estas cuestiones eran más importantes que el gráfico en sí. Un agente que parte de información incorrecta o termina sin una forma fiable de verificar su trabajo simplemente transfiere los errores de un nodo al siguiente. Las dos cuestiones clave se convirtieron en Contexto y Contrato. El contexto define qué puede creer un agente, mientras que el contrato define qué debe producir. Todo lo demás en el marco depende de estas dos ideas.

Contexto y contratos como bloques fundamentales

El gráfico no era la parte más difícil. El verdadero desafío era asegurarse de que cada nodo comenzara con la información correcta y produjera algo verificable antes de que el flujo de trabajo avanzara.

Contexto. Los agentes no deberían ver todo. Un nodo recibe únicamente la información en la que puede confiar, como por ejemplo los requisitos del usuario, las restricciones del proyecto, los documentos verificados o los resultados aceptados de nodos anteriores.

Contrato. Cada nodo necesita una definición clara de lo que debe entregar. Cuando un resultado no cumple con el contrato, el flujo de trabajo no puede seguir adelante sin más. Debe verificar la salida, corregir el paso defectuoso o detenerse.

En pocas palabras, el contexto determina en qué puede creer un agente y los contratos definen lo que debe entregar. Una vez que ambos límites están claros, es mucho más fácil razonar sobre el grafo. Cada nodo tiene un propósito definido, una fuente de información precisa, una salida medible y una verificación determinista antes de que comience el siguiente paso.

De una idea a un grafo ejecutable

Al separar el contexto de los contratos, la siguiente pregunta es cómo se convierten en un flujo de trabajo ejecutable. El objetivo no era codificar manualmente un grafo distinto para la investigación, la programación o la generación de documentos. En su lugar, el flujo de trabajo debería compilarse dinámicamente a partir del propio problema, y no a partir de rutas predefinidas. Primero son necesarios dos pasos.

El primer paso consiste en construir el contexto. No todos los archivos o documentos merecen la misma confianza, por lo que el flujo de trabajo crea un contexto canónico: una fuente de verdad validada en la que todos los nodos pueden basarse. Sus materiales brutos varían según la tarea, como documentos de proyecto, requisitos del usuario, código, documentos de diseño u otros datos considerados fiables.

El segundo paso consiste en crear el contrato. En lugar de describir la tarea únicamente en prosa, se genera un contrato estructurado que indica qué debe producirse en cada etapa, cómo dependen los nodos entre sí y qué se debe validar antes de continuar con la ejecución.

Una vez que ambos elementos están listos, se compila el flujo de trabajo. Esta etapa de inicialización no ejecuta nada; su función es planificar. De ella surgen el grafo de ejecución, un paquete de contexto específico para cada nodo, manifiestos reutilizables y habilidades compartidas, además de un orden de ejecución determinado a partir de los contratos, sin ninguna secuencia predefinida.

La ejecución es entonces sencilla. Un nodo recibe únicamente su contexto específico, realiza el trabajo asignado, pasa por una validación determinista, guarda el resultado aceptado y transfiere el control. Si la validación falla, solo se repara el nodo afectado antes de reanudar la ejecución, de modo que nada se reinicia desde cero.

Por lo tanto, la estructura del grafo proviene del contexto y de los contratos proporcionados al inicio, y no de una implementación fija. La misma cadena de compilación puede armar flujos de trabajo para investigación, programación, documentación o cualquier otra cosa, sin cambiar el entorno de ejecución.

Pruebas en modelos más grandes y más pequeños

Diseñar un marco es solo la mitad del trabajo. La pregunta más difícil es si la arquitectura resiste cuando un flujo de trabajo es lo suficientemente grande como para revelar sus debilidades.

Los primeros experimentos utilizaron un flujo de trabajo mucho más grande que se ejecutaba en Claude Code, con nodos de ejecución generados dinámicamente, etapas de planificación anidadas y tareas de investigación extensas. La calidad fue excelente, pero completar el flujo de trabajo requería una gran cantidad de cálculos del modelo.

Eso planteó una pregunta adicional: ¿podría la misma arquitectura de gráfico seguir generando flujos de trabajo fiables con un modelo mucho más pequeño y económico? Un segundo experimento utilizó un flujo de trabajo de generación de planes de estudio, ejecutado a través de OpenCode con Big Pickle en lugar de un modelo de vanguardia. La mecánica se mantuvo igual: el flujo de trabajo se compiló dinámicamente, se generaron nodos especializados, cada etapa se validó de manera determinística, se repararon los fallos cuando fue necesario, y el resultado final salió del mismo pipeline.

El objetivo no era comparar modelos ni determinar un ganador. Se trataba de ver en qué medida la fiabilidad provenía de la arquitectura de ejecución y no de la capacidad bruta del modelo. El hallazgo sorprendente fue que los mayores problemas no eran fallos del modelo en sí, sino fallos en el flujo de trabajo, y ahí es donde la ingeniería de gráficos se volvió interesante.

Dónde falló

El experimento no demostró que la ingeniería de grafos prevenga los fallos. Mostró que dicha ingeniería hace que los fallos sean visibles.

Por el camino surgieron todo tipo de problemas: metadatos incompletos, pruebas faltantes, referencias sin resolver, contenido duplicado, estados de ciclo de vida inválidos, información de seguimiento incorrecta e incluso problemas simples de codificación. El grafo no causó ninguno de ellos. Son los fallos que uno esperaría en flujos de trabajo de IA de larga duración.

Lo que cambió fue que cada fallo tenía una ubicación exacta. En lugar de tratar toda la ejecución como un único fallo, era posible encontrar el nodo específico que incumplió su función, reparar solo ese nodo, realizar nuevamente una validación determinista y continuar desde allí. El resto del flujo de trabajo permaneció intacto porque cada etapa exitosa ya había sido verificada y guardada.

Eso cambió la forma en que el desarrollador veía la técnica. No era una forma de hacer que los modelos fueran más inteligentes, sino una forma de hacer que los fallos fueran locales, observables y recuperables. El grafo no eliminaba los errores, pero le daba a cada error una dirección.

Por qué la validación debe ser determinista

Un modelo puede afirmar con total confianza que una tarea está completada, pero eso no la convierte en cierta. Los modelos de lenguaje razonan, resumen y toman decisiones muy bien, pero son un juez poco fiable para determinar si un flujo de trabajo ha cumplido con sus propios requisitos.

Por eso cada nodo en ContractGraph finaliza con una verificación determinística. Nadie solicita la opinión de un segundo modelo sobre el resultado. El flujo de trabajo comprueba condiciones objetivas: ¿el esquema cuenta con todos los campos necesarios? ¿Se han cumplido las dependencias? ¿Están presentes los artefactos requeridos y las referencias se resuelven? ¿El nodo ha entregado todo lo que su contrato prometía? Estas no son evaluaciones subjetivas; cada una es simplemente verdadera o falsa.

Esa separación resultó ser una de las ideas más valiosas del framework. El modelo se concentra en el razonamiento, mientras que la validación determinística se encarga de la verificación. Un modelo puede afirmar que ha terminado su trabajo, pero solo un validador determinístico puede demostrar que falta un campo requerido.

Por qué el esfuerzo adicional puede valer la pena

Incluso antes de este experimento, el desarrollador trataba a los agentes de programación basados en IA como un pequeño equipo y no como un único asistente. No era inusual que Claude Code, Codex y OpenCode trabajaran simultáneamente en diferentes partes de un mismo repositorio.

Eso generó un problema inesperado. Los agentes podían llegar a necesitar modificar los mismos archivos o depender de la misma implementación, y sin coordinación uno podía sobrescribir el trabajo del otro o invalidar las suposiciones hechas anteriormente.

La solución era sencilla: cada tarea tenía un responsable. Si un agente era el encargado de una parte del código, los demás no podían tocar esos archivos hasta que el responsable lo permitiera. Al añadir una verificación después de cada paso importante, muchos conflictos nunca llegaban al repositorio.

La compensación era evidente. Este estilo de desarrollo utiliza muchos más tokens que pedirle a un modelo que construya una función en una sola conversación, ya que cada paso de validación, intento de nuevo, reparación y coordinación añade trabajo. Sin embargo, el resultado era diferente. En lugar de corregir repetidamente las regresiones causadas por correcciones anteriores, el flujo de trabajo se volvió mucho más predecible, y las funciones desarrolladas de esta manera requerían pocos retoques, ya que cada etapa se verificaba antes de comenzar la siguiente.

La ingeniería de grafos no es algo que deba utilizarse en todos los casos, y para cambios pequeños representa una carga innecesaria. Para funciones más complejas, implementaciones extensas o trabajos con múltiples agentes, el costo adicional aporta algo más valioso que una inferencia barata: confianza.

Qué realmente cuesta

Nadie debería interpretar esto como una afirmación de que la ingeniería de grafos es la solución mágica. Preparar el contexto, generar contratos, compilar el grafo, validarlo, repararlo y agregar información implica costos adicionales en llamadas al modelo y en tokens. Además de un único prompt, el flujo de trabajo resulta indudablemente más caro.

Los primeros experimentos con modelos de vanguardia arrojaron resultados excelentes, pero consumieron mucha capacidad de cálculo, lo que fue una de las principales razones para probar modelos más pequeños y económicos. La lección aprendida es que la ingeniería de grafos no reduce la capacidad de cálculo; simplemente la reasigna. En lugar de gastar recursos en recuperarse de regresiones, reiniciar flujos de trabajo fallidos o corregir errores continuamente, el sistema los invierte de antemano en la planificación, verificación y aislamiento de fallos.

Eso cambia el objetivo de optimización. La ingeniería de grafos no está diseñada para producir la ejecución más económica, sino la más predecible. Una ejecución de OpenCode consumió una gran cantidad de tokens. Esa cifra no debe interpretarse como prueba de que el enfoque es económico; de hecho, demuestra lo contrario, ya que la ingeniería de grafos invierte conscientemente más recursos computacionales para lograr aislamiento de fallos, auditabilidad, posibilidad de reanudación y mayor confianza. Si ese es un buen intercambio depende por completo del problema.

Cuándo vale la pena

La ingeniería de grafos no es necesaria en todos los flujos de trabajo de IA. Para una consulta SQL, una función pequeña o algunos ajustes en la interfaz de usuario, generalmente basta con un prompt bien redactado, y agregar contratos, capas de validación y grafos de ejecución solo haría que las cosas sean más lentas y complicadas.

Comienza a ser útil cuando el costo del fracaso supera el costo del cálculo adicional. Esto incluye investigaciones de larga duración, trabajos con grandes volúmenes de datos, flujos de trabajo multiagente, sistemas sensibles a la seguridad, automatización empresarial y cualquier proceso cuyo resultado debe ser verificable y reproducible. Cuantos más pasos tenga un flujo de trabajo, más valiosa resulta una coordinación explícita.

La lección principal no tiene que ver con la inteligencia. En los casos en que un flujo de trabajo es complicado, su estructura hace que sea más sencillo seguirlo, verificarlo, recuperarse de errores y ampliarlo. Además, esta idea está lejos de estar completa. La ejecución consciente de las dependencias, la programación más inteligente, la optimización de recursos, la recompilación de grafos parciales y una coordinación más avanzada entre agentes siguen sin explorarse. Una versión breve de la lección: utilice indicaciones para resolver tareas y emplee la ingeniería de grafos para construir sistemas.

Pensamientos finales

Al principio, la expectativa era aprender sobre grafos. Lo que realmente enseñó el ejercicio fueron los límites, la verificación y la coordinación. El grafo no era lo importante. Lo que sí importaba era un propósito claro para cada paso, un límite en lo que un agente puede creer, una definición de lo que debe producir y una prueba de finalización antes de pasar a algo más.

Este no es el único modo de construir sistemas de IA, y no todo flujo de trabajo merece tanta estructura. Pero para trabajos complejos, de larga duración o con múltiples agentes, la ingeniería de grafos ofrece una vía práctica hacia sistemas que son más predecibles y fáciles de evolucionar.

Si hay una sola frase que hay que recordar, que sea esta cadena: una instrucción indica el deseo, el contexto determina qué puede considerarse hecho por el agente, el contrato detalla el resultado a entregar, y el grafo es el mecanismo que demuestra que el trabajo está terminado.

En el momento de este experimento, ContractGraph seguía en fase de desarrollo y su repositorio aún no se había publicado, ya que primero era necesario simplificar su arquitectura. Para una introducción más amplia sobre el tema, busque una guía general de ingeniería de grafos, ya que este texto aborda solo un marco y no todo el campo.