Cuatro capas de ingeniería de contexto para agentes de IA en producción: Cómo Deep Insight las aplica en código funcional

Cuando los agentes de IA en producción manejan tareas como el análisis de datos y la generación de informes, la gestión del contexto puede convertirse en un cuello de botella importante. Una ventana de 200K tokens suena generosa hasta que una tarea real la consume casi por completo en cuestión de minutos. El análisis de datos y la generación de informes dejan al agente fallando a mitad de la ejecución, perdiendo precisión o disparando los costos. Ya existe un conjunto de guías publicadas que aborda esto, pero las técnicas individuales son más fáciles de leer que de aplicar. Aplicadas en conjunto, marcan una diferencia medible: en la implementación de referencia que recorre esta publicación, una única herramienta de escritura y ejecución reduce en aproximadamente un 95 por ciento los tokens que cada script añade al contexto, y la carga de habilidades bajo demanda reduce el prompt del sistema en aproximadamente un 97 por ciento.

Esta serie organiza esa guía en prácticas que puedes aplicar directamente. Las publicaciones de ingeniería de Anthropic, junto con las características integradas en el Strands Agents SDK, convergen en cuatro capas de ingeniería de contexto: aislar el contexto a nivel de arquitectura, controlarlo mediante prompts, externalizarlo al sistema de archivos y verificarlo con agentes independientes y salvaguardas. En esta publicación (Parte 2), aprenderás cómo funciona cada capa y cómo se ve en código funcional. Aplicamos estas técnicas en Deep Insight, una solución de análisis de datos multiagente de código abierto construida sobre el Strands Agents SDK y Amazon Bedrock AgentCore, que sirve como implementación de referencia a lo largo de todo el artículo.

Serie de publicaciones

• Parte 1: 5 desafíos de producción en sistemas multiagente y cómo los resolvió Deep Insight.
• Parte 2: Cuatro capas de ingeniería de contexto para agentes de IA en producción: Cómo Deep Insight las aplica en código funcional.
• Parte 3: Ingeniería de harness en la práctica: llevando Deep Insight del desarrollo a producción. (¡Próximamente!)

La primera publicación definió cinco desafíos fundamentales que los sistemas multiagente en producción deben resolver. Presentó cómo Strands Agents SDK, Amazon Bedrock y Bedrock AgentCore, y AWS Fargate abordan cada uno diferentes capas del problema, con ejemplos de código. Esta segunda publicación toma las cuatro capas de la práctica de ingeniería de contexto que se sitúan sobre esa arquitectura y muestra la implementación de cada una. La tercera publicación te guía a través del despliegue y la operación de agentes en una red privada segura en Amazon Virtual Private Cloud (Amazon VPC), cubriendo todo lo necesario para operaciones en el mundo real.

¿Qué es la ingeniería de contexto?

La ingeniería de contexto es la disciplina de optimizar la información en la limitada ventana de contexto de un modelo de lenguaje grande (LLM) para que los agentes rindan al máximo. Anthropic Claude Sonnet 4.5, disponible en Amazon Bedrock, ofrece una ventana de contexto de 200K, pero las tareas complejas de producción la superan rápidamente. Por ejemplo, una solicitud aparentemente sencilla como «Analizar datos de ventas y crear un informe DOCX» atraviesa varias etapas: carga y exploración de datos (5 min), análisis de ventas por categoría (3 min), generación de cinco gráficos para análisis de series temporales (10 min), validación estadística (3 min) y generación del informe final (5 min). En conjunto, consumen más de 150K tokens a lo largo de 15 minutos.

Procesar tales tareas en un solo contexto causa problemas: la ventana se desborda a mitad de la tarea, el contexto obsoleto degrada el rendimiento, y los errores requieren volver a ejecutar todo el pipeline. A medida que el contexto crece, la atención a la información importante disminuye, y la ineficiencia eleva el costo bajo un precio por token.

«A medida que aumenta el número de tokens en la ventana de contexto, disminuye la capacidad del modelo para recordar con precisión la información de ese contexto (Context rot).»

— Anthropic, «Effective Context Engineering for AI Agents” (2025.09)

La ingeniería de contexto resuelve exactamente estos problemas, y no es solo una colección de técnicas. Abarcando el diseño de arquitectura, la escritura de prompts, la implementación de herramientas y la verificación, es una disciplina en capas donde cada capa compensa lo que las anteriores pasan por alto. Esta publicación detalla el enfoque de cuatro capas que puedes aplicar para gestionar el contexto de manera eficiente.

Cómo manejar tareas que exceden la ventana de contexto

Anthropic ha publicado varias técnicas para manejar tareas de largo alcance. Deep Insight agrupa estas técnicas en cuatro capas, donde cada capa aborda las limitaciones de las demás. La siguiente tabla presenta las cuatro capas.

Las secciones siguientes abordan cada capa en orden, indicando lo que la capa prescribe, por qué las capas anteriores por sí solas son insuficientes y cómo se implementa la práctica en Deep Insight.

1. Aislar el contexto mediante una arquitectura multiagente

Dar a cada agente especializado su propia ventana de contexto y pasar solo resultados comprimidos al orquestador. Deep Insight lo hace con una jerarquía de Coordinator, Planner, Plan Reviewer, Supervisor y Tool Agents (Coder, Validator, Reporter, Tracker, Auditor).

Con un solo agente, toda la información, desde las solicitudes del usuario hasta la exploración de datos, el análisis, la generación de gráficos, la validación y los informes, se acumula en un solo contexto y fácilmente excede la ventana. Dar a cada agente su propio contexto mantiene incluso al Coder, que es el que más usa, por debajo de 25K tokens en total. Cada agente recibe solo lo que necesita y señala a los demás con un aviso de finalización y un breve resumen.

La clave del aislamiento es minimizar la información compartida. Deep Insight utiliza un diccionario de Python, shared_state, que almacena solo cuatro cosas:

• messages: El mensaje final del agente anterior (no el historial completo de la conversación).
• clues: Resúmenes comprimidos recopilados de cada agente.
• full_plan: Una lista de verificación generada por Planner y actualizada por Tracker.
• history: Un registro breve de nombres de agentes y mensajes.

Las pistas utilizan un CLUES_FORMAT fijo: en lugar de la conversación completa de cada agente (decenas de miles de tokens), solo se pasan los resultados centrales comprimidos.

# coder_agent_tool.py -- context passing format
CLUES_FORMAT = "Here is clues from {}:\n\n<clues>\n{}\n</clues>\n\n"
RESPONSE_FORMAT = "Response from {}:\n\n<response>\n{}\n</response>\n\n*Please execute the next step.*"

# After Coder completes: add only compressed result to clues
clues += CLUES_FORMAT.format("coder", response["text"])

Este patrón es el recomendado en la publicación de Anthropic “How We Built Our Multi-Agent Research System”, que describe un patrón orquestador-trabajador en el que un agente principal delega en subagentes especializados, con cada agente trabajando solo dentro de su propio contexto. No es necesario construirlo usted mismo: el patrón agents-as-tools del Strands Agents SDK proporciona este aislamiento a nivel de framework.

2. Controlar el flujo de entrada del contexto mediante prompts

El aislamiento de la Capa 1 por sí solo no es suficiente: incluso con contextos independientes, un agente que genera respuestas largas infla el contexto del Supervisor. La Capa 2 limita la salida de cada agente mediante prompts.

Para Deep Insight, usamos prompts para limitar cuánta información devuelve cada agente al Supervisor. Tres reglas hacen la mayor parte del trabajo, como muestran los prompts de Deep Insight.

“Comienza con el modelo más fuerte y un prompt simple. Luego agrega incrementalmente instrucciones específicas basadas en casos de fallo observados realmente.”

— Anthropic, “Effective Context Engineering for AI Agents” (2025.09)

Detalle de implementación 2-1: Presupuestos de tokens de salida explícitos por agente

El prompt de cada agente especifica un recuento máximo de tokens de respuesta, lo que evita respuestas largas que contaminen el contexto del Supervisor.

La publicación ” Writing Effective Tools for Agents” de Anthropic sugiere dar a las herramientas una opción de respuesta CONCISE o DETAILED para ahorrar contexto. Aplique la misma idea un nivel más arriba, en el system prompt de cada agente. En Deep Insight, todos los agentes comparten un formato estandarizado:

## Status
[SUCCESS | PARTIAL_SUCCESS | ERROR]
## Completed Tasks
- [Task 1 from FULL_PLAN -- use exact wording so Tracker can match]
- [Task 2 -- be specific, not generic]
## Key Insights
- [Key finding 1 with numbers and ratios]
- [Key finding 2 with business implications]
## Generated Files
- ./artifacts/chart.png -- brief description
- ./artifacts/calculation_metadata.json -- N calculations

Detalle de implementación 2-2: filosofía de código autocontenido

El prompt del agente Coder indica explícitamente que “las variables no persisten entre scripts”. Cada script debe incluir todas las importaciones necesarias y cargar los datos directamente. El prompt proporciona ejemplos incorrectos y correctos:

# WRONG -- Attempting to use a variable from Turn 1 in Turn 2
# Turn 1:
df = pd.read_csv('data.csv')
total = df['Amount'].sum()

# Turn 2:
print(f"Total: {total}")  # NameError: name 'total' is not defined

# CORRECT -- Every script is self-contained
import pandas as pd
df = pd.read_csv('./artifacts/cache/df_main.csv')  # Load from cache
total = df['Amount'].sum()
print(f"Total: {total}")

La razón por la que esta regla se relaciona con la ingeniería de contexto es que hacer referencia a variables de scripts anteriores requiere que el agente “recuerde” conversaciones previas, lo que significa que el código pasado debe permanecer en el contexto. El principio de autocontención significa que el código pasado puede eliminarse del contexto de forma segura.

Detalle de implementación 2-3: regla de finalización de sección del Supervisor

El prompt del Supervisor incluye la regla “No pasar al siguiente agente hasta que todos los elementos de la lista de verificación de la sección del agente actual estén marcados [x]”. Expresamos esta regla en el prompt porque decidir si el trabajo del Coder está completo requiere que el Supervisor interprete el plan usando la información de las actualizaciones del Tracker. Este juicio es difícil de expresar solo en código.

3. “Solo punteros en el contexto, datos reales en archivos”

La capa 1 aísla el contexto entre agentes, y la capa 2 limita la salida dentro de los agentes. Pero cuando el agente Coder genera 100 líneas de código Python, ese código mismo entra en el contexto. Incluso con instrucciones de prompt de “responde brevemente”, algo de código no puede escribirse brevemente. La capa 3 usa el diseño de herramientas para mover el contenido pesado fuera del contexto, hacia el sistema de archivos. Cuatro técnicas aportan la mayor parte del beneficio, como muestran los siguientes detalles de implementación.

Detalle de implementación 3-1: mover el código fuera del contexto con la herramienta Write y Execute

El Coder lee el plan de análisis, escribe Python y lo ejecuta para generar visualizaciones. Pero cuando el código se hace largo, el enfoque convencional (herramientas separadas de escritura y ejecución de archivos) añade 100 líneas directamente al contexto por script, acumulando más de 1,000 líneas.

La solución es fusionar los dos pasos en una sola herramienta, de modo que el código nunca entre al contexto como un mensaje. El agente Coder de Deep Insight usa una write_and_execute_tool para esto.

Aquí hay una parte del write_and_execute_tool. Después de escribir y ejecutar el archivo, devuelve solo un resumen: “Se escribieron 105 líneas, ejecución exitosa, análisis de cinco categorías completado”. El código queda en el archivo y alrededor de tres líneas de resumen permanecen en el contexto. Basándose en este ejemplo, eso ahorra aproximadamente el 95 por ciento de los tokens.

# write_and_execute_tool.py
def _handle_write_and_execute_tool(file_path, content, timeout=300):
    """Write a Python script and immediately execute it."""
    # Step 1: Write file
    with open(file_path, 'w', encoding='utf-8') as f:
        f.write(content)
    # Step 2: Execute immediately
    result = subprocess.run(
        f"python {file_path}",
        shell=True,
        capture_output=True,
        timeout=timeout
    )
    # Return only summary
    return f"Written {len(content.split(chr(10)))} lines to {file_path}\n" \
        f"Execution successful\n" \
        f"Output: {result.stdout[:500]}"  # Only first 500 chars

“Filtrado del lado del servidor: filtrar los datos en la capa de ejecución antes de que lleguen al contexto, reducción de tokens del 98.7% (de 150K a 2K).”

— Anthropic, “Code Execution with MCP” (2025.11)

Detalle de implementación 3-2: reutilizar lógica común como módulos en el agente Coder

Los módulos comunes se reutilizan entre análisis. En lugar de regenerarlos cada vez, defina una vez las funciones de uso frecuente como un módulo e impórtelas, lo que evita el desperdicio de tokens y la duplicación de contexto.

Sin esto, definir funciones como to_python_type() o track_calculation() en cada análisis produce 200–300 líneas de código duplicado a lo largo de 10 análisis. Deep Insight genera un módulo llamado coder_analysis_utils.py antes de la primera tarea. Incluye funciones para convertir tipos de numpy, rastrear metadatos de cálculo y guardar en JSON. Los análisis posteriores lo importan, reemplazando 20–30 líneas regeneradas por dos líneas de importación, lo que ahorra tokens y mejora la consistencia y la depuración.

# coder_analysis_utils.py -- common module generated before first task
import numpy as np
import json
from datetime import datetime

_calculations = []

def to_python_type(value):
    """Convert numpy/pandas types to Python native types"""
    if isinstance(value, (np.integer, np.int64)): return int(value)
    elif isinstance(value, (np.floating, np.float64)): return float(value)
    elif isinstance(value, np.ndarray): return value.tolist()
    return value

def track_calculation(calc_id, value, description, formula,
                      source_file, source_columns, importance):
    """Track calculation metadata -- Validator independently verifies later"""
    _calculations.append({
        "id": calc_id, "value": to_python_type(value),
        "description": description, "formula": formula,
        "source_file": source_file, "source_columns": source_columns,
        "importance": importance
    })

def save_calculation_metadata(path="./artifacts/calculation_metadata.json"):
    """Save all tracked calculations to JSON"""
    with open(path, 'w', encoding='utf-8') as f:
        json.dump({"generated_at": datetime.now().isoformat(),
                   "calculations": _calculations}, f, ensure_ascii=False, indent=2)

Detalle de implementación 3-3: guardar y compartir resultados de análisis mediante notas estructuradas

Usamos notas estructuradas para compartir resultados detallados de análisis sin pasarlos por el contexto de cada agente. Deep Insight almacena estos resultados en un archivo llamado all_results.txt, que luego los agentes leen según sea necesario.

Por ejemplo, el agente Coder añade resultados a all_results.txt después de cada tarea de análisis:

with open('./artifacts/all_results.txt', 'a', encoding='utf-8') as f:
    f.write(f"""
## Category Sales Analysis (completed at: 14:32)
- Top revenue category: Fruit (417,166,008 KRW, 45% of total)
- Top 3 categories: Fruit, Vegetables, Meat (78% of total)
- Generated file: ./artifacts/category_sales_chart.png
""")

El Coder registra resultados detallados en este archivo después de cada análisis, y el Reporter lo lee al escribir el informe final. Otros agentes colaboran a través de all_results.txt de la misma manera.

Sin toma de notas, el Coder pasa resultados detallados al Supervisor después de cada tarea, acumulándolos en su contexto. Con toma de notas, solo se pasa un mensaje de aproximadamente 30 tokens como "Análisis de ventas por categoría completado, se encontraron 3 conclusiones clave, resultados detallados guardados en all_results.txt", y el Reporter lee el archivo cuando es necesario.

El patrón se generaliza más allá de un solo archivo. El propio sistema de archivos puede servir como bus de comunicación entre agentes, como ocurre en Deep Insight:

«El enfoque "just in time", que carga dinámicamente los datos en el contexto en tiempo de ejecución en lugar de preprocesar todos los datos relevantes de antemano, mantiene el contexto fresco, relevante y adaptable al estado cambiante de la tarea».

— Anthropic, “Ingeniería de contexto eficaz para agentes de IA” (2025.09)

Detalle de implementación 3-4: Cargar solo el conocimiento necesario con Skills

En lugar de poner todo el conocimiento especializado en el prompt del sistema, este enfoque lo carga solo cuando es necesario. Incluir cada guía de habilidades (verificación de estructuras de datos, generación de README, creación de habilidades, escritura de prompts de sistema, creación de herramientas) añadiría más de 20K tokens, cargaría información innecesaria en el agente Coder en cada llamada y obligaría a realizar un redeploy para añadir una habilidad.

El sistema de Skills de Deep Insight carga al inicio solo un catálogo de habilidades de unos 500 tokens, y la lista de habilidades contiene únicamente nombres y breves descripciones. Cuando un usuario solicita “Crear un archivo README”, el agente decide “Necesito la habilidad readme-generator” y llama skill_tool(skill_name="readme-generator"). El SkillLoader lee readme-generator/SKILL.md y devuelve una guía detallada de unos 3K tokens.

# 1. Skill Discovery (at initialization)
from src.utils.skills.skill_utils import initialize_skills
available_skills, skill_prompt = initialize_skills(
    skill_dirs=["./skills"],
    verbose=True
)

# 2. Add to System Prompt (~500-token catalog)
system_prompt = base_prompt + skill_prompt

# 3. Runtime -- Agent loads skill when needed
# Agent decides: "This is README generation, I need the readme-generator skill"
# -> skill_tool(skill_name="readme-generator")
# -> Returns full SKILL.md content (~3K tokens)

Cada skill se define como un SKILL.md archivo compuesto por frontmatter YAML y una guía detallada en markdown. Incluye metadatos como name, description, license y allowed-tools, junto con Overview, When to Use This Skill, instrucciones detalladas y Best Practices. Para añadir una nueva skill, crea un nuevo directorio bajo skills/ y escribe un archivo SKILL.md, y será descubierto automáticamente.

Al arrancar, el agente carga un catálogo de skills de unos 500 tokens en lugar de desperdiciar más de 20,000 tokens en guías completas (aproximadamente un 97 por ciento menos). Cuando lo necesita, puede cargar unos pocos miles de tokens adicionales de instrucciones detalladas para las skills.

4. Verificación de calidad con agentes de verificación y salvaguardas

Incluso con las Capas 1–3, queda un riesgo: los agentes aislados no pueden ver el trabajo de los demás, así que si el Coder calcula mal, el Reporter arrastra ese error al informe. La Capa 4 es la última línea de defensa.

«Proporcione herramientas de prueba para que el agente pueda verificar por sí mismo las funcionalidades y corregir errores que no son evidentes solo con el código. Haga que el modelo registre su progreso en git con mensajes de commit descriptivos y escriba resúmenes de progreso en un archivo de progreso.»

— Anthropic, «Effective Harnesses for Long-Running Agents” (2025.11)

Detalle de implementación 4-1: agentes Tracker, Validator y Auditor: seguimiento del progreso y aseguramiento de la calidad

Tracker actualiza la lista de verificación del plan en tiempo real. Cuando el Coder completa la carga de datos, el Supervisor llama a Tracker, que actualiza el elemento del plan de [ ] a [x] basándose en información como «Carga de datos completa (1,000 filas, 5 columnas)». Esto ayuda tanto a los usuarios como al sistema a saber exactamente cómo va el progreso.

Validator vuelve a ejecutar de forma independiente los cálculos del Coder para verificar su precisión. Lee calculation_metadata.json, repite cada cálculo a partir de los datos de origen y compara: las coincidencias dentro de 0.01 pasan, las discrepancias se marcan. Los cálculos verificados van a citations.json para que el Reporter los cite. Después de que el Reporter termina, el Auditor compara el DOCX final contra citations.json y calculation_metadata.json sin modificarlos. Registra los defectos de citación en audit_findings.json y puede solicitar hasta dos reintentos específicos al Reporter.

Detalle de implementación 4-2: priorización de cálculos para verificación

Verificar todos los cálculos es ineficiente, así que delimite la verificación según su importancia. El OptimizedValidator de Deep Insight aplica los siguientes umbrales:

• Más de 50 cálculos: filtrado agresivo, verificar todos los high más solo 10 medium.
• Más de 20 cálculos: filtrado moderado, verificar todos los high más 15 medium.
• 20 cálculos o menos: verificar la mayoría, todos los high más todos los medium más 5 low.

También aplica comparación segura en cuanto a tipos: para evitar problemas de tipos entre numpy y Python, todos los valores se convierten a float() y se comprueba que la diferencia absoluta sea inferior a 0.01:

# validator.md -- type-safe numerical comparison
try:
    match = abs(float(expected) - float(actual)) < 0.01
except:
    match = str(expected) == str(actual)

Detalle de implementación 4-3: SummarizingConversationManager: la última red de seguridad

El contexto todavía puede desbordarse en casos excepcionales, así que mantenga una red de seguridad bajo las otras capas. Deep Insight usa el SummarizingConversationManager del Strands Agents SDK para esto.

# strands_sdk_utils.py -- safety net configuration at agent creation
agent = Agent(
    model=llm,
    system_prompt=system_prompts,
    tools=tools,
    conversation_manager=SummarizingConversationManager(
        summary_ratio=0.5,  # summarize oldest 50% on overflow
        preserve_recent_messages=10,  # always preserve 10 most recent messages
        summarization_system_prompt=apply_prompt_template("summarization", {})
    )
)

Ante un desbordamiento, el LLM resume el 50 por ciento más antiguo de los mensajes en uno solo, conservando siempre los 10 más recientes para mantener el contexto de la tarea actual. El prompt de resumen (summarization.md) exige que clues, plans, y tracking status se conserven textualmente.

Detalle de implementación 4-4: caché de prompts selectiva para la optimización de costos

La ingeniería de contexto abarca la optimización de costos, no solo el ahorro de tokens. Habilite la caché de prompts por agente, según la frecuencia con que cada uno se llama con el mismo prompt. Configuración por agente de Deep Insight:

Los agentes con la caché habilitada insertan puntos de caché en los prompts de sistema y en las definiciones de herramientas, reduciendo los costos de tokens de entrada hasta en un 90 por ciento en llamadas repetidas. Esta es una función compatible de forma nativa con el Strands Agents SDK. Plan Reviewer no aparece en la tabla porque es un paso con intervención humana que recoge la aprobación o los comentarios del usuario en lugar de llamar a un modelo.

Conclusión

Esta publicación ha detallado el enfoque de ingeniería de cuatro capas que puede utilizar para gestionar eficientemente el contexto en tareas complejas que exceden la ventana de contexto.

• Capa 1 (aislamiento a nivel de arquitectura): cada agento trabaja en un contexto independiente mediante una arquitectura multiagente, pasando solo resúmenes comprimidos.
• Capa 2 (control basado en prompts): los presupuestos de tokens de salida, los formatos de respuesta estandarizados y la filosofía de código autosuficiente limitan activamente la entrada de contexto.
• Capa 3 (uso del sistema de archivos): write_and_execute_tool mantiene el código fuera del contexto, el sistema de archivos sirve como bus de comunicación entre agentes, y el conocimiento se carga de forma diferida solo cuando se necesita.
• Capa 4 (verificación y salvaguardas): la reverificación independiente de cálculos por parte de Validator, la auditoría de citas de solo lectura del informe final por parte de Auditor, el seguimiento del progreso de Tracker, la prevención de desbordamiento de SummarizingConversationManager y el almacenamiento en caché selectivo de prompts gestionan tanto la calidad como el costo.

Cada capa forma un sistema de defensa que compensa lo que las capas anteriores pasan por alto. Cuando el aislamiento de la arquitectura es insuficiente, los prompts limitan la salida. Cuando los prompts son insuficientes, las herramientas mantienen el contenido externo. Y cuando los problemas aún surgen, la verificación los detecta.

Cada una de estas capas está documentada en las publicaciones de ingeniería de Anthropic, «Effective Context Engineering for AI Agents», «Code Execution with MCP», y «How We Built Our Multi-Agent Research System». Gran parte de lo que recomiendan ya viene incluido en el Strands Agents SDK, en lugar de ser algo que tú tienes que construir: SummarizingConversationManager, el almacenamiento en caché de prompts y el patrón de agentes como herramientas.

Al construir agentes para producción, la ventana de contexto del LLM por sí sola rara vez es suficiente. Aplica estas técnicas de ingeniería de contexto para gestionar el contexto de manera eficiente y escalar tus agentes para cargas de trabajo de producción.

Deep Insight, la implementación de referencia utilizada aquí, es de código abierto. Revisa el código y extiéndelo para tu dominio.

• GitHub
• Taller

Sobre los autores