Context Engineering

Resumen

Context engineering es la práctica de decidir qué información entra en la ventana de contexto de un LLM antes de cada request y cómo se organiza. No es solo escribir un buen prompt. Es diseñar el contenido completo que el modelo verá: el mensaje de sistema, los documentos recuperados, el historial de conversación, los resultados de herramientas, las instrucciones del paso actual y cualquier dato externo relevante.

Importa porque el contexto es el único puente entre el mundo exterior y el modelo. Si el contexto contiene información contradictoria, irrelevante, desactualizada o mal formateada, el mejor prompt del mundo producirá malos resultados. Si el contexto es muy grande, la latencia y el costo suben y la atención del modelo se diluye. Si es muy pequeño, falta evidencia. Context engineering es la disciplina que resuelve ese equilibrio.

Alcance y supuestos

Este paquete cubre context engineering a nivel de práctica y diseño: qué incluir en la ventana de contexto, cómo estructurar mensajes de sistema, cómo integrar documentos recuperados, cómo formatear resultados de herramientas, cómo truncar y resumir historial, cómo ensamblar contexto de múltiples fuentes y cómo evaluar si el contexto es suficiente para la tarea.

No cubre optimización de tokens a nivel interno, caching de contexto, compresión automática ni parámetros específicos de APIs. Asume que entiendes LLMs, prompt engineering, RAG retrieval y cómo las llamadas de inferencia reciben y procesan tokens.

Modelo mental

Piensa en preparar el expediente completo que un abogado necesita antes de una audiencia. El abogado no puede buscar documentos durante la sesión. Todo lo que necesita debe estar en el expediente: la petición del cliente, contratos relevantes, jurisprudencia, correspondencia anterior y notas del caso. Además, debe estar ordenado: primero el resumen ejecutivo, luego los hechos, después los documentos de evidencia, y al final los anexos largos.

Context engineering es preparar ese expediente para un LLM. El modelo no puede buscar más información durante la inferencia. Solo ve lo que está en su ventana de contexto. Si la evidencia está al final y el resumen al principio, el modelo puede perder conexión. Si pones tres versiones contradictorias del mismo hecho sin aclarar cuál es vigente, el modelo elegirá o combinará. Si dejas documentos de un cliente dentro del contexto de otro, el modelo puede mezclarlos.

La práctica incluye decisiones estructurales: qué va en el mensaje de sistema vs. en el mensaje de usuario, cómo separar instrucciones de contenido externo, cómo ordenar documentos por relevancia, cuándo truncar historial en vez de resumir, y cómo formatear tool results para que el modelo entienda qué pasó sin consumir tokens innecesarios.

Uso práctico

Invierte en context engineering cuando el LLM recibe información de múltiples fuentes y cada request tiene consecuencias:

• ✅ RAG sobre documentación extensa: recuperar, ordenar, truncar y delimitar chunks para que el modelo sepa qué es evidencia y qué es instrucción.
• ✅ Agentes IA con herramientas: formatear resultados de tools, registros de ejecución y errores para que el modelo tome la siguiente decisión.
• ✅ Conversaciones largas: resumir, truncar o condensar historial para mantener coherencia sin saturar la ventana.
• ✅ Multi-tenant: asegurar que documentos de un tenant nunca lleguen al contexto de otro.
• ❌ No reemplaza prompt engineering; las instrucciones siguen necesitando claridad y estructura.
• ❌ No es un problema de infraestructura; es una decisión de diseño que afecta calidad, costo y latencia.

Ejemplo trabajado: ensamblar contexto para un agente RAG con herramientas

Supón que un agente debe responder preguntas de clientes usando documentación y una herramienta de verificación de pedidos. Cada paso consume contexto. Sin context engineering, el modelo recibe una sopa de mensajes:

type AgentContext = {
  systemPrompt: string;
  conversationHistory: Array<{ role: "user" | "assistant"; content: string }>;
  retrievedChunks: Array<{
    content: string;
    source: string;
    relevanceScore: number;
  }>;
  toolResults: Array<{
    toolName: string;
    input: unknown;
    output: unknown;
    error?: string;
  }>;
};

function assembleContext(ctx: AgentContext): string {
  const sections: string[] = [];

  // 1. Instrucciones permanentes
  sections.push(`<system>\n${ctx.systemPrompt}\n</system>`);

  // 2. Historial resumido si es largo
  const historyBlock =
    ctx.conversationHistory.length > 10
      ? `[Conversación previa resumida: ${ctx.conversationHistory.length} mensajes]\n` +
        ctx.conversationHistory.slice(-6).map(
          (m) => `${m.role}: ${m.content.slice(0, 300)}`
        ).join("\n")
      : ctx.conversationHistory.map(
          (m) => `${m.role}: ${m.content}`
        ).join("\n");

  sections.push(`<conversation>\n${historyBlock}\n</conversation>`);

  // 3. Documentos recuperados, ordenados por relevancia y truncados
  const topChunks = ctx.retrievedChunks
    .sort((a, b) => b.relevanceScore - a.relevanceScore)
    .slice(0, 5)
    .map(
      (chunk, i) =>
        `<document index="${i + 1}" source="${chunk.source}">\n${chunk.content}\n</document>`
    )
    .join("\n");

  sections.push(`<retrieved_context>\n${topChunks}\n</retrieved_context>`);

  // 4. Resultados de herramientas formateados
  if (ctx.toolResults.length > 0) {
    const toolBlock = ctx.toolResults
      .map((tr) =>
        tr.error
          ? `<tool_result name="${tr.toolName}" status="error">\n${tr.error}\n</tool_result>`
          : `<tool_result name="${tr.toolName}" status="ok">\n${JSON.stringify(tr.output)}\n</tool_result>`
      )
      .join("\n");

    sections.push(`<tool_results>\n${toolBlock}\n</tool_results>`);
  }

  return sections.join("\n\n");
}

Lo que hace funcionar este ensamblaje es un conjunto de decisiones:

1. Separación clara con tags XML: <system>, <conversation>, <retrieved_context>, <tool_results>. El modelo distingue roles sin ambigüedad.
2. Truncado inteligente del historial: si hay más de 10 mensajes, resume y mantiene solo los últimos 6 con 300 caracteres cada uno.
3. Orden por relevancia: los chunks más relevantes primero, máximo 5, con índice y fuente.
4. Tool results explícitos: cada tool reporta éxito o error con status, el modelo no adivina si la llamada falló.
5. Delimitación de fuentes: cada documento tiene source e index para que el modelo pueda citar evidencia.

Antes de diseñar contexto, cinco preguntas:

1. ¿Qué necesita saber el modelo para resolver esta tarea específica?
2. ¿Qué información es permanente (sistema) y qué es dinámica (recuperación, herramientas, historial)?
3. ¿Cómo distingo instrucciones de contenido externo para evitar confusión o prompt injection?
4. ¿Qué trunco primero si el contexto crece: historial viejo, documentos menos relevantes o tool results anteriores?
5. ¿Cómo verifico que el contexto ensamblado es correcto? Revisar fuentes, tenant, formato y completitud.

Evidencia

• Anthropic Engineering, Effective context engineering for AI agents explora el arte emergente del context engineering y ofrece un modelo mental refinado para construir agentes dirigibles y efectivos.
• OpenAI API, Prompt engineering incluye estrategias para gestionar y estructurar la ventana de contexto, incluyendo mensajes de sistema, ejemplos y delimitación de contenido.
• Anthropic Claude Platform Docs, Prompt engineering overview cubre estructuración XML del contexto, role prompting y organización de instrucciones y contenido externo.