Ventana de contexto

La ventana de contexto es el número máximo de tokens que el modelo puede manejar en una petición, sumando todo lo que envías (sistema, herramientas, historial, documentos) y lo que genera. Es un límite duro: si te pasas, la petición falla. Y es también un presupuesto: aunque quepa, cada token cuesta dinero y latencia, y el exceso de material irrelevante empeora la respuesta.

El tamaño exacto depende del modelo y cambia con cada generación. Consulta el vigente en la documentación oficial. La lección La ventana de contexto y qué cabe en ella explica el concepto desde cero.

Qué ocupa la ventana

flowchart LR
  A[system + tools] --> T[Total de la petición]
  B[historial] --> T
  C[documentos] --> T
  T --> L{"total + max_tokens ≤ ventana"}
  L -- sí --> OK[Se procesa]
  L -- no --> E[Error]

Medir antes de enviar

No adivines: cuenta. El endpoint de recuento devuelve los tokens de entrada que tendría una petición sin ejecutarla.

import anthropic

MODEL = "claude-sonnet-5-5"
client = anthropic.Anthropic()

mensajes = [{"role": "user", "content": open("contrato.txt", encoding="utf-8").read() + "\n\nResume las cláusulas de rescisión."}]

recuento = client.messages.count_tokens(model=MODEL, system="Eres un asistente jurídico.", messages=mensajes)
print("tokens de entrada:", recuento.input_tokens)

import { readFileSync } from "node:fs";
import Anthropic from "@anthropic-ai/sdk";

const MODEL = "claude-sonnet-5-5";
const client = new Anthropic();

const contrato = readFileSync("contrato.txt", "utf-8");
const recuento = await client.messages.countTokens({
  model: MODEL,
  system: "Eres un asistente jurídico.",
  messages: [{ role: "user", content: `${contrato}\n\nResume las cláusulas de rescisión.` }],
});
console.log("tokens de entrada:", recuento.input_tokens);

En producción, registra además usage.input_tokens y usage.output_tokens de cada respuesta. Te dirán cómo crece el contexto a lo largo de una conversación o de un agente.

Estrategias para el historial

En un chat o un agente el historial crece en cada turno. Antes de llegar al límite tienes que decidir qué sale.

Al recortar, respeta la estructura: no separes un tool_use de su tool_result. Si eliminas uno, elimina el otro, o la petición fallará.

def recortar(historial: list[dict], max_turnos: int) -> list[dict]:
    """Conserva los últimos turnos sin dejar un tool_result huérfano al principio."""
    recorte = historial[-max_turnos:]
    while recorte and not (recorte[0]["role"] == "user" and isinstance(recorte[0]["content"], str)):
        recorte = recorte[1:]  # empieza siempre por un mensaje de usuario con texto
    return recorte

Contexto largo frente a recuperación

Que quepa un documento entero no significa que debas meterlo. Con contextos largos la calidad puede caer para la información situada en mitad del texto (Liu et al., 2023, Lost in the Middle), y pagas todos esos tokens en cada pregunta.

Pautas de colocación en Trabajar con documentos largos. Más discusión en Ventanas de contexto enormes: no sustituyen a la recuperación.

Errores frecuentes

• No contar max_tokens. La entrada cabe, pero entrada más salida no.
• Herramientas con descripciones o esquemas enormes. Pagas por ellas en cada llamada, las use el modelo o no.
• Historial que nunca se recorta. El agente funciona en pruebas cortas y falla en la sesión de dos horas.
• Recortar rompiendo pares tool_use / tool_result. Error 400.
• Meterlo todo porque cabe. Más contexto irrelevante, peores respuestas. Ver Qué meter en el contexto y qué no.

Ver también

• Ventana de contexto, Contexto largo y Compactación.
• Compactación y memoria: técnicas de compactación.
• Prompt caching: abaratar el prefijo que se repite.
• El contexto es un presupuesto, no un cajón.