Ingeniería de contexto: gastar una atención finita donde más rinde · Lección 5 de 6

Lección 5: Subagentes y aislamiento de contexto

Objetivos de aprendizaje:

Explicar por qué un subagente cuenta como movimiento de gestión de contexto: una ventana limpia más un resumen de vuelta, dejando el «proceso» fuera de la ventana principal

Usar la proporción entre tokens de proceso y tokens de conclusión, junto con datos reales de costo, para juzgar si vale la pena entregarle una tarea a un subagente

Cablear el despacho de subagentes en el bucle del arnés que escribiste en el curso 7 de esta serie, de modo que cada despacho devuelva exactamente un resumen a la ventana principal

Requisitos: Terminaste la Lección 4 sobre compactación y notas, y sabes ejecutar el bucle del arnés que escribiste en el curso 7 de esta serie, «Fundamentos del arnés de agente: bucles y control» | Anterior: Lección 4 << | Siguiente: Lección 6 >>

Un cambio de perspectiva: no es división del trabajo, es solo aislamiento

Ya te encontraste con los subagentes en el curso 6 de esta serie, «Colaboración multiagente»: cómo repartir una tarea, cómo reportar resultados, cómo se coordinan varios agentes. Ese curso respondía a la pregunta de cómo trabajan juntos varios agentes. Esta lección responde a otra distinta: ¿qué hace que un subagente sea, en primer lugar, una técnica de gestión de contexto?

Dicho de otro modo: aunque tengas un solo agente principal y no necesites ninguna coordinación de equipo, igual vas a querer echar mano de un subagente — no por la división del trabajo, sino por el aislamiento.

Recuerda la óptica del presupuesto de la Lección 1. Cuando un modelo analiza contexto, echa mano de un presupuesto de atención, y cada nuevo token que entra al contexto agota un poco ese presupuesto¹. Amontona más tokens y la capacidad del modelo de recordar con precisión información de ese contexto decae¹. Un agente es justamente el escenario más propenso a amontonar tokens: cada turno del bucle produce datos nuevos que podrían ser relevantes para el siguiente turno de inferencia — difíciles de tirar, difíciles de guardar¹.

Las tareas de exploración son la versión más filosa de esto. Digamos que el agente principal tiene que rastrear todos los puntos de llamada de una API obsoleta en un repositorio de unos cientos de miles de líneas: una docena de greps, veinte archivos abiertos, unos miles de líneas leídas. Ese contenido intermedio llega a decenas de miles de tokens, mientras que la conclusión que vale la pena conservar podría ser de cinco líneas: «los puntos de llamada se agrupan en estos tres módulos, y este es el orden de migración sugerido». Si todo eso ocurre en la ventana principal, el presupuesto de atención se lo come el proceso y queda poco para la conclusión y para el trabajo que sigue.

El subagente es el cuchillo apuntado exactamente a ese problema.

La mecánica: ventana limpia adentro, resumen comprimido afuera

La mecánica cabe en una frase: un subagente especializado maneja una tarea acotada en una ventana de contexto limpia¹; el gran volumen de contenido intermedio que genera la exploración — resultados de búsqueda, contenidos crudos de archivos, callejones sin salida — se queda todo dentro del subagente¹; y lo que vuelve al agente principal es solo un resumen condensado y destilado de su trabajo, a menudo de 1000 a 2000 tokens¹.

La ventana del agente principal, por lo tanto, carga solo la conclusión, nunca el proceso. Es un diseño asimétrico: el subagente puede quemar decenas de miles de tokens explorando, pero de él solo sale un pasaje corto de texto.

En código, esto es apenas una apertura nueva para el arnés que escribiste en el curso 7. Para mantenerlo compacto, dos acciones que se repetían a lo largo del bucle de aquel curso vienen envueltas aquí como funciones auxiliares: textOf extrae el bloque de texto de una respuesta, y appendToolResults ejecuta las herramientas de este turno y anexa los bloques tool_result al arreglo de mensajes (por dentro hace exactamente lo que escribiste a mano en ese curso: ejecutar cada tool_use, juntar los resultados, devolverlos).

JAVASCRIPT

const SUBAGENT_SYSTEM = `Eres un subagente de investigación.
Cuando la tarea esté lista, entrega una conclusión de como máximo 1500 tokens:
hallazgos clave, las rutas de archivo involucradas y acciones recomendadas para el agente principal.
No repitas el texto crudo que leíste.`;

async function runSubagent(client, task, maxTurns = 15) {
  // Todo el truco es esta línea: un arreglo de mensajes totalmente nuevo, nada del historial del agente principal
  let messages = [{ role: "user", content: task }];
  for (let turn = 0; turn < maxTurns; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-5",
      max_tokens: 4096,
      system: SUBAGENT_SYSTEM, // el prompt del sistema propio del subagente
      tools: SEARCH_TOOLS,     // solo las herramientas que la exploración necesita
      messages,
    });
    if (response.stop_reason === "end_turn") {
      return textOf(response); // solo este texto sale del subagente
    }
    // ejecuta las herramientas, anexa los resultados a messages, todo eso se queda dentro del subagente
    messages = await appendToolResults(messages, response);
  }
  return "La investigación no terminó dentro del presupuesto de turnos";
}

Fíjate en tres detalles. Primero, messages arranca desde una única descripción de tarea solitaria, sin cargar ni una palabra del historial del agente principal: ese es el significado entero de «ventana limpia». Segundo, la función devuelve textOf(response), una cadena simple; las decenas de idas y vueltas de herramientas que se apilaron dentro del bucle se desvanecen junto con la variable local messages. Tercero, el prompt del sistema del subagente exige explícitamente «no repitas el texto crudo»: la calidad de compresión del resumen se fija justo ahí.

Del lado del agente principal, la acción de despacho es apenas una herramienta común que se enchufa al bucle de stop_reason que ya tienes:

JAVASCRIPT

const DISPATCH_TOOL = {
  name: "dispatch_research",
  description:
    "Entrega una tarea de investigación acotada a un subagente y devuelve su resumen de los hallazgos. " +
    "Úsala para tareas que necesitan exploración pesada pero cuya conclusión se puede enunciar brevemente.",
  input_schema: {
    type: "object",
    properties: {
      task: {
        type: "string",
        description: "Una descripción de tarea autocontenida; el subagente no puede ver el historial de esta conversación",
      },
    },
    required: ["task"],
  },
};

async function handleDispatch(mainMessages, toolCall) {
  const summary = await runSubagent(client, toolCall.input.task);
  mainMessages.push({
    role: "user",
    content: [{
      type: "tool_result",
      tool_use_id: toolCall.id,
      content: summary, // la ventana principal gana solo esta entrada
    }],
  });
}

Mira la description del campo task: «Una descripción de tarea autocontenida; el subagente no puede ver el historial de esta conversación». Esa línea está escrita para el agente principal — tiene que enunciar la tarea completa, porque del otro lado hay una ventana nueva y amnésica. Explicitar el propósito y los límites con esta precisión en la descripción de una herramienta es exactamente la idea de que «las herramientas son contexto» de la Lección 2: las herramientas deberían ser autocontenidas, robustas ante el error y sumamente claras respecto de su uso previsto¹.

Cuánto historial del agente principal debería recibir un subagente al arrancar

Estás escribiendo la lógica de despacho de un subagente de investigación y un colega sugiere: «Pásale al subagente el historial de mensajes completo del agente principal hasta ahora; así entenderá el panorama general y hará mejor el trabajo». Desde el punto de vista de la economía del contexto, ¿cómo evaluarías esto?

Datos de primera mano: los subagentes como filtros inteligentes

La mecánica está zanjada; ahora las mediciones. Anthropic publicó un informe sobre su sistema de investigación multiagente — la arquitectura detrás de la función Research de Claude — que es una pieza poco común de material de ingeniería de primera mano².

Tres de sus hallazgos tocan directamente esta lección:

Los subagentes facilitan la compresión al operar en paralelo con sus propias ventanas de contexto². Cada subagente explora en una ventana propia, sin apretujar a los demás.
Llaman a los subagentes «filtros inteligentes»: condensan los tokens más importantes para el agente de investigación líder². La palabra «filtro» es acertada: entra el corpus, sale lo esencial.
Una línea que vale la pena masticar: "The essence of search is compression: distilling insights from a vast corpus."² (la esencia de la búsqueda es la compresión: destilar hallazgos de un corpus enorme). Leída en el contexto de esta lección: cada exploración que ejecuta un subagente existe para producir ese destilado de mil tokens.

Como apunte al margen, el paralelismo también compra velocidad — varias líneas de investigación avanzando a la vez. Pero eso es tema de orquestación, ya cubierto en el curso 6 de esta serie; esta lección mantiene la mirada solo en el lado de la compresión.

La otra cara del libro contable: el aislamiento no ahorra costos

Con la ventaja expuesta, hay que exponer también la factura. El mismo informe da los números medidos — ojo, son mediciones del sistema de investigación de Anthropic, no leyes universales:

Los agentes suelen usar unas 4× más tokens que las interacciones de chat²;
Los sistemas multiagente usan unas 15× más tokens que los chats²;
Cuando analizaron de dónde venía el rendimiento, el uso de tokens por sí solo explicaba el 80 % de la varianza, y la cantidad de llamadas a herramientas y la elección del modelo daban cuenta de la mayor parte del resto².

Su propia conclusión es franca: "Multi-agent systems work mainly because they help spend enough tokens to solve the problem."² (los sistemas multiagente funcionan sobre todo porque ayudan a gastar suficientes tokens para resolver el problema).

Así que digámoslo sin rodeos: un subagente no ahorra costos. Los tokens totales solo suben — hay que reenunciar la tarea, volver a tender el trasfondo, varias ventanas quemando a la vez. Lo que compra es otra cosa: cada ventana se mantiene en un rango que no se ha degradado, así que la densidad de atención se sostiene alta de punta a punta. Es una disyuntiva de atención: gastar más tokens en total a cambio de una ventana limpia para cada agente.

¿Cuándo vale la pena aceptar esa disyuntiva? De vuelta a la óptica del presupuesto de la Lección 1: el contexto es un recurso finito con rendimientos marginales decrecientes¹. Dos preguntas para juzgarlo:

Proporción entre proceso y conclusión. ¿Qué tan grande es el contenido intermedio de esta tarea y qué tan pequeña su conclusión final? Cuanto más despareja la proporción, mayor el rédito del aislamiento. A la inversa, una tarea cuyo proceso ya es corto de entrada es puro sobrecosto de traspaso si la despachas.
Si la complejidad mejora el resultado de forma demostrable. La guía de Anthropic es considerar agregar complejidad solo cuando mejora los resultados de forma demostrable — la palabra del original es «considerar», una cuestión de proporción, no una regla de hierro³. Si los tokens extra no compran una mejor salida, vuelve a una sola ventana.

El combo de tarea larga: notas como base, traspasos para la resistencia

Por muy limpia que sea la ventana de un subagente, sigue siendo finita. Para tareas de horizonte genuinamente largo, el informe describe un combo: los agentes resumen las fases de trabajo completadas y guardan la información esencial en memoria externa²; después generan subagentes frescos con contextos limpios para continuar, manteniendo la continuidad mediante traspasos cuidadosos².

Eso enhebra la Lección 4 y esta en una sola secuencia de movimientos:

Las notas estructuradas de la Lección 4 se ocupan de «poner el estado clave fuera de la ventana» — un NOTES.md, una lista de tareas — viven en el sistema de archivos y no ocupan la atención de ninguna ventana;
El aislamiento de esta lección se ocupa de «mantener cada tramo de trabajo dentro de una ventana limpia» — lo primero que hace un subagente fresco es leer las notas; no necesita heredar el historial completo de su antecesor, solo lo esencial destilado de su antecesor.

¿Qué va en un documento de traspaso? Reutiliza el mismo criterio de disyuntiva de la compactación de la Lección 4: conservar decisiones arquitectónicas, bugs sin resolver y detalles de implementación, y descartar resultados de herramientas redundantes¹. Escribir un traspaso y escribir un resumen de compactación son el mismo oficio; solo cambia quien lee, de «tu yo futuro» al «siguiente subagente».

Cómo se ve esto en Claude Code

Por último, contrasta esto con una implementación que usas a diario. Las buenas prácticas oficiales de Claude Code lo dicen llanamente: la ventana de contexto se llena rápido y el rendimiento se degrada a medida que se llena; "The context window is the most important resource to manage."⁴ (la ventana de contexto es el recurso más importante que hay que gestionar). Dado que el contexto es la restricción fundamental, los subagentes son una de las herramientas más potentes disponibles⁴.

Su implementación coincide con la mecánica que describe esta lección: los subagentes se ejecutan en ventanas de contexto separadas y reportan resúmenes de vuelta⁴. Pídele a Claude Code que «encuentre la causa raíz de este bug» y el subagente al que despache hará greps, leerá archivos y seguirá la cadena de llamadas — toda esa exploración ocurriendo en la ventana propia del subagente, con la conversación principal recibiendo al final solo un resumen de la investigación. Acota bien el alcance de las investigaciones o entrégalas a subagentes, y la exploración no consumirá tu contexto principal⁴.

Cuando ves una subtarea ejecutándose en segundo plano en la interfaz y la conversación principal gana solo un informe corto al terminar, eso es la «ventana limpia adentro, resumen comprimido afuera» que esta lección viene describiendo desde el principio.

A esta altura ya viste las tres piezas del juego de herramientas para tareas largas: la compactación (Lección 4), las notas estructuradas (Lección 4) y las arquitecturas multiagente (esta lección). Su objetivo compartido es que un agente pueda mantener coherencia, contexto y comportamiento dirigido a objetivos a lo largo de secuencias de acciones¹. En la Lección 6 cableamos las tres en tu propio arnés.

Resumen

Un subagente es una técnica de gestión de contexto: la tarea acotada se ejecuta en una ventana de contexto limpia, el contenido intermedio de la exploración queda aislado dentro del subagente, y lo que vuelve suele ser solo un resumen destilado de 1000 a 2000 tokens — la ventana principal carga la conclusión, no el proceso¹.
En el sistema de investigación multiagente de Anthropic, los subagentes se ejecutan en ventanas de contexto separadas en paralelo y logran compresión por esa vía, actuando como «filtros inteligentes» que condensan los tokens más importantes para el agente líder; "The essence of search is compression"².
Números medidos del mismo sistema: los agentes usan unas 4× más tokens que los chats, los sistemas multiagente unas 15×, y el uso de tokens por sí solo explica el 80 % de la varianza de rendimiento — el aislamiento es una disyuntiva de atención, «gastar más tokens en total a cambio de una ventana que no se degrada», no un ahorro de costos².
Que el aislamiento valga la pena depende de la proporción entre proceso y conclusión, y de si la complejidad agregada mejora el resultado de forma demostrable — la palabra de Anthropic es «considerar», una cuestión de proporción más que una regla de hierro³.
El combo de tarea larga: resumir cuando una fase se completa, guardar lo esencial en memoria externa, y luego generar un subagente fresco con contexto limpio manteniendo la continuidad mediante traspasos cuidadosos — las notas de la Lección 4 y el aislamiento de esta lección hacen juego².
En Claude Code la ventana de contexto es el recurso más importante que hay que gestionar, lo que convierte a los subagentes en una de las herramientas más potentes disponibles: se ejecutan en ventanas de contexto separadas y reportan de vuelta solo resúmenes⁴.

>> Lección 6: Práctica: cablear la gestión de contexto sobre el arnés

Effective context engineering for AI agents — Anthropic Engineering — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹
How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³
Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents ↩ ↩²
Best practices for Claude Code — Claude Code Docs — https://code.claude.com/docs/en/best-practices ↩ ↩² ↩³ ↩⁴ ↩⁵

Ejercicios

Tu agente principal toma tres tareas:

Nivel 1: Decidir el aislamiento para tres tareas

Tarea A: En un repositorio de unos cientos de miles de líneas, encontrar todos los puntos de llamada que todavía usan la API obsoleta LegacyLedgerReader y sugerir un orden de migración.
Tarea B: El agente principal acaba de leer una función de 80 líneas al contexto; el usuario señala un bug off-by-one (error por uno) y pide arreglarlo.
Tarea C: Para una decisión de elección de librería, investigar tres librerías de parseo candidatas — leer la documentación de cada una, escarbar en su rastreador de issues y hacer una comparación lado a lado.

Para cada tarea, anota tu decisión — aislar (despachar un subagente) o no (hacerlo en la ventana principal) — señalando el paralelismo donde aplique, y da una o dos frases de razonamiento usando los criterios de esta lección.

Criterios de finalización · marcado local

Los tres juicios giran sobre la proporción entre tokens de proceso y tokens de conclusión: cuanto más pesado el proceso y más pequeña la conclusión, más vale la pena aislarLa Tarea B se juzga como no-aislar, con un razonamiento que incluye el lado del costo: la función ya está en la ventana principal, así que un subagente fresco tendría que retransferir la función y el trasfondo de la tarea, con lo que el sobrecosto del aislamiento supera al beneficioLa Tarea C señala que las tres líneas de investigación no dependen entre sí, así que pueden ocupar ventanas separadas en paralelo, devolviendo cada una solo los puntos que la comparación necesita

Cableaste un subagente en el arnés del curso 7 de esta serie, con esta lógica de despacho:

Nivel 2: Arreglar una función de despacho de «aislamiento falso»

JAVASCRIPT

async function runSubagent(client, task, maxTurns = 15) {
  let messages = [{ role: "user", content: task }];
  for (let turn = 0; turn < maxTurns; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-5",
      max_tokens: 4096,
      system: SUBAGENT_SYSTEM,
      tools: SEARCH_TOOLS,
      messages,
    });
    if (response.stop_reason === "end_turn") {
      // agrega también la respuesta final, devuelve el historial completo
      return [
        ...messages,
        { role: "assistant", content: textOf(response) },
      ];
    }
    messages = await appendToolResults(messages, response);
  }
  return messages;
}

async function handleDispatch(mainMessages, toolCall) {
  const subHistory = await runSubagent(client, toolCall.input.task);
  mainMessages.push({
    role: "user",
    content: [{
      type: "tool_result",
      tool_use_id: toolCall.id,
      // renderiza el historial entero a texto y lo mete de vuelta en la ventana principal
      content: renderAsText(subHistory),
    }],
  });
}

Síntoma: después de tres despachos de investigación, el uso de contexto del agente principal se acerca al límite de la ventana, y la lógica de compactación que instalaste en la Lección 4 se ve forzada a dispararse antes de tiempo. Inspecciona el arreglo de mensajes del agente principal y encontrarás que la gran mayoría de los tokens son los retornos originales de herramientas del subagente.

Señala la causa raíz y edita el código para que cada despacho agregue un solo mensaje de resumen a la ventana principal.

Criterios de finalización · marcado local

Identifica la causa raíz en el valor de retorno de `runSubagent` y en la escritura de vuelta de `handleDispatch`: el historial de mensajes completo del subagente (con todos sus retornos de herramientas) se renderiza en bloque a texto y se mete en la ventana principal, con lo que el aislamiento queda en un cascarón huecoDespués del arreglo, `runSubagent` devuelve solo el texto del resumen final, el `content` del `tool_result` es ese resumen, y cada despacho agrega un mensaje a la ventana principalExplica el vínculo con la Lección 4: la ventana principal deja de inundarse con el contenido de proceso del subagente, así que la lógica de compactación se dispara con menos frecuencia

Lección 5: Subagentes y aislamiento de contexto

Un cambio de perspectiva: no es división del trabajo, es solo aislamiento

La mecánica: ventana limpia adentro, resumen comprimido afuera

Datos de primera mano: los subagentes como filtros inteligentes

La otra cara del libro contable: el aislamiento no ahorra costos

El combo de tarea larga: notas como base, traspasos para la resistencia

Cómo se ve esto en Claude Code

Resumen

Footnotes

Ejercicios

Tu agente principal toma tres tareas:

Cableaste un subagente en el arnés del curso 7 de esta serie, con esta lógica de despacho: