Traducción automática

Este artículo se tradujo automáticamente a partir de la versión original en inglés.

Ingeniería de contexto para agentes de IA: ventanas de contexto, memoria, herramientas y guardrails

TL;DR

La ingeniería de contexto es el pipeline que decide qué ve el modelo en el momento de decidir: instrucciones, ejemplos, conocimiento, memoria, habilidades, herramientas, guardrails. La mayoría de los agentes en producción o funcionan o se rompen en esta capa. Abajo está el plano al que vuelvo una y otra vez, con los patrones que uso de verdad.

El mismo agente que borda una demo de 30 minutos puede venirse abajo al tercer día en producción. Casi siempre, el fallo no tiene nada que ver con el modelo y sí con lo que había en el contexto cuando tomó la decisión equivocada. Una memoria desactualizada. Un documento que ya no es relevante. Una descripción de herramienta que se ha desviado. Una instrucción vaga.

La ingeniería de contexto es lo que haces para evitar que eso ocurra: diseñar lo que ve el modelo antes de cada decisión, a propósito y con un presupuesto. Este artículo recorre los patrones que uso.

---

Por qué la ingeniería de contexto importa para los agentes de IA

Un agente de soporte al cliente funciona durante tres semanas y gestiona 200 tickets. Entonces empieza a alucinar detalles del producto, a mezclar clientes y a llamar a las APIs equivocadas. El modelo no empeoró. El contexto sí.

En 2025 cambiaron cuatro cosas que hacen que esto sea más doloroso que antes. Los agentes dejaron de ser chatbots y empezaron a ejecutar acciones, lo que significa que una sola mala decisión de contexto puede propagarse por un plan de diez pasos en lugar de producir una única mala respuesta. La memoria centralizada y estándares como MCP permiten cargar contexto personal de forma segura, pero solo si diseñas bien la capa: sin gobernanza filtras PII o revientas la ventana. La recuperación híbrida, el reranking y la recuperación consciente de grafos ya han madurado, lo que reduce alucinaciones y tokens, siempre que de verdad enrutes las consultas a la estrategia correcta. Y la mayoría de los pilotos agentic que veo estancarse se estancan en el diseño y la gobernanza del contexto, no en la calidad del modelo. Una capa de contexto deliberada es lo que los desbloquea.

---

Conceptos clave para principiantes

Algunos términos que aparecen a lo largo del artículo:

• Ventana de contexto: la memoria de trabajo del modelo. El texto máximo (en tokens) que puede mirar en una única decisión. Si la superas, el modelo falla o se olvida del principio.
• Tokens: la unidad en la que se trocea el texto. Aproximadamente, 1.000 tokens son 750 palabras.
• Presupuesto de atención: los modelos de lenguaje atienden a cada par de tokens, así que para n tokens hay n² relaciones. A medida que crece el contexto, ese presupuesto se reparte demasiado y los tokens del medio salen perdiendo frente al principio y al final.
• Embeddings: representaciones numéricas del texto. Permiten buscar por significado, así que una consulta de "dog" puede encontrar "puppy".
• JSON Schema: una forma estándar de describir la estructura de datos JSON. Se usa para forzar al modelo a generar campos concretos, como {"answer": "...", "citations": [...]}.
• MCP (Model Context Protocol): un estándar abierto que permite que los modelos de IA hablen con datos y herramientas externas a través de una interfaz común. Piensa en ello como un puerto USB para conectar un agente a tus archivos locales, bases de datos o Slack.

---

¿Qué es la capa de contexto?

Un pipeline más una política que selecciona y estructura entradas por paso, aplica controles (formato, seguridad, política) y alimenta al modelo con el contexto justo, en el momento justo.

Piensa en ello como la línea de montaje que prepara exactamente lo que el modelo necesita para tomar una buena decisión.

El contexto es un recurso finito. Los modelos, igual que los humanos con memoria de trabajo limitada, tienen un presupuesto de atención que se agota a medida que crece el contexto. Cada nuevo token consume una parte. El problema de ingeniería consiste en encontrar el conjunto más pequeño de tokens de alta señal que te dé la respuesta que quieres.

No hay una descomposición canónica única: distintos equipos despliegan stacks distintos. La que yo uso se parece a esto:

1) Instrucciones

Un contrato duradero de comportamiento: rol, tono, restricciones, esquema de salida, objetivos de evaluación. Los modelos modernos respetan jerarquías de instrucciones (system > developer > user), así que usa esa jerarquía de forma explícita en vez de meterlo todo en un único bloque.

Recurrimos a las instrucciones cuando necesitamos salidas consistentes (informes, SQL, llamadas API, JSON) o cuando hay que aplicar políticas: redactar PII, rechazar peticiones de cosas que no soportas, no incluir nunca URLs internas. Los patrones que funcionan en la práctica son los obvios: mantén los bloques de política separados de la tarea del usuario, guía el código downstream determinista con JSON Schemas y separa los mensajes de system, developer y user para que el modelo sepa de qué voz viene cada instrucción.

Un ejemplo sencillo de bloque de política:

SYSTEM RULES
- Role: support assistant for ACME.
- Always output valid JSON per AnswerSchema.
- If a request needs account data, ask for the account ID.
- Never include secrets or internal URLs.

---

Razonamiento guiado por esquemas (SGR)

La mejora más útil sobre "darle instrucciones al modelo" es hacer que esas instrucciones sean estructurales. Guía al agente con JSON Schemas para el plan, los argumentos de herramientas, los resultados intermedios y la respuesta final. El modelo genera y consume JSON en cada paso, y tu código lo valida antes de que ocurra cualquier otra cosa. Esto reduce la ambigüedad, hace que los reintentos sean deterministas y mejora la seguridad porque los tipos y los campos obligatorios se aplican durante todo el bucle.

El flujo es corto. Define esquemas para Plan, ToolArgs, StepResult y FinalAnswer. En cada paso, el modelo genera un JSON que encaja con uno de ellos. Tu código valida. Si la validación falla, intenta una reparación automática (por ejemplo, rellenar campos obligatorios ausentes con valores por defecto razonables). Si la reparación falla, rechaza y registra.

En concreto: en lugar de que el modelo diga "Voy a buscar los tickets del cliente", genera

{
    "action": "call_tool",
    "tool": "search_tickets",
    "args": { "customer_id": "A-123", "limit": 10 },
    "expected_schema": "TicketList"
}

y tu código valida args contra el esquema de la herramienta antes de llamar a la API.

---

2) Ejemplos

Unas pocas parejas cortas de entrada-salida que muestran el formato exacto, el tono y los pasos que debe seguir el modelo. Recurre a ejemplos cuando necesites una plantilla concreta (tablas, JSON, SQL, llamadas API) o cuando quieras formulaciones específicas del dominio y un tono consistente.

Hay unas cuantas reglas que sigo reaprendiendo. Muestra la estructura objetivo exacta en tu demo canónica, no una paráfrasis. Empareja buenos ejemplos con malos: contrastar un error típico con el resultado deseado enseña más que dos salidas correctas. Combina tu JSON Schema con dos o tres demos cortas en vez de una larga. Y mantenlos breves: muchas demos pequeñas y enfocadas ganan casi siempre a un ejemplo enorme.

---

3) Conocimiento

Anclar el modelo con hechos externos: recuperación vectorial y por palabras clave, reranking, consultas a grafos, web fetches, fuentes empresariales. Lo necesitas cuando el modelo no puede conocer la respuesta por sus pesos: hechos recientes, hechos privados o cualquier cosa que necesite una cita.

La pila de retrieval por defecto que merece la pena usar es híbrida (BM25 más dense) con un reranker encima para reducir la factura de tokens. Recurre a la recuperación consciente de grafos (GraphRAG) cuando la respuesta requiera cruzar documentos, y a RAG adaptativo cuando un solo tipo de consulta no sirva para todo: a veces quieres no recuperar nada, a veces un único disparo, a veces un bucle iterativo.

Los parámetros que realmente mueven la calidad son menos de lo que sugiere la literatura. Trocea por frontera semántica (párrafos, secciones) en lugar de por tamaño fijo: el chunking es la única decisión que de verdad hace o rompe la calidad de retrieval en documentos reales. Empieza con top-k entre 10 y 20 para híbrido, luego rerank hasta 3 a 5. Usa MMR con λ alrededor de 0,7 como valor por defecto para diversidad. Y añade siempre referencias a las fuentes y citas directas en la salida, no porque el modelo alucine sin ellas, sino porque son lo que hace auditable la respuesta.

---

4) Memoria

Contexto duradero entre turnos y sesiones. La memoria a corto plazo mantiene el estado de la conversación. La memoria a largo plazo guarda hechos sobre el usuario y la aplicación. La memoria episódica guarda eventos. La memoria semántica guarda entidades. Usa memoria cuando quieras personalización y continuidad, o cuando varios agentes coordinen trabajo durante días o semanas.

Los patrones que sobreviven al contacto con producción: memorias de entidades (nombres, IDs, preferencias) con políticas de caducidad explícitas; retrieval acotado desde un almacén de largo plazo respaldado por vectores, pares clave-valor o un grafo; y vincular la memoria con compresión para que, cuando la memoria a corto plazo crezca demasiado, se resuma en lugar de truncarse. La parte de resumido se trata en Estrategias de compresión de contexto [7].

La política de caducidad que uso por defecto:

• Preferencias: 365 días.
• Eventos episódicos: 90 días.
• Estado a corto plazo: limpiar al final de la sesión.
• Entidades: sin caducidad, pero con validación periódica obligatoria.

---

5) Habilidades

Experiencia de dominio componible que los agentes descubren y cargan bajo demanda. El framework Agent Skills de Anthropic es el diseño de referencia para capturar conocimiento procedimental y compartirlo entre agentes.

Construir una skill para un agente es como preparar una guía de onboarding para una nueva contratación. — Anthropic Engineering Blog

Quieres habilidades cuando necesitas experiencia específica de dominio (manipulación de PDF, git, análisis de datos), cuando quieres procedimientos reutilizables entre agentes u organizaciones, o cuando quieres especializar un agente sin codificar comportamientos de forma rígida en el system prompt.

¿Qué es una skill?

Una skill es una carpeta organizada que contiene instrucciones, scripts y recursos que el agente puede descubrir y cargar cuando sean relevantes:

• Un archivo SKILL.md con un nombre, una descripción (en YAML frontmatter) y las instrucciones de la skill.
• Archivos adicionales — referencias, plantillas — que la skill puede incorporar.
• Código: Python u otros ejecutables que el agente puede ejecutar como herramientas.

Patrón de skills: progressive disclosure

El principio que permite escalar las skills es la progressive disclosure: cargar información solo cuando se necesita. (Consulta El principio de progressive disclosure más abajo para la versión general). Al arrancar, solo los nombres y las descripciones de las skills están en contexto; suficiente para que el agente sepa qué hay disponible. El SKILL.md completo solo se carga cuando la skill se activa. Los archivos referenciados más profundos solo se cargan cuando la skill activada los necesita.

Esto significa que el contenido de las skills es, en la práctica, ilimitado. El agente no paga contexto por lo que no usa.

┌─────────────────────────────────────────────────────────┐
│ Context Window                                          │
├─────────────────────────────────────────────────────────┤
│ System Prompt                                           │
│ ├── Core instructions                                   │
│ └── Skill metadata (name + description only)           │
│     • pdf: "Manipulate PDF documents"                   │
│     • git: "Advanced git operations"                    │
│     • context-compression: "Manage long sessions"       │
├─────────────────────────────────────────────────────────┤
│ [User triggers task requiring PDF skill]                │
│                                                         │
│ → Agent reads pdf/SKILL.md into context                 │
│ → Agent reads pdf/forms.md (only if filling forms)      │
│ → Agent executes pdf/extract_fields.py (without loading)│
└─────────────────────────────────────────────────────────┘

Buenas prácticas para skills

Las directrices de Anthropic se resumen en cuatro cosas. Empieza por la evaluación: ejecuta el agente sobre tareas representativas, encuentra las carencias y escribe skills para cerrarlas. Estructura para escalar: divide un SKILL.md grande en archivos separados y mantén rutas separadas cuando los contextos sean mutuamente excluyentes. Observa cómo usa el agente tus skills e itera sobre nombres y descripciones hasta que la precisión de activación sea alta. Y deja que el agente ayude: pide a Claude que capture enfoques exitosos en contenido de skill reutilizable.

Consideraciones de seguridad

Las skills introducen vulnerabilidades por definición: dan al agente nuevas capacidades a través de instrucciones y código. Instala solo desde fuentes de confianza. Audita antes de usar, incluidos los archivos empaquetados, las dependencias de código y cualquier conexión de red. Presta especial atención a las instrucciones que conectan la skill con servicios externos, porque ahí es donde suele empezar la exfiltración.

---

6) Herramientas

Llamadas a funciones que obtienen datos o ejecutan acciones: APIs, bases de datos, búsqueda, operaciones con archivos, uso del ordenador. Quieres herramientas cuando necesitas efectos secundarios deterministas y fidelidad de datos, o cuando orquestas bucles de plan-call-verify-continue.

Los patrones que uso por defecto son planificación tool-first con validadores posteriores a la llamada, salidas estructuradas entre pasos y fallbacks explícitos cuando fallan las herramientas (reintentar, luego degradar, luego human-in-loop).

Hay tres conceptos sobre los que conviene ser preciso. Idempotente significa seguro de reintentar sin efectos secundarios (GET sí, POST o DELETE no). Las postconditions son las comprobaciones que ejecutas después de cada llamada: resultado no vacío, estado igual a "ok", JSON válido. La cadena de fallback es el orden que sigues cuando algo sale mal: reintentar, luego degradar con elegancia y después escalar a una persona.

Una nota sobre MCP

MCP se está convirtiendo en el estándar para cómo los agentes se conectan a herramientas y datos [6]. En lugar de escribir un wrapper de API a medida para cada servicio, ejecutas un servidor MCP para cada uno y el agente descubre automáticamente las herramientas y recursos disponibles.

---

7) Guardrails

Validación de entrada y salida, filtros de seguridad, defensa frente a jailbreaks, aplicación de esquemas, política de contenido. Quieres guardrails cuando necesitas compliance o integridad de marca, y cuando quieres salidas tipadas y correctas y un comportamiento seguro.

La forma que aguanta en producción: rails programables (reglas de política más acciones), validadores de esquema y semánticos (tipos, regex, evals) y política centralizada con observabilidad (dashboards, red-teaming).

La decisión entre reparar o rechazar es donde los equipos suelen equivocarse. Las violaciones de esquema reciben un intento automático de reparación; si falla, se rechaza con un error claro. Las violaciones de política se saltan por completo el intento de reparación: se rechazan de inmediato y se sugiere una alternativa segura.

Cuatro tipos comunes de guardrail cubren la mayoría de necesidades en producción. Los guardrails de entrada detectan PII, prompt injection y toxicidad antes de que el modelo los vea. Los guardrails de salida aplican esquema, política de contenido y consistencia factual. Los guardrails de herramientas gestionan rate limiting, comprobaciones de permisos y umbrales de coste. Los guardrails de memoria redactan PII antes del almacenamiento y aplican caducidad.

---

Ejemplo concreto: un bot de soporte respondiendo a un ticket

Esto es lo que ensambla la capa de contexto cuando un cliente pregunta "¿Por qué no funciona mi API key?":

• Instrucciones: el rol es el de un asistente de soporte útil para ACME, citar fuentes, devolver JSON {answer, sources, next_steps}.
• Ejemplos: dos pares cortos P→R que muestran tono y forma JSON, uno sobre API keys y otro sobre facturación.
• Conocimiento: buscar en el centro de ayuda y en los runbooks del producto "API key troubleshooting"; incluir citas relevantes.
• Memoria: nombre del cliente "Sam", ID de cuenta "A-123", plan "Pro", última interacción "API key creada hace 3 días".
• Skills: cargar la skill ticket-handling con procedimientos de troubleshooting, políticas de escalado y plantillas de resolución.
• Herramientas: search_tickets(customer_id), check_api_key_status(key), create_issue(description).
• Guardrails: redactar los valores de API key en la salida; si falla el esquema, reparar una vez; si se viola la política (por ejemplo, una petición de borrar datos de producción), rechazar con educación.

El modelo recibe todo este contexto estructurado, genera una respuesta y los guardrails la validan antes de que vuelva al cliente.

---

Profundización en los fundamentos del contexto

Antes de que los patrones tengan sentido, la anatomía tiene que tenerlo.

La anatomía del contexto

El contexto tiene varios componentes distintos, cada uno con características y restricciones diferentes.

Los system prompts establecen la identidad del agente, las restricciones y las directrices de comportamiento. Se cargan una vez al inicio de la sesión y persisten durante la conversación. El truco está en encontrar la altura adecuada: lo bastante específicos como para orientar de verdad el comportamiento, pero lo bastante flexibles como para dejar margen al criterio. Si bajas demasiado, despliegas reglas rígidas y frágiles. Si subes demasiado, el modelo no tiene una señal concreta con la que actuar.

Organiza los prompts en secciones distintas usando etiquetas XML o encabezados Markdown:

<BACKGROUND_INFORMATION>
You are a Python expert helping a development team.
Current project: Data processing pipeline in Python 3.9+
</BACKGROUND_INFORMATION>

<INSTRUCTIONS>
- Write clean, idiomatic Python code
- Include type hints for function signatures
- Add docstrings for public functions
</INSTRUCTIONS>

<TOOL_GUIDANCE>
Use bash for shell operations, python for code tasks.
File operations should use pathlib for cross-platform compatibility.
</TOOL_GUIDANCE>

Las definiciones de herramientas especifican las acciones que el agente puede realizar. Cada herramienta tiene un nombre, descripción, parámetros y formato de retorno. Las descripciones son lo que de verdad orienta el comportamiento. Las malas descripciones obligan al agente a adivinar; las buenas incluyen contexto de uso, ejemplos y valores por defecto razonables. El principio de consolidación: si un ingeniero humano no puede decir con claridad a qué herramienta recurrir, un agente no lo hará mejor. Esa es tu señal para fusionarlas o renombrarlas.

Los documentos recuperados llevan contenido relevante al contexto en tiempo de ejecución en lugar de precargarlo todo. El enfoque just-in-time mantiene alrededor identificadores ligeros — rutas de archivo, consultas almacenadas, enlaces web — y carga los datos reales solo cuando hacen falta.

El historial de mensajes es la conversación entre usuario y agente, incluidas consultas previas, respuestas y razonamiento. En tareas de larga duración puede crecer hasta dominar la ventana. También actúa como memoria de trabajo, donde los agentes siguen el progreso y el estado de la tarea.

Las salidas de herramientas son los resultados de las acciones del agente: contenido de archivos, resultados de búsqueda, salida de comandos, respuestas de API. En trayectorias típicas de agentes, las observaciones terminan consumiendo más del 80% del contexto total [4]. Esa cifra es la presión que hay detrás de técnicas como el observation masking y la compactación.

Ventanas de contexto y mecánica de atención

Los modelos de lenguaje calculan la atención como relaciones por pares entre cada par de tokens. Para n tokens, eso son n² relaciones. A medida que crece el contexto, la capacidad del modelo para capturar esas relaciones se estira demasiado.

Los modelos también heredan sus patrones de atención de los datos de entrenamiento, y esos datos están dominados por secuencias más cortas. Así que el modelo tiene comparativamente poca experiencia con dependencias que recorren todo el contexto. El resultado final es un presupuesto de atención que se agota a medida que crece el contexto.

El principio de progressive disclosure

La progressive disclosure gestiona el contexto de forma eficiente cargando información solo cuando hace falta. Al arrancar, los agentes cargan solo nombres y descripciones de skills: suficiente para saber cuándo una skill puede ser relevante. El contenido completo solo se carga cuando se activa para tareas concretas.

# Instead of loading all documentation at once:

# Step 1: Load summary

docs/api_summary.md # Lightweight overview

# Step 2: Load specific section as needed

docs/api/endpoints.md # Only when API calls needed
docs/api/authentication.md # Only when auth context needed

Calidad del contexto frente a cantidad

La suposición de que ventanas de contexto más grandes resuelven los problemas de memoria ha quedado refutada empíricamente. La ingeniería de contexto consiste en encontrar el conjunto más pequeño posible de tokens de alta señal.

Hay varias fuerzas que empujan hacia la eficiencia. El coste de procesamiento crece de forma desproporcionada con la longitud del contexto: no es el doble por el doble de tokens, sino exponencialmente más en tiempo y cómputo. El rendimiento del modelo se degrada más allá de ciertas longitudes de contexto aunque técnicamente la ventana soporte más. Y las entradas largas siguen siendo caras incluso con prefix caching.

El principio guía es informatividad por encima de exhaustividad. Incluye lo que importa para la decisión concreta y excluye lo que no.

---

Patrones de degradación del contexto

Los modelos de lenguaje muestran patrones predecibles de degradación a medida que crece el contexto. Conocerlos es lo que te permite diagnosticar fallos y diseñar sistemas resilientes.

El fenómeno lost-in-middle

El patrón de degradación mejor documentado es "lost-in-middle", donde los modelos muestran curvas de atención en U [1]. La información al principio y al final del contexto recibe atención fiable; la información en medio sufre entre un 10% y un 40% menos de precisión de recuerdo.

El mecanismo es concreto. Los modelos asignan una atención masiva al primer token (a menudo el token BOS) para estabilizar estados internos, creando un "attention sink" que consume presupuesto de atención [2]. A medida que crece el contexto, los tokens del medio no consiguen suficiente peso de atención.

La solución práctica es poner la información crítica al principio o al final del contexto. Usa estructuras de resumen que saquen la información clave a posiciones favorecidas por la atención.

# Organize context with critical info at edges

[CURRENT TASK] # At start

- Goal: Generate quarterly report
- Deadline: End of week

[DETAILED CONTEXT] # Middle (less attention)

- 50 pages of data
- Multiple analysis sections
- Supporting evidence

[KEY FINDINGS] # At end

- Revenue up 15%
- Costs down 8%
- Growth in Region A

Para instrucciones que no te puedes permitir perder en ningún caso, duplícalas tanto al principio como al final. Como los modelos atienden con fuerza a ambos bordes, la misma instrucción en ambas posiciones recibe atención independientemente de la longitud del contexto. Este es el movimiento correcto para restricciones de sistema que siempre deben cumplirse, requisitos de formato de salida y políticas de seguridad.

# Example: Duplicating critical instructions

[SYSTEM - START]
CRITICAL: Always respond in JSON format. Never include PII.

[... long context with documents, history, tools ...]

[SYSTEM - REMINDER]
CRITICAL: Always respond in JSON format. Never include PII.

Envenenamiento del contexto

El envenenamiento del contexto es lo que ocurre cuando alucinaciones, errores o información incorrecta entran en el contexto y se van acumulando por referencias repetidas. Una vez envenenado, el contexto crea bucles de realimentación que refuerzan la creencia equivocada.

Suele llegar por una de estas tres vías: salidas de herramientas con errores o formatos inesperados, documentos recuperados con información incorrecta o desactualizada, y resúmenes generados por el modelo que introducen alucinaciones y luego persisten.

Lo detectas por los síntomas: peor calidad de salida en tareas que antes funcionaban, agentes llamando a herramientas incorrectas o con parámetros erróneos, y alucinaciones persistentes que sobreviven a los intentos de corrección.

La recuperación es mecánica. Trunca el contexto hasta antes del punto de envenenamiento, señala explícitamente el envenenamiento y pide una reevaluación, o reinicia con un contexto limpio conservando solo la información verificada.

Distracción del contexto

La distracción del contexto aparece cuando el contexto crece tanto que el modelo se centra en exceso en lo que le has proporcionado en perjuicio de lo que aprendió durante el entrenamiento. La investigación muestra que incluso un único documento irrelevante reduce el rendimiento en tareas que implican documentos relevantes [8]. El efecto sigue una función escalón: la presencia de cualquier distractor desencadena degradación.

La idea clave: los modelos no pueden saltarse el contexto irrelevante. Tienen que atender a todo lo que se les proporciona, y esa propia atención es la distracción, incluso cuando la información irrelevante es claramente inútil.

La mitigación pasa por filtrar por relevancia antes de cargar documentos, usar namespacing para que las secciones irrelevantes sean fáciles de ignorar y preguntarse si cierta información necesita estar en contexto o puede obtenerse mediante una llamada a herramienta.

Confusión del contexto

La confusión del contexto es lo que ocurre cuando información irrelevante influye en las respuestas de formas que degradan la calidad. Si metes algo en contexto, el modelo tiene que prestarle atención, y eso significa que puede incorporar información irrelevante, usar definiciones de herramientas pensadas para otra tarea o aplicar restricciones de otro contexto.

Señales que conviene vigilar: respuestas que abordan el aspecto equivocado de la consulta, llamadas a herramientas que parecen correctas para otra tarea, salidas que mezclan requisitos de múltiples fuentes.

La solución es segmentación explícita de tareas (tareas distintas obtienen ventanas de contexto distintas), transiciones claras entre contextos y gestión de estado que aísle el contexto.

Choque de contexto

El choque de contexto aparece cuando la información acumulada entra en conflicto directo, creando directrices contradictorias. Esto es distinto del envenenamiento, donde una pieza es errónea: en el choque, varias piezas correctas se contradicen entre sí.

Las fuentes habituales incluyen retrieval multifuente con información contradictoria, conflictos de versión (información desactualizada y actual a la vez en contexto) y conflictos de perspectiva (puntos de vista válidos pero incompatibles).

Resuélvelo con marcado explícito de conflictos, reglas de prioridad que establezcan qué fuente prevalece y filtrado por versión que excluya información desactualizada.

Umbrales de degradación específicos por modelo

La investigación ofrece datos concretos sobre cuándo empieza la degradación. La longitud efectiva de contexto —donde los modelos mantienen un rendimiento óptimo— suele ser significativamente menor que el máximo anunciado [3]:

Modelo	Contexto máximo	Contexto efectivo	Notas de degradación
GPT-4 Turbo	128K tokens	~32K tokens	El retrieval se degrada tras 32K, la precisión cae tras 64K
GPT-4o	128K tokens	~8K tokens	La precisión NIAH compleja cae del 99% al 70% en 32K
Claude 3.5 Sonnet	200K tokens	~4K tokens	La precisión NIAH compleja cae del 88% al 30% en 32K
Gemini 1.5 Pro	1M tokens	~128K tokens	99% de recall NIAH en 1M, mejor rendimiento en contexto largo
Gemini 2.0 Flash	1M tokens	~32K tokens	La precisión NIAH compleja cae del 94% al 48% en 32K

Fuentes: benchmark RULER [3], benchmark NoLiMa [9], informes técnicos de Google.

El hallazgo clave de RULER [3]: solo el 50% de los modelos que afirman soportar contexto 32K+ mantienen un rendimiento satisfactorio a 32K tokens. Las puntuaciones casi perfectas en pruebas simples de needle-in-a-haystack no se traducen a comprensión real de contexto largo: las tareas de razonamiento complejo muestran una degradación mucho más acusada.

---

Estrategias de compresión de contexto

Nota terminológica: la compresión de contexto es un paraguas que incluye summarization (para historial de conversación y memoria), observation masking (para salidas de herramientas) y selective trimming [5]. El resumido de memoria mencionado en la sección de Memoria es una aplicación de estas estrategias de compresión más amplias.

Cuando las sesiones de agentes generan millones de tokens de historial conversacional, la compresión deja de ser opcional. El enfoque ingenuo es comprimir agresivamente para minimizar los tokens por petición. El objetivo correcto de optimización es tokens por tarea [4]: el total de tokens consumidos para completar la tarea, incluidos los costes de volver a recuperar algo cuando la compresión pierde un detalle crítico.

Cuándo se necesita compresión

Activa la compresión cuando las sesiones del agente superen los límites de la ventana de contexto, cuando los agentes empiecen a "olvidar" qué archivos modificaron, cuando estés depurando una sesión larga de programación que ya se ha extendido durante horas o cuando el rendimiento se degrade de forma perceptible en conversaciones largas.

Tres enfoques listos para producción

Anchored iterative summarization mantiene un resumen persistente estructurado con secciones explícitas para intención de sesión, modificaciones de archivos, decisiones y siguientes pasos. Cuando se activa la compresión, resume solo el tramo recién truncado y lo fusiona con el resumen existente. La razón por la que funciona es que la estructura fuerza la preservación: las secciones dedicadas actúan como una checklist que el resumidor debe rellenar, lo que evita deriva silenciosa.

## Session Intent

Debug 401 Unauthorized error on /api/auth/login despite valid credentials.

## Root Cause

Stale Redis connection in session store. JWT generated correctly but session could not be persisted.

## Files Modified

- auth.controller.ts: No changes (read only)
- config/redis.ts: Fixed connection pooling configuration
- services/session.service.ts: Added retry logic for transient failures
- tests/auth.test.ts: Updated mock setup

## Test Status

14 passing, 2 failing (mock setup issues)

## Next Steps

1. Fix remaining test failures (mock session service)
2. Run full test suite
3. Deploy to staging

Opaque compression produce representaciones comprimidas optimizadas para fidelidad de reconstrucción. Consigue las ratios de compresión más altas (99%+) pero sacrifica interpretabilidad. Úsala cuando el ahorro máximo de tokens importe y volver a recuperar sea barato.

Regenerative full summary genera un resumen estructurado detallado en cada compresión. La salida es legible, pero los detalles pueden degradarse a lo largo de ciclos repetidos de compresión.

Comparativa de compresión

La investigación de Factory.ai [4] comparó estrategias de compresión en sesiones reales de agentes en producción:

Método	Ratio de compresión	Puntuación de calidad	Mejor para
Anchored Iterative	98.6%	3.70/5	Sesiones largas, seguimiento de archivos
Regenerative	98.7%	3.44/5	Límites de fase claros
Opaque	99.3%	3.35/5	Máximo ahorro, sesiones cortas

Cómo leer las métricas:

• Ratio de compresión (98.6%): porcentaje de tokens eliminados. Una ratio del 98,6% significa que de 100.000 tokens de historial solo quedan 1.400.
• Puntuación de calidad (3.70/5): medida mediante evaluación basada en sondas — tras la compresión, al agente se le hacen preguntas que requieren recordar detalles concretos del historial truncado (qué archivos modificamos, cuál era el mensaje de error). 3,70/5 significa que el agente respondió correctamente a aproximadamente el 74% de las sondas.
• 0.7% de tokens adicionales: al comparar anchored iterative (98,6%) con opaque (99,3%), la diferencia es del 0,7%. Para una sesión de 100K tokens, eso son 1.400 tokens frente a 700. Esos 700 tokens extra (0,7% del original) compran 0,35 puntos de calidad (3,70 frente a 3,35): un recuerdo significativamente mejor de detalles críticos para la tarea.

El problema de la traza de artefactos

La integridad de la traza de artefactos es la dimensión más débil en todos los métodos de compresión, con puntuaciones entre 2,2 y 2,5 sobre 5,0. Los agentes de programación necesitan saber qué archivos crearon, modificaron o leyeron, y la compresión a menudo pierde esa información.

Recomendación: implementa un índice de artefactos independiente o un seguimiento explícito del estado de archivos en el scaffolding del agente, además del resumido general.

Estrategias de activación de compresión

Estrategia	Punto de activación	Trade-off
Umbral fijo	70-80% de utilización	Simple pero puede comprimir demasiado pronto
Ventana deslizante	Mantener las últimas N interacciones + resumen	Tamaño de contexto predecible
Basada en importancia	Comprimir primero lo menos relevante	Compleja pero preserva señal
Límite de tarea	Comprimir al completar tareas	Resúmenes limpios, timing impredecible

Evaluación basada en sondas

Las métricas tradicionales como ROUGE no capturan la calidad funcional de la compresión. Un resumen puede puntuar alto en solapamiento léxico y aun así perder la única ruta de archivo que el agente realmente necesita.

La evaluación basada en sondas mide la calidad directamente haciendo preguntas después de comprimir:

Tipo de sonda	Qué prueba	Ejemplo de pregunta
Recall	Retención factual	"¿Cuál era el mensaje de error original?"
Artifact	Seguimiento de archivos	"¿Qué archivos hemos modificado?"
Continuation	Planificación de tarea	"¿Qué deberíamos hacer a continuación?"
Decision	Cadena de razonamiento	"¿Qué decidimos sobre el problema de Redis?"

Si la compresión preservó la información correcta, el agente responde correctamente. Si no, adivina o alucina.

---

Técnicas de optimización de contexto

La optimización de contexto amplía la capacidad efectiva mediante compresión, masking, caching y particionado. Estas técnicas se apoyan en las Estrategias de compresión de contexto anteriores y las aplican de forma sistemática para producción. Si se hace bien, la optimización puede duplicar o triplicar la capacidad efectiva de contexto sin requerir un modelo mayor.

Estrategias de compactación

La compactación resume el contenido del contexto cuando se acercan los límites y después reinicializa con el resumen. El objetivo es destilar el contenido con alta fidelidad, para que el agente pueda seguir operando con una degradación mínima.

El orden de prioridad que sigo: comprimir primero las salidas de herramientas (reemplazarlas por resúmenes), luego los turnos antiguos (resumir la parte inicial de la conversación) y después los documentos recuperados (resumir si existen versiones recientes). No comprimas nunca el system prompt.

Qué preservar depende del tipo. Salidas de herramientas: conserva hallazgos, métricas y conclusiones; descarta la salida bruta y verbosa. Turnos conversacionales: conserva decisiones, compromisos y cambios de contexto; descarta relleno. Documentos recuperados: conserva hechos y afirmaciones clave; descarta elaboración de apoyo.

Observation masking

Las salidas de herramientas pueden suponer más del 80% del uso de tokens [4]. Una vez que un agente ha usado la salida de una herramienta para tomar una decisión, mantener la salida completa aporta un valor decreciente.

Una matriz de decisión para masking:

Categoría	Acción	Justificación
Observaciones de la tarea actual	No enmascarar nunca	Críticas para el trabajo actual
Turno más reciente	No enmascarar nunca	Inmediatamente relevante
Razonamiento activo	No enmascarar nunca	Pensamiento en curso
Hace 3+ turnos	Considerar masking	Probablemente ya cumplió su propósito
Salidas repetidas	Enmascarar siempre	Redundantes
Boilerplate	Enmascarar siempre	Baja señal

Optimización de KV-cache

La KV-cache almacena tensores Key y Value calculados durante la inferencia. Hacer caching entre peticiones con prefijos idénticos evita recomputación, lo que reduce drásticamente coste y latencia.

Optimiza para caching colocando primero el contenido estable:

# Stable content first (cacheable)
context = [system_prompt, tool_definitions]
# Frequently reused elements
context += [reused_templates]
# Unique elements last
context += [unique_content]

Diseña para estabilidad de caché: evita contenido dinámico como timestamps en los prompts, usa formato consistente y mantén la estructura estable entre sesiones.

Particionado de contexto

La optimización más agresiva es particionar el trabajo entre subagentes con contextos aislados. Cada subagente opera en un contexto limpio centrado en su subtarea, sin arrastrar contexto acumulado de otras subtareas.

Para la agregación: valida que todas las particiones se hayan completado, fusiona resultados compatibles y resume si la salida combinada sigue siendo demasiado grande.

Marco de decisión de optimización

Cuándo optimizar: cuando la utilización del contexto supere el 70%, cuando la calidad de respuesta se degrade en conversaciones largas, cuando los costes empiecen a subir por contextos largos o cuando la latencia aumente con la longitud de la conversación.

Qué aplicar depende de qué domine. Si dominan las salidas de herramientas, observation masking. Si dominan los documentos recuperados, summarization o particionado. Si domina el historial de mensajes, compactación con summarization. Si dominan varios componentes, combinar estrategias.

Métricas objetivo razonables: compactación con reducción de tokens del 50-70% y menos del 5% de degradación de calidad; masking con reducción del 60-80% en observaciones enmascaradas; optimización de caché con tasa de aciertos del 70%+ para cargas de trabajo estables.

---

Cómo cocinarlo (paso a paso)

Una receta práctica para la capa de contexto. Empieza simple y añade complejidad solo cuando algo se rompa.

Paso 1: escribe el contrato

Define qué debe hacer tu agente y cómo debe comportarse. Escribe las políticas a nivel system (rol, restricciones, reglas de seguridad) y las directrices a nivel developer (formato de salida, tono, requisitos de citas). Define JSON Schemas para cada forma de salida: AnswerSchema, PlanSchema, StepResultSchema.

Paso 2: elige una estrategia de retrieval

Empieza con retrieval híbrido (BM25 más vector) y un reranker. Después enruta por tipo de consulta. El conocimiento general no necesita retrieval. Los hechos recientes o privados necesitan RAG de un solo disparo (híbrido más rerank). Las consultas complejas de varias partes necesitan RAG iterativo (dividir en subconsultas).

Paso 3: diseña la memoria

Separa corto plazo (estado conversacional) de largo plazo (hechos del usuario, historial). El corto plazo mantiene el estado de la conversación y los últimos turnos, y luego se limpia al final de la sesión. El largo plazo mantiene entidades del usuario, preferencias y eventos episódicos. Fija reglas de caducidad: preferencias 365 días, episodios 90 días, corto plazo solo durante la sesión. Añade redacción de PII antes de almacenar cualquier cosa.

Paso 4: especifica las herramientas

Define firmas de herramientas claras con validación y estrategias de fallback. Para cada herramienta, escribe un docstring claro, un esquema de entrada y un esquema de salida. Marca si es idempotente. Define postconditions y la cadena de fallback. Valida los argumentos de herramientas contra el esquema antes de llamar.

Paso 5: instala guardrails

Añade validación de entrada y salida, filtros de seguridad y aplicación de políticas. El checklist mínimo:

• [ ] Redactar PII (emails, SSN, tarjetas de crédito) antes de procesar.
• [ ] Validar todas las salidas contra JSON Schema.
• [ ] Bloquear intentos de prompt injection.
• [ ] Aplicar rate limiting a llamadas de herramientas.
• [ ] Registrar todas las violaciones de política para auditoría.

Paso 6: añade observabilidad y evals

Instrumenta la capa de contexto para poder depurarla. Traza qué fuentes de contexto se cargaron; recuentos de tokens (entrada, salida, coste); métricas de retrieval (consulta, top-k, fuentes citadas); llamadas a herramientas (qué herramientas, argumentos, resultados, fallos); y activaciones de guardrails (bloqueos de entrada, reparaciones de salida, rechazos por política).

Las métricas que más importan son exactitud (validez del esquema, objetivo 99%+), groundedness (tasa de citas, objetivo 90%+ para consultas de conocimiento), latencia (objetivo por debajo de 2s p95) y coste (objetivo por debajo de $0.05 por consulta).

Paso 7: itera

Añade patrones avanzados solo cuando llegues a límites claros. Añade reflexiones cuando la tasa de error supere el 5%. Añade planners cuando las tareas requieran de forma habitual más de tres pasos secuenciales. Añade subagentes cuando tengas dominios distintos que necesiten contextos aislados.

---

Anti-patterns

Errores comunes que matan los sistemas agentic. Evítalos.

1. Stuff-the-window

Meter en contexto todos los documentos, memorias y ejemplos posibles en cada consulta. El resultado es context rot: la relación señal-ruido se hunde y activas todos los patrones de degradación a la vez. Consulta Patrones de degradación del contexto para los detalles sobre distracción y confusión. La solución es enrutar de forma adaptativa y aplicar compresión y masking. Consulta Técnicas de optimización de contexto.

2. Resultados de herramientas sin validar

El agente llama a una herramienta, recibe datos y se los pasa inmediatamente al modelo sin comprobar nada. Los datos mal formados rompen la lógica downstream. Los resultados nulos provocan alucinaciones. Este es uno de los vectores principales de Envenenamiento del contexto. Valida siempre los resultados de herramientas contra el esquema y las postconditions.

3. Todo en una sola pasada

Política de sistema, directrices de developer, ejemplos, consulta del usuario, memoria y conocimiento, todo apretado en un único prompt monolítico. Sin separación de responsabilidades. La ventana de contexto se llena de boilerplate duplicado. Separa las instrucciones duraderas del contexto específico de cada paso y usa los patrones de Optimización de KV-cache de arriba.

4. Memoria sin límites

Guardar para siempre cada interacción del usuario y cargarlo todo en cada consulta. El contexto se llena de memorias antiguas e irrelevantes, y además asumes riesgo de privacidad gratis. Consulta el fenómeno lost-in-middle para ver por qué el contenido del medio se ignora igualmente. Define políticas de retención, implementa retrieval acotado y redacta PII.

5. RAG en todas partes

Recuperar documentos para cada consulta, incluso "¿Cuánto es 2+2?" o "Hola". Desperdicia latencia y coste, y el retrieval inyecta ruido que activa la Distracción del contexto. Implementa routing RAG adaptativo con un clasificador o un pequeño conjunto de heurísticas.

6. Ignorar las activaciones de guardrails

Registras las violaciones de guardrails, pero nunca las revisas. Los ataques reales se te cuelan. Los problemas reales de UX pasan desapercibidos. Las reparaciones de esquema no deberían ser frecuentes; si lo son, tus instrucciones no están claras. Revisa semanalmente las activaciones de guardrails.

7. Sin evals

Desplegar cambios en la capa de contexto sin probar. Regresiones silenciosas, ninguna forma de comparar variantes objetivamente. Define entre cinco y diez escenarios de eval antes de desplegar, ejecútalos con cada cambio y usa la Evaluación basada en sondas para detectar problemas de calidad en la compresión.

---

Quick wins: despliega esto hoy

Si ya tienes un agente en producción y quieres mejoras inmediatas, empieza aquí. Cada una lleva menos de un día.

1. Añade validación del esquema de salida

Captura la mayoría de errores antes de que lleguen a los usuarios.

from jsonschema import validate, ValidationError

def validate_output(output: dict) -> dict:
    try:
        validate(instance=output, schema=ANSWER_SCHEMA)
        return output
    except ValidationError as e:
        repaired = auto_repair(output, e)
        validate(instance=repaired, schema=ANSWER_SCHEMA)
        return repaired

2. Instrumenta trazas básicas

Depura mucho más rápido cuando algo se rompe.

logger.info(json.dumps({
    "request_id": request_id,
    "query": query,
    "context_loaded": {"instructions": True, "memory": True, "knowledge": True},
    "tokens": {"input": 1200, "output": 150},
    "latency_ms": 1120,
    "result": "success"
}))

3. Separa mensajes system y user

Reduce de forma significativa el desperdicio de tokens al habilitar la Optimización de KV-cache.

messages = [
    {"role": "system", "content": SYSTEM_POLICY + DEVELOPER_GUIDELINES},
    {"role": "user", "content": f"Query: {query}\nMemory: {memory}\nKnowledge: {knowledge}"}
]

4. Añade requisitos de citas

Genera confianza, permite auditoría y reduce alucinaciones.

5. Fija caducidad de memoria

Evita contaminación del contexto y riesgos de privacidad.

def load_memory(customer_id: str) -> dict:
    entries = db.get_memory(customer_id)
    now = datetime.now()
    return {
        k: v for k, v in entries.items()
        if v.get("expires_at", now) > now
    }

---

Conclusión

La ingeniería de contexto es la disciplina que separa los agentes de demo de los agentes de producción. El modelo no empeoró: el contexto sí. Las cuatro palancas que merece la pena conocer: fundamentos (el contexto es finito, la atención es limitada, la progressive disclosure es la clave), patrones de degradación (lost-in-middle, envenenamiento, distracción, confusión, choque), compresión (tokens-per-task por encima de tokens-per-request, resúmenes estructurados) y optimización (compactación, masking, caching, particionado).

Empieza por los quick wins. Añade complejidad solo cuando llegues a un límite real. Y mídelo todo: no puedes mejorar lo que no trazas.

---

Este artículo incorpora contenido de la colección Agent Skills for Context Engineering, un conjunto de módulos de conocimiento reutilizables para construir mejores agentes de IA.

---

Referencias

1. Liu, N. F., Lin, K., Hewitt, J., Paranjape, A., Bevilacqua, M., Petroni, F., & Liang, P. (2023). "Lost in the Middle: How Language Models Use Long Contexts." arXiv preprint arXiv:2307.03172. https://arxiv.org/abs/2307.03172

   • Hallazgo clave: entre un 10% y un 40% menos de precisión de recuerdo para la información en medio del contexto frente al principio/final.

2. Xiao, G., Tian, Y., Chen, B., Han, S., & Lewis, M. (2023). "Efficient Streaming Language Models with Attention Sinks." ICLR 2024. https://arxiv.org/abs/2309.17453

   • Introduce el fenómeno de "attention sink", donde los LLM asignan una atención desproporcionada a los tokens iniciales.

3. Hsieh, C. Y., et al. (2024). "RULER: What's the Real Context Size of Your Long-Context Language Models?" COLM 2024. https://arxiv.org/abs/2404.06654

   • Hallazgo clave: solo el 50% de los modelos que afirman soportar contexto 32K+ mantienen un rendimiento satisfactorio a 32K tokens.

4. Factory.ai Research. (2025). "Evaluating Context Compression for AI Agents." https://www.factory.ai/blog/evaluating-context-compression

   • Fuente de las comparativas de estrategias de compresión, la optimización tokens-per-task y la metodología de evaluación basada en sondas.

5. Li, Y., et al. (2023). "Compressing Context to Enhance Inference Efficiency of Large Language Models." EMNLP 2023.

   • Investigación sobre poda selectiva de contexto usando métricas de self-information.

6. Anthropic. (2024). "Model Context Protocol (MCP) Specification." https://modelcontextprotocol.io/

   • Especificación oficial del estándar MCP para la integración IA-herramientas.

7. LangChain/LangGraph. (2024). "How to add memory to the prebuilt ReAct agent." https://langchain-ai.github.io/langgraph/how-tos/create-react-agent-memory/ — Demuestra que el summarization es una técnica para gestionar memoria dentro de los límites de contexto.

8. Yoran, O., Wolfson, T., Bogin, B., Katz, U., Deutch, D., & Berant, J. (2024). "Making Retrieval-Augmented Language Models Robust to Irrelevant Context." ICLR 2024. https://arxiv.org/abs/2310.01558

   • Hallazgo clave: incluso un único documento irrelevante puede reducir significativamente el rendimiento de RAG, creando un "efecto de distracción".

9. Maekawa, S., et al. (2025). "NoLiMa: Long-Context Evaluation Beyond Literal Matching." ICML 2025. https://arxiv.org/abs/2502.05167

   • Hallazgo clave: contexto efectivo de GPT-4o ~8K tokens, Claude 3.5 Sonnet ~4K tokens cuando se requiere razonamiento latente (frente a literal matching). En 32K tokens, GPT-4o cae del 99,3% al 69,7% de precisión.

Recursos adicionales

• Anthropic Claude Documentation: buenas prácticas para uso de contexto largo
• OpenAI Cookbook: estrategias para gestionar ventanas de contexto
• LangChain Documentation: patrones de memoria y retrieval
• LlamaIndex Documentation: estrategias de RAG y chunking