Cómo los subagentes obtienen su propio contexto y herramientas
Un subagente no es una versión más pequeña de la sesión principal de Claude Code.
Es una instancia separada, con una ventana de contexto que comienza casi vacía y una lista de herramientas que puede ser más reducida que la del agente principal.
Comprender por qué existe ese aislamiento, en lugar de tratarlo como un detalle de implementación, es lo que permite usar bien los subagentes en lugar de simplemente invocarlos por reflejo.
Resumen
- Idea Central: un subagente se ejecuta en su propia ventana de contexto y con sus propios permisos de herramientas con ámbito definido, separado de la sesión que lo generó.
- Por qué es Importante: sin aislamiento, cada paso exploratorio que da un subagente consumiría el presupuesto de contexto de la sesión principal, y cada subagente tendría acceso completo a todo lo que el agente principal podría tocar.
- Conceptos Clave: ventana de contexto, contexto aislado, ámbito de herramientas, prompt de tarea, informe de resumen, sesión principal.
- Cuándo Usar: investigación que de otro modo inundaría la sesión principal con detalles intermedios, trabajo que no debería poder acceder a ciertas herramientas, o tareas independientes que pueden ejecutarse en paralelo.
- Limitaciones / Compensaciones: el aislamiento significa que un subagente no puede ver la conversación previa del agente principal a menos que se incluya explícitamente, y la invocación de uno añade latencia real para tareas pequeñas.
- Temas Relacionados: investigación paralela de subagentes, el SDK de Agentes de Claude, comandos slash personalizados, hooks.
Fundamentos
Cada sesión de Claude Code tiene una ventana de contexto, el registro en ejecución de todo lo dicho y hecho en esa conversación hasta el momento.
Un subagente obtiene su propia ventana de contexto, no una parte compartida de la del agente principal.
Cuando el agente principal invoca un subagente, escribe un prompt de tarea que describe exactamente lo que el subagente debe hacer, y ese prompt de tarea es efectivamente el punto de partida completo del contexto del subagente.
El subagente no hereda los turnos anteriores del agente principal, sus lecturas de archivos anteriores, ni su hilo de pensamiento en curso, a menos que el agente principal reitere explícitamente esa información en el prompt de tarea.
Una analogía simple: entregar trabajo a un subagente es como entregar una carpeta sellada de instrucciones a un contratista, no como incluir a un compañero de trabajo que ya estaba sentado en la sala durante toda la reunión.
El contratista realiza el trabajo descrito en la carpeta y luego entrega un informe escrito. No regresa a la sala y comienza a narrar todo lo que vio en el camino.
Mecánica e Interacciones
El aislamiento resuelve dos problemas separados, y ayuda nombrarlos por separado.
El primero es el presupuesto de contexto. Una ventana de contexto es finita. Si una tarea de investigación requiere cuarenta llamadas a herramientas para explorar una base de código, ejecutar esa investigación directamente en la sesión principal significa que cuarenta llamadas a herramientas (con sus contenidos de archivos, resultados de búsqueda y callejones sin salida) residen en el historial de la conversación principal, independientemente de si algo de eso resulta importante. Delegar esa investigación a un subagente significa que solo el resumen final del subagente, no sus cuarenta pasos intermedios, llega al contexto del agente principal.
El segundo es el ámbito de las herramientas. Un subagente puede configurarse con una lista de herramientas más reducida que los permisos del propio agente principal.
---
name: codebase-researcher
description: Investigación de solo lectura sobre cómo se implementa una característica específica
tools: Read, Grep, Glob
---
Investigas cómo se implementa una característica nombrada en la base de código y
informas las rutas de archivo y una breve descripción de cada una, en menos de 300 palabras.Esa línea tools es una restricción real, no una sugerencia. Un subagente definido de esta manera no puede llamar a Edit o Write, sin importar cómo esté redactado su prompt de tarea, porque esas herramientas simplemente no están en su conjunto disponible para esa invocación. Esto es lo que convierte el "aislamiento" de una conveniencia en un límite de seguridad real.
Cuando el agente principal invoca varios subagentes a la vez, cada uno obtiene su propio contexto independiente, que es exactamente lo que hace que ejecutarlos en paralelo sea seguro. Dos subagentes que investigan subsistemas diferentes no pueden leer o basarse accidentalmente en los hallazgos intermedios del otro, porque ninguno tiene acceso al contexto del otro en primer lugar.
Consideraciones Avanzadas y Aplicaciones
El modelo de aislamiento tiene compensaciones reales, y tratarlo como gratuito llevaría a un uso excesivo de subagentes.
Invocar un subagente tiene un costo de latencia: iniciar un nuevo contexto, ejecutar la tarea y reportar es más lento que continuar directamente en la sesión principal para una tarea pequeña y bien definida. Una búsqueda de una línea no necesita un subagente; una exploración de cuarenta pasos generalmente sí.
El aislamiento también significa que un subagente puede perder el acceso a los matices que la sesión principal ha desarrollado a lo largo de una conversación larga. Si el agente principal ha estado depurando un problema sutil durante veinte turnos e invoca un subagente para verificar una hipótesis, el subagente solo sabe lo que el prompt de tarea del agente principal le dice, no los veinte turnos de contexto acumulado. Escribir un prompt de tarea que incluya lo suficiente de ese contexto, sin pegar la conversación completa, es una habilidad real, y subespecificarlo es una de las formas más comunes en que el informe de un subagente resulta menos útil de lo esperado.
También hay un ángulo de gobernanza que vale la pena nombrar explícitamente. Dado que el ámbito de las herramientas se aplica por subagente, un proyecto puede definir roles de subagente especializados: un investigador estrictamente de solo lectura, un ejecutor de pruebas con acceso a comandos de prueba pero no a ediciones de código fuente, un redactor de documentación limitado a archivos markdown solamente, cada uno con permisos ajustados a su trabajo real. Esa es una postura de seguridad significativamente diferente a la de una sola sesión con acceso amplio y uniforme que realiza todo tipo de tareas.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Trabajar directamente en la sesión principal | Sin sobrecarga de latencia, contexto completo en ejecución disponible | Cada paso exploratorio consume el presupuesto de contexto compartido | Tareas pequeñas y rápidas estrechamente vinculadas a la conversación en curso |
| Invocar un subagente | Mantiene la exploración fuera del contexto principal, puede reducir el ámbito de las herramientas | Añade latencia, el subagente comienza con contexto mínimo | Una investigación acotada o una tarea aislada con un entregable claro |
| Invocar varios subagentes en paralelo | El trabajo independiente ocurre concurrentemente, sin contaminación cruzada | Sobrecarga de coordinación, el agente principal debe sintetizar múltiples informes | Múltiples subtareas genuinamente independientes (por ejemplo, auditar subsistemas separados) |
Conceptos Erróneos Comunes
- "Un subagente tiene acceso a toda la conversación hasta el momento, solo que en una ventana separada." No lo tiene. Su contexto comienza esencialmente vacío, alimentado solo por el prompt de tarea que el agente principal escribe; todo lo que el agente principal no incluye explícitamente es invisible para el subagente.
- "Limitar el ámbito de las herramientas de un subagente es solo una cortesía organizativa." Es una restricción impuesta. Un subagente sin
Editen su lista de herramientas genuinamente no puede editar archivos, independientemente de cómo esté redactado su prompt o de cómo se le pida. - "Los subagentes comparten el mismo presupuesto de contexto, solo que dividido." Cada subagente obtiene su propia ventana de contexto independiente; invocar tres subagentes no divide un presupuesto compartido entre tres, sino que crea tres separados.
- "Usar un subagente es siempre más eficiente que hacer el trabajo directamente." Para una tarea pequeña, la sobrecarga de configuración y reporte de un subagente puede costar más que hacer el trabajo en la sesión principal; el aislamiento se amortiza una vez que la tarea es lo suficientemente grande o independiente como para justificarlo.
- "Un subagente puede volver libremente y pedir más contexto al agente principal a mitad de la tarea." Un subagente generalmente opera sobre el prompt de tarea que se le dio por adelantado y reporta una vez; no tiene un canal abierto para consultar interactivamente a la sesión principal mientras trabaja.
Preguntas Frecuentes
¿Con qué empieza realmente el contexto de un subagente?
- Solo con el prompt de tarea que la sesión principal escribió al invocarlo.
- Sin historial de conversación previo del agente principal, a menos que se incluya explícitamente en ese prompt de tarea.
- Sin memoria de ningún otro subagente que pueda estar ejecutándose en paralelo.
¿Puede un subagente usar cualquier herramienta que la sesión principal pueda usar?
No necesariamente. La lista de herramientas de un subagente puede configurarse de forma más reducida que la del agente principal, y cualquier herramienta que no esté en esa lista simplemente no está disponible para él, independientemente de lo que pida la tarea.
¿Ve la sesión principal todo lo que hizo el subagente mientras trabajaba?
No. El agente principal solo recibe el resumen que el subagente reporta al final; las lecturas de archivos individuales, búsquedas y pasos de razonamiento intermedios del subagente no se muestran al agente principal.
¿Por qué el aislamiento es importante para ejecutar varios subagentes en paralelo?
Debido a que el contexto de cada subagente es independiente, su investigación no puede contaminarse mutuamente. Dos subagentes que investigan subsistemas separados no influirán accidentalmente en los hallazgos del otro, ya que ninguno tiene visibilidad del trabajo del otro.
¿Limitar el ámbito de las herramientas de un subagente es principalmente por conveniencia o por seguridad?
Ambos, pero el aspecto de seguridad es real, no cosmético. Un subagente limitado a herramientas de solo lectura no puede hacer una edición incluso si su prompt está redactado para intentar convencerlo de hacerlo, porque la herramienta no está disponible para ser llamada.
¿Invocar un subagente cuesta algo además del beneficio del aislamiento?
Sí, principalmente latencia. Iniciar un nuevo contexto y esperar a que el subagente complete su tarea y reporte lleva más tiempo que continuar directamente en la sesión principal, lo que es importante para tareas pequeñas.
¿Qué sucede si un prompt de tarea para un subagente es demasiado vago?
El subagente no tiene nada más en lo que basarse, por lo que un prompt de tarea vago o insuficientemente especificado tiende a producir un informe vago o incompleto, ya que el subagente no puede inferir el contexto faltante de una conversación que nunca vio.
¿Puede un subagente invocar sus propios subagentes?
El mecanismo existe en la arquitectura subyacente, pero en la práctica la mayoría de los flujos de trabajo mantienen la invocación de subagentes a un solo nivel, delegada desde la sesión principal, para evitar acumular latencia y complejidad de coordinación.
¿Es la ventana de contexto aislada de un subagente del mismo tamaño que la de la sesión principal?
El mecanismo es el mismo tipo de ventana de contexto, pero como comienza casi vacía, un subagente típicamente tiene mucho más margen disponible para su tarea específica que la sesión principal a mitad de una conversación larga.
¿Cómo decide el agente principal cuándo invocar un subagente en lugar de hacer el trabajo directamente?
- La tarea es exploratoria y generaría muchos detalles intermedios que no vale la pena mantener en el contexto principal.
- La tarea debe ejecutarse con un acceso a herramientas más limitado que el que tiene la sesión actual.
- La tarea es lo suficientemente independiente como para ejecutarse en paralelo con otros trabajos.
¿El aislamiento significa que un subagente nunca puede afectar los archivos reales de la sesión principal?
No. Un subagente con Edit o Write en su lista de herramientas aún puede modificar archivos; el aislamiento se refiere al contexto y al ámbito de permisos, no a si puede actuar sobre la misma base de código en la que está trabajando el agente principal.
Relacionado
- Comandos, Hooks y Subagentes Personalizados: Para Qué Sirve Cada Uno - cómo los subagentes se diferencian de los comandos y hooks.
- Fundamentos de Comandos y Subagentes Personalizados - una primera invocación práctica de un subagente.
- Invocación de Subagentes Paralelos para Tareas de Investigación Aisladas - poner el aislamiento a trabajar en varios subagentes a la vez.
- Subagentes vs. el SDK de Agentes: Cómo se Construye Claude Code - los primitivos subyacentes sobre los que se construye este modelo de aislamiento.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.