
La primera vez que logré ejecutar de principio a fin la cadena principal del Agent, pensé que la parte más difícil ya había terminado.
El modelo podía hacer llamadas, los datos podían persistirse en la base de datos, los vectores podían recuperarse y el flujo de trabajo también llegaba hasta el final sin problemas. Para alguien que hacía su primer proyecto completo con LangGraph, eso ya era suficiente para emocionarme un buen rato.
Pero cuando empecé a usarlo de forma continua, los problemas fueron apareciendo uno tras otro: aunque había configurado checkpoint, en la siguiente ronda el modelo no sabía qué había ocurrido en la ronda anterior; el flujo de trabajo estaba dividido en partes muy finas, pero el estado estaba lleno de productos intermedios que no era necesario guardar; en la base de datos había bastante información almacenada, pero el contexto que recibía el modelo no necesariamente era útil.
Lo más incómodo era que, cada vez que cambiaba un requisito del producto, primero tenía que explicar por qué la arquitectura existente no lo soportaba bien y luego buscar la forma de forzarlo dentro.
Después, decidí reescribir.
Para facilitar la discusión, a continuación oculto el negocio concreto del proyecto y lo considero un Agent conversacional que necesita acumular contexto de forma continua y soportar interacción multiturno. Este artículo tampoco pretende enumerar todo el stack tecnológico; prefiero hablar de aquellos puntos que realmente me bloquearon y de cómo estos problemas cambiaron mi comprensión del desarrollo de Agents.
Uno. Tomé el estado del flujo de trabajo como la memoria del modelo
La arquitectura más temprana era un Pipeline bastante largo: cargar el objeto de negocio, organizar los materiales básicos, construir la query de recuperación, recuperar información, organizar el contexto y, finalmente, llamar al modelo.
Para facilitar el paso de datos entre nodos, metí casi todo lo que se generaba en el camino dentro del Graph State. Resultados de consultas, queries de recuperación, contexto a medio organizar e incluso instancias ORM de SQLAlchemy, todo iba ahí dentro.
En ese momento mi comprensión era muy simple: ¿acaso State no es precisamente los datos compartidos entre nodos? Lo pongo ahí y el siguiente nodo lo toma directamente, qué cómodo.
Hasta que conecté checkpoint y apareció el problema.
Primero, la serialización. Las instancias ORM no se podían entregar directamente como un diccionario normal a la cadena de serialización de checkpoint de aquel entonces. Segundo, el alcance de la persistencia: muchos datos temporales que solo servían durante esta ejecución también quedaban guardados junto con el estado.
Mi primera solución fue vaciar los campos intermedios en el último nodo. Solo después me di cuenta de que checkpoint registra el estado durante el proceso de ejecución, y vaciarlo una vez al final no elimina las instantáneas que ya se habían escrito antes.
Pero ese no era el mayor problema.
Para soportar preguntas de seguimiento continuas, quería que la segunda ronda reutilizara directamente el contexto guardado en la primera ronda y ahorrarse un proceso de construcción que consumía tiempo. Configuré el mismo thread_id y volví a llamar al Graph, pero el modelo seguía como si no hubiera visto la ronda anterior.
Al revisar la cadena con cuidado, la razón era bastante directa: el estado se había restaurado, pero cuando llamé al modelo solo construí un nuevo HumanMessage. La información histórica estaba ahí en el State, pero no se había organizado dentro de esta solicitud, así que el modelo, naturalmente, no podía verla.
Lo más absurdo fue que, en la entrada de la segunda ronda, además pasé una cadena vacía al campo de contexto. La intención original era expresar "esta ronda no recalcular", pero el efecto real fue sobrescribir el estado existente con un valor vacío...
Después de esto, realmente separé varias cosas:
| Datos | Responsabilidad en el sistema |
|---|---|
| Variables temporales dentro del nodo | Completar el paso actual; se pueden descartar al usarse |
| Graph State | Estado de ejecución que se pasa entre nodos y se restaura según sea necesario |
| Historial de mensajes | Contenido de conversación que debe conservarse en la interacción multiturno |
| Entrada del modelo en esta ronda | Información que la tarea actual realmente necesita consumir |
checkpoint puede ayudar a restaurar el estado de ejecución, pero qué contenido entra en la entrada del modelo sigue siendo algo que debo diseñar yo. A la inversa, que el State sea grande tampoco significa que cada solicitud vaya a consumir muchos tokens; solo cuando estos contenidos se envían al modelo se convierten en costo de entrada.
Esta distinción parece muy básica, pero ciertamente tuve que tropezar una vez para entenderla.
También reconsideré la división de nodos. Antes casi dividía un nodo por función, y luego llegué al otro extremo, metiendo toda la cadena de vuelta en un solo nodo. Al seguir trabajando me di cuenta de que los límites de los nodos deben seguir las necesidades de ejecución: los pasos que necesitan observación independiente, enrutamiento por ramas o programación paralela vale la pena separarlos; la lógica de transformación que solo se usa localmente basta con una función normal.

Dos. A veces el modelo procesa lento porque yo le planteé un problema demasiado difícil
Había una cadena de entrada temprana que necesitaba recuperar registros estructurados a partir de capturas de pantalla.
Le pedía al modelo identificar el hablante, el contenido y la hora de cada mensaje, y luego organizarlo en un JSON estricto. Para mejorar la precisión, también añadí bastantes restricciones al usuario: subir las capturas en orden, incluir la hora, controlar el número de imágenes, etc.
El resultado no fue ideal. En un intento, dos capturas tardaron aproximadamente dos minutos en procesarse y todavía había confusión temporal, hablantes desalineados y contenido inválido.
La primera reacción, por supuesto, fue seguir ajustando el prompt. Pero al revisar de nuevo el uso final, de repente me di cuenta de que no necesitaba recuperar el registro original completo, sin omitir ni una sola línea.
Lo que realmente necesitaba el downstream era: sobre qué tema gira este material, qué información vale la pena conservar y en qué contexto ocurren.
Así que ajusté la granularidad de los datos de "registros originales uno por uno" a "información organizada en torno a un tema". El modelo ya no asumía la tarea de reconstruir completamente el registro, y la recuperación posterior tampoco necesitaba recomponer primero el significado a partir de una gran cantidad de mensajes dispersos.
Por supuesto, esta solución también tenía un costo en aquel momento: pedía al usuario que el material enviado en una sola vez perteneciera, en lo posible, al mismo tema, lo que equivalía a devolverle al usuario parte del trabajo de segmentación. Aliviaba la carga de procesamiento, pero todavía no podía considerarse una solución completa a la experiencia de entrada.
Esto me hizo empezar a acostumbrarme a hacerme dos preguntas antes de optimizar el modelo: ¿qué información necesita realmente la función final? ¿La granularidad que ahora le pido al modelo supera el uso real?
Que la base de datos pueda contener registros originales no significa que el modelo deba reconstruirlos uno por uno; que el modelo pueda producir una estructura compleja tampoco significa que el producto necesite que el usuario espere a que llene esa estructura.
Tres. La dificultad del contexto pasó de "guardarlo" a "cómo usarlo en esta ronda"
Al principio, cuando hacía memoria, mi atención estaba principalmente en el lado de la escritura: cómo extraer la información, cómo modelar los datos, cómo vectorizar el texto.
Más tarde, al entrar en contacto con algunas soluciones que organizan el contexto con Markdown, descubrí que tenían muchas cosas que valía la pena tomar como referencia en la clasificación y expresión de la información. Pero entre las soluciones que probé, algunos archivos exigían lectura obligatoria en cada ronda, mientras que otros se cargaban completos bajo demanda.
Cuando había poca información, esto era muy directo. A medida que la información fue creciendo, empecé a preocuparme porque cada vez solo necesitaba una pequeña parte de la información, pero primero tenía que cargar el archivo completo.
Así que, al refactorizar, conservé los materiales básicos y dividí la información más detallada en entradas independientes, para soportar la recuperación posterior según la pregunta. Aquí, la base de datos se encarga de gestionar la pertenencia, clasificación y temporalidad de las entradas, y el contenido textual se encarga de expresar la semántica que el modelo necesita entender.
Pero con la recuperación vectorial, los problemas tampoco desaparecieron por sí solos.
Al principio, la recuperación dependía principalmente de la distancia semántica. Después fui añadiendo gradualmente filtrado por ámbito de negocio, pesos de importancia y decaimiento temporal para parte de la información. Porque "ser muy similar a la pregunta" y "ser adecuado para la respuesta actual" no son lo mismo.
Especialmente el tiempo.
Alguna vez solo puse una "hora actual" en el prompt del sistema, y luego me di cuenta de que no podía indicar cuándo ocurrió cada mensaje histórico. Yendo más hacia arriba, incluso si la base de datos tiene la hora de creación, si el texto extraído pierde el año, período o etapa del material original, el modelo sigue confundiendo fácilmente cosas similares ocurridas en momentos distintos.
Los ajustes posteriores se dividieron en dos partes: los mensajes de conversación llevan explícitamente una marca de tiempo; al extraer información, los anclajes temporales confirmables del material se conservan en el cuerpo del texto, y los tiempos que no se pueden determinar no se completan.
Esto está más adelante que simplemente ajustar la fórmula de ordenación. Si la información temporal se pierde durante la extracción, es muy difícil recuperarla de la nada en la etapa de recuperación.
Además, también probé encapsular la recuperación de conocimiento como una Tool, para que el modelo decidiera cuándo necesitaba complementar materiales y evitar ejecutar mecánicamente todo el conjunto de recuperación en cada ronda.
Pero Tool Call reveló otro límite: el modelo no puede generar de forma estable el ID del objeto de negocio actual. Ese ID ya estaba en el contexto de ejecución del sistema, y aun así le pedía al modelo que lo adivinara otra vez.
Al final, inyecté antes de ejecutar la herramienta los parámetros ya determinados en el contexto actual. El modelo puede decidir si necesita recuperar y qué recuperar; en cuanto a quién es el usuario actual, qué objeto está operando y si tiene permiso de acceso, eso debe determinarlo y validarlo el programa.
Después de trabajar en estos problemas, mi comprensión del contexto pasó de "recopilar la mayor cantidad posible" a: conservar la información necesaria para la tarea actual y hacer que entre en el modelo en una forma adecuada.
En cuanto a cuánto mejoró realmente el efecto con cada cambio, no tengo datos de evaluación suficientemente sistemáticos y no quiero inventar aquí un porcentaje. Lo que puedo confirmar es que empecé a saber por qué cadena debo investigar, en lugar de mirar solo la respuesta final y ajustar el prompt.
Cuatro. Dividir directorios no significa que realmente se haya desacoplado
Cuando hacía proyectos web en el pasado, tenía la costumbre de escribir primero el backend, luego envolverlo con una interfaz HTTP y finalmente dárselo al frontend para que lo llamara. Este Agent también siguió al principio una estructura similar, con las capacidades de negocio y el servicio web muy cerca.
Más tarde, el producto pasó a interactuar principalmente mediante IM, y además añadí una CLI para ejecutar operaciones de configuración, administración y diagnóstico. Llegados a este punto, que la capa de negocio siguiera dependiendo del framework web resultaba muy incómodo.
Así que separé el Service, para que asumiera las capacidades de negocio y acceso a datos, y que diferentes entradas lo llamaran.
Suena a que ya está desacoplado, ¿verdad? La realidad me dio otro golpe.
Una vez, al ejecutar el comando de ayuda de la CLI, lo que se imprimió fue la ayuda del framework web.
La razón era que el módulo de comandos importaba el Service, y el Service importaba en el nivel superior el tipo Request del framework web. Originalmente solo era una anotación de tipo, pero en tiempo de ejecución traía todo el framework y afectaba el análisis de argumentos de la línea de comandos.
La solución no era complicada: mover las dependencias de solo tipo bajo TYPE_CHECKING, mantener lo más ligera posible la fase de registro de comandos y cargar los módulos necesarios solo en el momento de la ejecución real.
Pero este pequeño asunto me hizo darme cuenta de que las flechas de dependencia en el diagrama de arquitectura, al final, deben materializarse en las importaciones de módulos y el comportamiento de inicialización. Un Service que parece muy limpio, si al importarlo arrastra el framework, lee argumentos o inicia conexiones externas, los problemas seguirán apareciendo al llamarlo desde otra entrada.
Más tarde, para simplificar la configuración del usuario, intenté llevar una parte de las capacidades de datos a un entorno remoto. Donde antes se obtenían objetos ORM, había que pasar a consumir estructuras de retorno explícitas; las operaciones de base de datos dispersas en la entrada y en el Graph también tenían que seguir concentrándose en el Service.
Añadí una capa de distribución unificada: el modo local llama al Service, el modo remoto llama a la API HTTP correspondiente. La serialización también se maneja en este límite, para evitar que la conversión de enums, objetos de tiempo y parámetros opcionales quede dispersa por todas partes.
Por ejemplo, un parámetro de consulta con valor por defecto: en una función de Python pasar None es muy natural, pero al codificarlo como query HTTP puede dar error directamente. La corrección debe quedar en el límite de la solicitud, conservando al mismo tiempo valores con significado real como 0 y False; tampoco se puede eliminar de paso el null explícito del cuerpo JSON de la solicitud.
Nada de esto es un algoritmo complejo, pero determina si "una función que se puede llamar localmente" puede convertirse en una interfaz remota confiable.
Cinco. Si el usuario configura una base de datos menos, el sistema asume un conjunto más de responsabilidades
Hacer la CLI y la entrada por IM fue, al principio, para reducir la cantidad de desarrollo de un frontend independiente y también para que los usuarios interactuaran en lugares que ya conocen.
Pero al encadenar el proceso de instalación, me di cuenta de que solo me había ahorrado el frontend; el usuario seguía teniendo que preparar la base de datos, la configuración del modelo y la configuración del bot. Que el código se ejecute no significa que el usuario esté dispuesto a usarlo; entre ambas cosas hay todavía un largo camino.
Por eso intenté que el servidor asumiera el acceso a la base de datos, reduciendo la carga de que el usuario tuviera que crear su propia base de datos.
La primera restricción era clara: no se podían enviar al cliente las credenciales de conexión de la base de datos compartida solo por comodidad. Las operaciones de datos normales podían asumirse mediante una API autenticada, pero el checkpoint del flujo de trabajo depende de la conexión a la base de datos, y no iba a obtener automáticamente capacidad de almacenamiento remoto porque añadiera una ruta HTTP.
La solución en aquel momento fue conservar dos comportamientos: el modo local seguía usando PostgreSQL para persistir el checkpoint; el modo compartido experimental pasaba a usar memoria del proceso.
El costo también era claro: después de reiniciar el proceso, esta parte de la memoria a corto plazo en el modo compartido se perdía.
No resolví del todo este problema, solo acepté una degradación a cambio de una forma de ejecución que no expusiera al cliente la conexión a la base de datos. Tampoco significa que checkpoint no pueda volverse remoto alguna vez, solo que la capa de distribución de aquel entonces no lo cubría, y el costo de seguir abstrayendo ya superaba el objetivo de esa ronda.
El problema más incómodo estaba por venir.
Algunos Services que parecían ser de "sincronización de datos" en realidad llamaban internamente al modelo. Al moverlos al servidor, ¿de quién debería ser la configuración del modelo que se use? ¿Cómo se pasa la configuración del usuario? ¿Quién asume el costo de la llamada?
Antes, en una sola máquina, la base de datos, la configuración del modelo y el entorno de ejecución estaban en el mismo lugar, y estos problemas se ignoraban fácilmente. Después de cruzar la red, cada uno de ellos hay que responderlo de nuevo.
Lo mismo ocurre con el estado de inicio de sesión. Para reducir las interrupciones de las tareas en segundo plano por la expiración del token, en un momento adopté un enfoque sin tiempo de expiración. Pero los problemas de rotación, revocación y gestión de invalidación que deja siguen existiendo; no porque la cadena principal siga funcionando se puede decir que la autenticación esté completamente diseñada.
Al final, aunque parte de la cadena del modo compartido ya estaba conectada, seguí ocultando la entrada de configuración pública. Si la propiedad de la configuración del modelo y el límite de la ejecución en nombre del servidor no están bien resueltos, no se debe dejar que el usuario lo considere una opción ya preparada.
Este también fue un cambio en mi forma de ver el producto: reducir el costo de uso significa que alguien tiene que asumir la complejidad que antes se le entregaba al usuario. Si el usuario ya no tiene que configurar la base de datos, el servidor debe asumir los permisos, la configuración y la responsabilidad operativa correspondientes. Un "Easy Mode" está lejos de ser solo mostrar menos campos de entrada.

Seis. Un fallo del servicio de prompts me hizo reconsiderar las dependencias de ejecución
Hubo otra lección que casi no tenía relación con la capacidad del modelo.
Para facilitar el ajuste, puse los prompts en una plataforma externa y los obtenía en tiempo real durante la ejecución. Modificar los prompts no requería volver a publicar, y la experiencia de desarrollo era realmente buena.
Luego el servicio de la plataforma falló.
No había conservado una copia de seguridad local ni había diseñado un respaldo para fallos de lectura, así que todas las cadenas que involucraban prompts se cayeron de golpe. El servicio externo se recuperó aproximadamente dos días después, pero esos dos días fueron suficientes para darme cuenta de que había convertido una herramienta de comodidad para el desarrollo en una dependencia dura en tiempo de ejecución.
La lección de esto fue muy concreta. Aunque el prompt es un fragmento de texto, en el sistema asume lógica de ejecución real; su versión, respaldo y disponibilidad deben tratarse con seriedad. Gestionarlo en remoto no hace que estas responsabilidades desaparezcan.
Durante el desarrollo posterior, también empecé a consolidar en Skills los requisitos de colaboración que se repetían: hacer control de calidad tras los cambios, registrar modificaciones, sincronizar la documentación de Graph y escribir las correcciones en las reglas.
Estos procedimientos no pueden sustituir a las pruebas ni garantizan que el Agent se ejecute correctamente cada vez. Pero al menos, cuando vuelva a aparecer el mismo tipo de omisión, tengo la oportunidad de modificar las reglas que se consumen de forma continua, en lugar de solo recordarlo una vez más.
Escribiendo hacia el final
Mirando atrás, esta reescritura no consistió en comprender todos los problemas en un solo día y luego dibujar un nuevo diagrama de arquitectura para completarla de una vez.
Primero malinterpreté el checkpoint y luego rediseñé el estado; primero perseguí una entrada de grano fino y luego volví a la semántica que realmente necesitaba la parte posterior; primero separé la capa de negocio y eliminé entradas innecesarias, y más tarde, por el nuevo modo de despliegue, volví a añadir el servicio HTTP. Surgen nuevos problemas constantemente y las decisiones tomadas antes también se revisan de nuevo.
Ya no me obsesiono tanto con «si elegí mal el framework en su momento». Lo que realmente me hizo dar rodeos fue no tener claros algunos límites más básicos: qué necesita persistirse, qué debe entrar en el modelo, qué parámetros decide el programa y qué responsabilidades se llevan consigo cuando una capacidad cambia de lugar de ejecución.
Ahora, cuando empiezo a escribir una nueva funcionalidad, dedico un poco más de tiempo que antes a preguntarme estas cosas. No necesariamente me hacen acertar a la primera, pero me permiten escribir menos código que parece ya terminado y que, al cambiar de escenario, hay que derribar de nuevo.
En cuanto a esta reescritura, el resultado que más me gustaría conservar son, probablemente, estas preguntas que seguirán influyendo en cómo escribo código más adelante.