Siete formas silenciosas en las que la contaminación de contexto daña a los agentes LangGraph

Imagínese un agente de LangGraph que le dice a un usuario que su proyecto está “en camino para ser entregado en julio”. El calendario indica agosto. Los registros no muestran excepciones ni llamadas a herramientas fallidas, y no hay nada en rojo en ningún lugar. Según todas las métricas que sigue el equipo, el agente funciona correctamente, pero durante tres días engaña silenciosamente a las personas hasta que alguien se da cuenta.

Incidentes como este comparten una causa invisible: la contaminación del contexto, y los siete casos siguientes se deben todos a ella. Cada uno generó cero errores. Estos escenarios son ficticios e ilustrativos, con nombres de empresas y números inventados, pero la mecánica detrás de ellos es del tipo con el que los desarrolladores de agentes se encuentran regularmente.

Contaminación del contexto en dos minutos

Cuando un agente razona, no ve su aplicación. Ve un único bloque largo de texto, la ventana de contexto, y nada más. Piénselo como un escritorio: todo lo que está sobre el escritorio es utilizable, y cualquier cosa fuera de él no existe para el agente, incluso si se encuentra en su base de datos a pocos metros de distancia.

Cada turno se acumulan varias cosas en ese escritorio:

• la indicación del sistema, es decir, las instrucciones
• las definiciones de herramientas, es decir, lo que el agente puede utilizar
• el historial de conversación, es decir, todo lo dicho hasta el momento
• las salidas de las herramientas, es decir, lo que devuelven sus APIs
• el estado, que es lo que almacenan y transmiten los nodos de LangGraph
• los documentos recuperados, si utiliza RAG

Los principiantes rara vez escuchan esto: el escritorio tiene un límite de tamaño, y la atención no se distribuye de manera uniforme sobre él. El contenido puede estar técnicamente presente pero ser ignorado en la práctica. También puede estar desactualizado, duplicado o contradictorio, y el modelo no pondrá objeciones. Analiza ese material inútil sin hacer comentarios.

La contaminación por contexto se refiere a material obsoleto, sobredimensionado o contradictorio que permanece en el sistema y empeora el rendimiento sin generar ni un solo error. Ese es el peligro: una falla grave te hace cerrar el sistema a las 2 a.m., mientras que la contaminación simplemente deja a tu agente con un 20% de errores de forma indefinida.

Cada caso que se presenta a continuación incluye un síntoma, una causa raíz, una solución y una forma de detectarlo en tu propio sistema, porque un fallo que no puedas detectar volverá a ocurrir.

Caso 1: el agente atascado en julio

Síntoma. Tomemos como ejemplo un agente de generación de informes para una aplicación ficticia, llamémoslo Meridian Energy. Este agente seguía mostrando cifras “de este mes” que en realidad pertenecían al mes anterior. Los usuarios culpaban al sistema de procesamiento de datos, lo cual era comprensible.

Causa raíz. Al inicio de la sesión, un desarrollador había almacenado el período de generación de informes activo en el estado de LangGraph exactamente una vez (una clave llamada current_period con el valor 2026-07), y el punto de control lo guardó. Más tarde, los usuarios reanudaron sesiones antiguas, una función muy utilizada, y el punto de control guardado volvió a incluir los datos correspondientes a julio. El agente no se confundió; siguió su contexto, y en ese contexto se indicaba julio.

Solución. Adopte una regla que modifique el diseño del estado: nunca almacene lo que pueda volver a calcularse fácilmente. La fecha actual, el período actual y cualquier elemento etiquetado como “hoy” deben calcularse nuevamente al inicio de cada ejecución, en lugar de guardarse. Mover current_period fuera del estado guardado y a un nodo pequeño que lo recalcule en cada llamada solo requiere una línea de código y elimina todo tipo de errores.

Detección. En el desarrollo, imprima el diccionario de estado al inicio de cada ejecución y pregúntese si cada clave podría estar desactualizada y si usted se daría cuenta. Cualquier clave que contenga una fecha, un estado o la palabra “actual” es sospechosa.

Caso 2: un volcado de herramienta con 8,000 tokens que ahogó las instrucciones

Síntoma. El agente comenzó a ignorar las reglas de formato. La instrucción del sistema indicaba abrir cada respuesta con una tabla resumida. Así lo hacía, hasta que a veces no lo hacía. De forma aleatoria, lo cual es el peor tipo de error.

Causa raíz. Una herramienta llamada API insertó la respuesta JSON en bruto dentro del contexto. En consultas pequeñas, eso representaba 400 tokens. En las grandes, la cantidad superaba los 8,000 tokens de JSON anidado lleno de IDs, metadatos, campos nulos y detalles de paginación que nadie necesitaba. Al insertarse en medio del contexto, esa información convertía las instrucciones claras en una voz tenue al fondo de una habitación ruidosa. La atención se centró en ese muro de JSON y las reglas de formato desaparecieron prácticamente.

El detalle desagradable es que esto solo ocurría con respuestas grandes. Las consultas pequeñas funcionaban bien, por lo que relacionar “el agente se comporta mal” con “el usuario hizo una pregunta compleja” llevó semanas.

Solución. Las herramientas deben devolver datos concretos, no volúmenes masivos de información. Se debe añadir una capa de transformación sencilla dentro de cada herramienta que extraiga los pocos campos que necesita el agente, los organice de forma compacta y descarte el resto. Una herramienta de este tipo pasó de aproximadamente 8,000 tokens a unos 300.

# Before: return response.json()          # 8,000 tokens of noise
# After:
def summarize_response(data: dict) -> dict:
    return {
        "project": data["name"],
        "status": data["status"],
        "owner": data["owner"]["displayName"],
        "due": data["dueDate"],
        "open_risks": len(data.get("risks", [])),
    }                                       # ~300 tokens of signal

Detección. Registre la cantidad de tokens de cada salida del herramienta. Una herramienta que puede devolver más tokens que todo el prompt del sistema es una fuente de contaminación que espera generar una respuesta extensa.

Caso 3: una corrección que nunca reemplazó lo original

Síntoma. Un usuario pide información sobre la región del Noreste y luego se corrige de inmediato, pidiendo datos sobre el Noroeste. El agente responde correctamente sobre el Noroeste. Después de cuatro interacciones, sin que se le pregunte, vuelve a hablar del Noreste.

Causa raíz. El historial de conversaciones está configurado por defecto para que solo se añadan nuevos datos, por lo que tanto la instrucción errónea como la corrección permanecen en el contexto de forma permanente. Normalmente el modelo da prioridad a los mensajes más recientes, pero no siempre es así, y a medida que crece la conversación, las dos versiones se vuelven hechos igualmente plausibles. El agente no estaba recordando incorrectamente; simplemente recordaba demasiado.

Solución. Hay dos opciones.

1. Resolver, no acumular. Al detectar una corrección, no basta con añadirla al final. Escriba el nuevo valor en un bloque de datos estructurados en el estado (con la región establecida en Northwest) que el agente considere como fiable, de modo que no sea necesario volver a discutir la transcripción confusa en cada turno.
2. Editar el historial. LangGraph permite recortar o reescribir mensajes antes de que vuelvan a formar parte del contexto, por lo que las instrucciones obsoletas pueden eliminarse simplemente.

La lección general es que el historial de una conversación es un registro y no una base de conocimientos. No haga que el agente obtenga la verdad a partir de la transcripción en cada turno.

Detección. Añada un caso de autocorrección a sus pruebas: el usuario dice X, luego lo corrige a Y y hace cinco preguntas más. Si el agente vuelve a usar X, entonces existe este error.

Caso 4: RAG devolvió una respuesta cinco veces y ocultó la real

Síntoma. Las personas hicieron una pregunta a la que la documentación respondía claramente, pero el agente proporcionó una respuesta vaga e incompleta. Los registros de recuperación mostraron seis fragmentos obtenidos, por lo que parecía que el sistema de recuperación estaba funcionando correctamente.

Causa raíz. El corpus contenía casi duplicados: un párrafo de la política copiado en cinco documentos diferentes, como suelen hacer las empresas reales. La búsqueda de similitudes funcionó a la perfección y devolvió cinco fragmentos casi idénticos, los cuales desplazaron al único fragmento diferente que contenía la respuesta real. Cinco plazas en la mesa quedaron ocupadas por el mismo “invitado”.

Solución. Eliminar las duplicadas en el momento de la recuperación. Incluso un método rudimentario funciona bien: obtener 20 candidatos, descartar cualquier fragmento demasiado similar a uno ya seleccionado y conservar el conjunto más diverso. Si su almacén de vectores admite la relevancia marginal máxima, esa misma idea ya está implementada. La calidad de las respuestas a preguntas basadas en políticas mejoró de inmediato sin necesidad de modificar el modelo ni la instrucción.

Detección. Registrar los fragmentos recuperados y revisarlos semanalmente. Si una oración aparece regularmente dos veces en un lote, está pagando por redundancia a costa de la relevancia.

Caso 5: el resumen que ignoró la regla más importante

Síntoma. Para mantener económicas las sesiones largas, un equipo implementó una resumen dinámico: cada N turnos, los mensajes antiguos se comprimen. Es el método estándar y ampliamente recomendado. Sin embargo, un agente comenzó a incluir borradores en los informes oficiales, a pesar de que el usuario había indicado “excluir borradores” once turnos antes.

Causa raíz. El sistema de resumen se comportó como tal. Mantuvo la información esencial (el usuario quería informes regionales y habló sobre el diseño) y descartó lo que consideró secundario. Pero “excluir borradores” no era algo secundario; era una restricción, y las restricciones no pueden reinterpretarse: o se respetan tal cual o desaparecen. De los siete fallos, este es el que merece más preocupación, ya que la función de resumen parece ser una ventaja evidente en las demostraciones.

Solución. Separar la memoria en dos canales antes de realizar cualquier compresión.

• Narrativa: se puede resumir de manera agresiva.
• Restricciones, decisiones y preferencias: se incluyen en una lista estructurada que nunca se resume. Solo se añaden nuevas entradas o se revocan explícitamente, y toda la lista se incorpora al contexto en cada turno.

La instrucción de resumen puede indicarlo directamente: antes de resumir, copie cada instrucción, restricción y decisión tal cual al listado de restricciones.

Detección. Durante el desarrollo, compare la lista de restricciones antes y después de cada ejecución de resumen. Una restricción que solo permanece dentro de un párrafo de resumen significa que el compresor está alterando sus reglas.

Caso 6: un seguimiento de llamadas que hizo que el agente desconfiara de una herramienta funcional

Síntoma. Una herramienta tuvo un tiempo de espera breve una vez y funcionó en la siguiente llamada. Sin embargo, durante el resto de la sesión, el agente siguió diciendo a los usuarios que no podía conectarse al sistema de informes, aun cuando lograba acceder a él con éxito. Naturalmente, los usuarios confiaron más en esas palabras que en los datos.

Causa raíz. El rastro completo del error, un TimeoutError después de 30 segundos, se añadió al historial y nunca se eliminó. Para el modelo, “el sistema de informes es poco fiable” pasó a ser un hecho establecido, y todas las respuestas posteriores se vieron influenciadas por ello. Un error temporal se convirtió en una contaminación permanente.

Solución. Trate los errores como eventos y no como hechos. Después de un intento de reintentar exitoso, reemplace el error en el historial con una nota de una línea como "(error temporal, resuelto al reintentar)". Si una herramienta falla de forma permanente, proporcione al agente un estado estructurado y claro, y no una traza de pila. Las trazas de pila pertenecen a los registros, nunca al contexto.

Detección. Busque en los contextos en tiempo real las cadenas Error, Traceback y Exception. Cada coincidencia representa ya sea un incidente en curso o un residuo que contamina análisis posteriores, y ambos deben eliminarse.

Caso 7: veinticinco herramientas en una sola ventana

Síntoma. A lo largo de varios meses, la herramienta se volvió más lenta y costosa, lo cual era predecible dado que se añadían continuamente nuevas funciones. También comenzó a seleccionar la herramienta incorrecta para solicitudes sencillas, como devolver una exportación de cumplimiento cuando alguien quería un resumen del proyecto. Nada estaba roto; simplemente todo se había vuelto más complicado.

Causa raíz. El conjunto de herramientas había llegado a contar con 25 herramientas, cada una con una descripción extensa y un esquema JSON; en conjunto, consumían aproximadamente 12,000 tokens antes de que el usuario escribiera una sola palabra. En cada interacción, el modelo evaluaba 25 opciones, muchas de las cuales tenían descripciones similares como “obtener datos del proyecto”, “recuperar detalles del proyecto” y “consultar información del proyecto”. Elegir una herramienta es una tarea de razonamiento, pero el equipo la convirtió en un examen de opción múltiple con 25 respuestas similares.

Solución. En dos partes.

1. Elimine de forma agresiva. Combine las herramientas que se superponen, reduciendo de 25 a 11 en este caso, y reescriba cada descripción centrada en una pregunta: ¿cuándo debería el modelo elegir esta herramienta en lugar de sus vecinas?
2. Cargue las herramientas según el contexto. No todo nodo necesita todas las herramientas. En LangGraph es sencillo vincular solo el subconjunto relevante a cada nodo, de modo que un nodo dedicado a generar informes podría ver cuatro herramientas en lugar de 25.

El costo por token por turno disminuyó en aproximadamente un tercio, y las selecciones erróneas de herramientas prácticamente desaparecieron.

Detección. Cuente únicamente los tokens en las definiciones de sus herramientas. Si superan la longitud del prompt del sistema más la de una conversación promedio combinada, su agente está realizando un examen con el libro abierto donde la mayoría de las páginas están incorrectas.

Lo que tienen en común los siete

Al leerlo de nuevo, surge un patrón claro: ningún componente estaba dañado y faltaba algo. La “contaminación” se debía consistentemente a contenido excesivo, obsoleto o repetido.

Por eso los métodos habituales de depuración fallan aquí. Los ingenieros están entrenados para buscar ausencias: la verificación null faltante, la excepción no manejada. La “contaminación” por contexto requiere habilidades opuestas: aprender a buscar aquello que no debería estar allí.

Si solo mantienes un hábito, que sea leer el contexto en bruto de tu agente. Omite los registros y el panel de seguimiento, y lee el texto real que recibe el modelo en una operación real de producción. Es la hora más valiosa para quienes desarrollan agentes, y casi nadie la aprovecha.

Lista de verificación de sesenta segundos antes de desplegar

1. ¿Algún valor de estado es una fecha, un estado o algo llamado “current”? (Caso 1)

¿Podría una herramienta devolver más tokens que el propio prompt del sistema? (Caso 2)

¿Cuando un usuario se corrige a sí mismo, puede la versión anterior ganar alguna vez? (Caso 3)

¿Se repiten alguna vez los fragmentos recuperados? (Caso 4)

¿Puede una restricción sobrevivir palabra por palabra al resumen generado? (Caso 5)

¿Permanecen las huellas de errores en el historial después de la recuperación? (Caso 6)

¿Cuántos tokens utilizan las definiciones de la herramienta antes de que el usuario escriba algo? (Caso 7)

Siete preguntas. Cualquier respuesta de “probablemente, pero no estoy seguro” es un incidente que espera su momento.

Lecturas relacionadas

• Ingeniería de contexto para aplicaciones LLM: salida estructurada, herramientas y límites de los agentes — Cómo diseñar intencionalmente la entrada del modelo: selección de contexto, plantillas de prompts, esquemas JSON, decodificación restringida, llamadas a herramientas, bucles de agentes y autonomía limitada.
• ¿Cuándo debería un AI usar su memoria? Experimentos con memoria persistente y adulación — Recuperar una memoria no es lo mismo que permitir que esta moldee la respuesta. Pequeños experimentos con memorias tipadas y un controlador de influencia muestran beneficios parciales contra la adulación.